Практическое руководство. Создание федеративного клиента

В Windows Communication Foundation (WCF) создание клиента для федеративной службы состоит из трех основных этапов:

1. Настройте настраиваемую привязку <wsFederationHttpBinding> или аналогичную пользовательскую привязку. Дополнительные сведения о создании соответствующей привязки см. в статье "Практическое руководство. Создание WSFederationHttpBinding". Кроме того, запустите средство служебной программы метаданных ServiceModel (Svcutil.exe) для конечной точки метаданных федеративной службы, чтобы создать файл конфигурации для взаимодействия с федеративной службой и одной или несколькими службами маркеров безопасности.

2. Задайте свойства IssuedTokenClientCredential, управляющие различными аспектами взаимодействия клиента со службой маркеров безопасности.

3. Задайте свойства X509CertificateRecipientClientCredential, разрешающие сертификаты, необходимые для безопасного обмена данными с определенными конечными точками, такими как служба маркеров безопасности.

Примечание.

Исключение CryptographicException может возникнуть, если клиент использует олицетворенные учетные данные, привязку WSFederationHttpBinding или выданный пользовательский маркер и асимметричные ключи. Асимметричные ключи используются с привязкой WSFederationHttpBinding и выданными пользовательскими маркерами, если для свойств IssuedKeyType и KeyType соответственно задано значение AsymmetricKey. Исключение CryptographicException возникает, когда клиент пытается отправить сообщение, а для идентификации, которую олицетворяет клиент, отсутствует профиль пользователя. Чтобы подавить эту проблему, перед отправкой сообщения войдите в систему на клиентском компьютере или вызовите метод LoadUserProfile.

В этом разделе приведены подробные сведения об этих процедурах. Дополнительные сведения о создании соответствующей привязки см. в статье "Практическое руководство. Создание WSFederationHttpBinding". Дополнительные сведения о том, как работает федеративная служба, см. в статье "Федерация".

Создание и проверка конфигурации для федеративной службы

1. Запустите средство служебной программы метаданных ServiceModel (Svcutil.exe) с адресом URL-адреса метаданных службы в качестве параметра командной строки.

2. Откройте созданный файл конфигурации в подходящем редакторе.

3. Проверьте атрибуты и содержимое всех созданных <издателей> и <элементов issuerMetadata> . Они находятся в элементах безопасности для элементов безопасности> для <элементов wsFederationHttpBinding> или пользовательских привязок.< Убедитесь, что адреса содержат ожидаемые имена доменов или другую адресную информацию. Важно проверить эту информацию, так как клиент проверяет свою подлинность по этим адресам, и возможно раскрытие такой информации, как пары "имя пользователя-пароль". Если адреса отличаются от ожидаемых, это может привести к передаче информации неправильному получателю.

4. Проверьте все дополнительные <выданные элементыTokenParameters> внутри закомментированного элемента.<alternativeIssuedTokenParameters> Если при использовании средства Svcutil.exe для создания конфигурации для федеративной службы эта федеративная служба или любая промежуточная служба маркеров безопасности указывает не адрес издателя, а адрес метаданных для службы маркеров безопасности с несколькими конечными точками, получающийся файл конфигурации ссылается на первую конечную точку. Дополнительные конечные точки находятся в файле конфигурации в виде закомментированных <alternativeIssuedTokenParameters> элементов.

   Определите, предпочтительнее ли одно из них <issuedTokenParameters> уже присутствует в конфигурации. Например, клиент может предпочесть пройти проверку подлинности в службе маркеров безопасности с помощью маркера Windows CardSpace, а не пары имени пользователя или пароля.

   Примечание.

   Если перед началом взаимодействия со службой необходимо пройти через несколько служб маркеров безопасности, промежуточная служба маркеров безопасности может направить клиента в неправильную службу маркеров безопасности. Поэтому убедитесь, что конечная точка для службы маркеров безопасности в <выданныхTokenParameters> является ожидаемой службой маркеров безопасности, а не неизвестной службой маркеров безопасности.

Настройка IssuedTokenClientCredential в коде

1. Получите доступ к IssuedTokenClientCredential через свойство IssuedToken класса ClientCredentials (возвращается свойством ClientCredentials класса ClientBase<TChannel> или через класс ChannelFactory), как показано в следующем примере кода.

   IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
   

   Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
   

2. Если кэширование маркера не требуется, установите для свойства CacheIssuedTokens значение false. Свойство CacheIssuedTokens определяет, будут ли кэшироваться такие маркеры, полученные от службы маркеров безопасности. Если для этого свойства задано значение false, клиент запрашивает новый маркер у службы маркеров безопасности каждый раз, когда ему требуется заново подтвердить свою подлинность в федеративной службе, независимо от того, действует ли еще предыдущий маркер. Если для этого свойства задано значение true, клиент повторно использует существующий маркер, когда ему требуется заново подтвердить свою подлинность в федеративной службе (до тех пор, пока не истечет срок действия этого маркера). Значение по умолчанию — true.

3. Если для кэшированных маркеров требуется ограничение по времени, задайте для свойства MaxIssuedTokenCachingTime значение TimeSpan. Это свойство указывает, как долго маркер может оставаться в кэше. По истечении указанного времени маркер удаляется из кэша клиента. По умолчанию время нахождения маркеров в кэше не ограничено. В следующем примере задается промежуток времени 10 минут.

   itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);
   

   itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)
   

4. Необязательно. Задайте для IssuedTokenRenewalThresholdPercentage значение в процентах. По умолчанию используется значение 60 процентов. Это свойство задается в процентах от срока действия маркера. Например, если срок действия выданного маркера составляет 10 часов, и для параметра IssuedTokenRenewalThresholdPercentage задано значение 80, маркер обновляется через 8 часов. В следующем примере задается значение 80 процентов.

   itcc.IssuedTokenRenewalThresholdPercentage = 80;
   

   itcc.IssuedTokenRenewalThresholdPercentage = 80
   

   Интервал обновления, заданный сроком действия маркера и значением IssuedTokenRenewalThresholdPercentage, заменяется значением MaxIssuedTokenCachingTime, если время кэширования меньше порогового времени обновления. Например, если произведение IssuedTokenRenewalThresholdPercentage и срока действия маркера равно восьми часам, а значение MaxIssuedTokenCachingTime равно 10 минутам, клиент обращается в службу маркеров безопасности за обновленным маркером каждые 10 минут.

5. Если режим энтропии ключа, отличный CombinedEntropy от необходимого для привязки, которая не использует безопасность сообщений или безопасность транспорта с учетными данными сообщения (например, привязка не имеет SecurityBindingElement), задайте DefaultKeyEntropyMode для свойства соответствующее значение. Режим энтропии определяет, можно ли управлять симметричными ключами с помощью DefaultKeyEntropyMode свойства. По умолчанию используется значение CombinedEntropy, когда и клиент, и издатель маркера предоставляют данные, совместно используемые для создания фактического ключа. Также предусмотрены значения ClientEntropy и ServerEntropy, которые означают, что весь ключ задается клиентом или сервером соответственно. В следующем примере свойству задается значение, означающее, что для ключа используются только данные сервера.

   itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;
   

   itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy
   

   Примечание.

   Если в привязке службы маркеров безопасности или службы присутствует элемент SecurityBindingElement, параметр DefaultKeyEntropyMode со значением IssuedTokenClientCredential переопределяется свойством KeyEntropyMode элемента SecurityBindingElement.

6. Настройте все поведения конечных точек, специфичных для издателя, добавив эти поведения в коллекцию, возвращаемую свойством IssuerChannelBehaviors.

   itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);
   

   itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)
   

Настройка IssuedTokenClientCredential в конфигурации

1. Создайте выданный элементToken в качестве дочернего <элемента выданного ЭлементаToken>> в поведении конечной точки.<

2. Если кэширование маркеров не требуется, задайте cacheIssuedTokens для атрибута <issuedToken> (элемента) значение false.

3. Если для кэшированных маркеров требуется ограничение времени, задайте maxIssuedTokenCachingTime атрибут элемента <issuedToken> соответствующим значением. Например: <issuedToken maxIssuedTokenCachingTime='00:10:00' />

4. Если значение, отличное от значения по умолчанию, issuedTokenRenewalThresholdPercentage задайте атрибут для <issuedToken> элемента соответствующим значением, например:

   <issuedToken issuedTokenRenewalThresholdPercentage = "80" />
   

5. Если для привязки, не использующей безопасность сообщений или безопасность транспорта с учетными данными сообщения (например, в привязке отсутствует элемент CombinedEntropy), требуется режим энтропии ключа, отличный от SecurityBindingElement, задайте для атрибута defaultKeyEntropyMode элемента <issuedToken> требуемое значение ServerEntropy или ClientEntropy.

   <issuedToken defaultKeyEntropyMode = "ServerEntropy" />
   

6. Необязательно. Настройте любое поведение настраиваемой конечной точки для конкретного издателя, создав <issuerChannelBehaviors> элемент в качестве дочернего <issuedToken> элемента. Для каждого поведения создайте <add> элемент в качестве дочернего <issuerChannelBehaviors> элемента элемента. Укажите адрес издателя поведения, задав issuerAddress атрибут в элементе <add> . Укажите само поведение, задав behaviorConfiguration атрибут для <add> элемента.

   <issuerChannelBehaviors>
   <add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
   </issuerChannelBehaviors>
   

Настройка X509CertificateRecipientClientCredential в коде

1. Обратитесь к X509CertificateRecipientClientCredential через свойство ServiceCertificate свойства ClientCredentials класса ClientBase<TChannel> или свойство ChannelFactory.

   X509CertificateRecipientClientCredential rcc =
       client.ClientCredentials.ServiceCertificate;
   

   Dim rcc As X509CertificateRecipientClientCredential = _
   client.ClientCredentials.ServiceCertificate
   

2. Если для сертификата для определенной конечной точки имеется экземпляр X509Certificate2, используйте метод Add коллекции, возвращаемой свойством ScopedCertificates.

   rcc.ScopedCertificates.Add(new Uri("http://fabrikam.com/sts"), cert);
   

   rcc.ScopedCertificates.Add(New Uri("http://fabrikam.com/sts"), cert)
   

3. Если экземпляр X509Certificate2 отсутствует, используйте метод SetScopedCertificate класса X509CertificateRecipientClientCredential, как показано в следующем примере.

   public void snippet20(CalculatorClient client)
   {
       X509CertificateRecipientClientCredential rcc = client.ClientCredentials.ServiceCertificate;
       rcc.SetScopedCertificate(StoreLocation.CurrentUser,
                                StoreName.TrustedPeople,
                                X509FindType.FindBySubjectName,
                                "FabrikamSTS",
                                new Uri("http://fabrikam.com/sts"));
   }
   

   rcc.SetScopedCertificate(StoreLocation.CurrentUser, _
               StoreName.TrustedPeople, _
               X509FindType.FindBySubjectName, _
               "FabrikamSTS", _
               New Uri("http://fabrikam.com/sts"))
   

Настройка X509CertificateRecipientClientCredential в конфигурации

1. Создайте элемент scopedCertificates> в качестве дочернего <элемента serviceCertificate>, который является дочерним <элементом элемента clientCredentials> в поведении конечной точки.<

2. Создайте элемент <add>, являющийся дочерним для элемента <scopedCertificates>. Задайте значения атрибутов storeLocation, storeName, x509FindType и findValue, указывающие на соответствующий сертификат. Задайте для атрибута targetUri значение, предоставляющее адрес конечной точки, для которой предназначен сертификат, как показано в следующем примере.

   <scopedCertificates>
    <add targetUri="http://fabrikam.com/sts"
         storeLocation="CurrentUser"
         storeName="TrustedPeople"
         x509FindType="FindBySubjectName"
         findValue="FabrikamSTS" />
   </scopedCertificates>
   

Пример

В следующем примере кода экземпляр класса IssuedTokenClientCredential настраивается в коде.

// This method configures the IssuedToken property of the Credentials property of a proxy/channel factory
public static void ConfigureIssuedTokenClientCredentials(ChannelFactory cf, bool cacheTokens,
                                                          TimeSpan tokenCacheTime, int renewalPercentage,
                                                          SecurityKeyEntropyMode entropyMode
                                                          )
{
    if (cf == null)
    {
        throw new ArgumentNullException("cf");
    }
    // Set the CacheIssuedTokens property
    cf.Credentials.IssuedToken.CacheIssuedTokens = cacheTokens;

    // Set the MaxIssuedTokenCachingTime property
    cf.Credentials.IssuedToken.MaxIssuedTokenCachingTime = tokenCacheTime;

    // Set the IssuedTokenRenewalThresholdPercentage property
    cf.Credentials.IssuedToken.IssuedTokenRenewalThresholdPercentage = renewalPercentage;

    // Set the DefaultKeyEntropyMode property
    cf.Credentials.IssuedToken.DefaultKeyEntropyMode = entropyMode;
}

' This method configures the IssuedToken property of the Credentials property of a proxy/channel factory
Public Shared Sub ConfigureIssuedTokenClientCredentials(ByVal cf As ChannelFactory, _
                                                        ByVal cacheTokens As Boolean, _
                                                        ByVal tokenCacheTime As TimeSpan, _
                                                        ByVal renewalPercentage As Integer, _
                                                        ByVal entropyMode As SecurityKeyEntropyMode)
    If cf Is Nothing Then
        Throw New ArgumentNullException("ChannelFactory")
    End If
    ' Set the CacheIssuedTokens property
    With cf.Credentials.IssuedToken
        .CacheIssuedTokens = cacheTokens

        ' Set the MaxIssuedTokenCachingTime property
        .MaxIssuedTokenCachingTime = tokenCacheTime

        ' Set the IssuedTokenRenewalThresholdPercentage property
        .IssuedTokenRenewalThresholdPercentage = renewalPercentage

        ' Set the DefaultKeyEntropyMode property
        .DefaultKeyEntropyMode = entropyMode
    End With
End Sub

Безопасность .NET Framework

Для исключения возможного раскрытия информации клиенты, запускающие средство Svcutil.exe для обработки метаданных от федеральных конечных точек, должны проверять, что получающиеся адреса служб маркеров безопасности соответствуют ожидаемым. Это особенно важно, если служба маркеров безопасности предоставляет несколько конечных точек, так как средство Svcutil.exe задает в создаваемом файле конфигурации первую такую конечную точку, которая может отличаться от конечной точки, которую должен использовать клиент.

Требуется LocalIssuer

Если требуется, чтобы клиенты всегда использовали локального издателя, обратите внимание на следующее: выходные данные средства Svcutil.exe по умолчанию задают, что локальный издатель не используется, если в предпоследней службе маркеров безопасности в цепочке указан адрес издателя или адрес метаданных издателя.

Дополнительные сведения о настройке LocalIssuerAddressи LocalIssuerBindingLocalIssuerChannelBehaviors свойствах класса см. в статье "Практическое руководство. Настройка локального IssuedTokenClientCredential издателя".

Сертификаты с областью действия

Если требуется задать сертификаты службы для взаимодействия с любыми службами маркеров безопасности (обычно в связи с тем, что не используется согласование сертификатов), их можно задать с помощью свойства ScopedCertificates класса X509CertificateRecipientClientCredential. Метод SetDefaultCertificate принимает в качестве параметров Uri и X509Certificate2. Указанный сертификат используется при взаимодействии с конечными точками по указанному универсальному коду ресурса (URI). В качестве альтернативы можно с помощью метода SetScopedCertificate добавить сертификат в коллекцию, возвращаемую свойством ScopedCertificates.

Примечание.

Концепция сертификатов клиента, область действия которых ограничена только определенным универсальным кодом ресурса (URI), применима только к приложениям, производящим исходящие вызовы служб, предоставляющих конечные точки по этим универсальным кодам ресурса (URI). Он не применяется к сертификатам, которые используются для подписывания выданных маркеров, таких как настроенные на сервере в коллекции, возвращаемой классом KnownCertificates IssuedTokenServiceCredential . Дополнительные сведения см. в разделе "Практическое руководство. Настройка учетных данных в службе федерации".

См. также

• Пример федерации
• Практическое руководство. Порядок отключения безопасных сеансов в WSFederationHttpBinding
• Практическое руководство. Создание WSFederationHttpBinding
• Практическое руководство. Настройка учетных данных службы федерации
• Практическое руководство. Настройка локального издателя
• Вопросы безопасности при использовании метаданных
• Практическое руководство. Защита конечных точек метаданных