Как создавать федеративный клиент

Статья
02/28/2011

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

Настройте wsFederationHttpBinding element или аналогичную пользовательскую привязку. Дополнительные сведения создании соответствующей привязки см. в разделе Как создать WSFederationHttpBinding. Можно также запустить Служебное средство ServiceModel Metadata Utility Tool (Svcutil.exe) для конечной точки метаданных федеративной службы, чтобы создать файл конфигурации для взаимодействия с этой федеративной службой и одной или несколькими службами маркеров безопасности.
Задайте свойства IssuedTokenClientCredential, управляющие различными аспектами взаимодействия клиента со службой маркеров безопасности.
Задайте свойства X509CertificateRecipientClientCredential, разрешающие сертификаты, необходимые для безопасного обмена данными с определенными конечными точками, такими как служба маркеров безопасности.

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

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

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

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

Запустите Служебное средство ServiceModel Metadata Utility Tool (Svcutil.exe) с URL-адресом метаданных службы в качестве параметра командной строки.
Откройте созданный файл конфигурации в подходящем редакторе.
Изучите атрибуты и содержимое всех созданных элементов <issuer> и <issuerMetadata>. Они находятся в элементах <security> для <wsFederationHttpBinding> или в элементах пользовательских привязок. Убедитесь, что адреса содержат ожидаемые имена доменов или другую адресную информацию. Важно проверить эту информацию, так как клиент проверяет свою подлинность по этим адресам, и возможно раскрытие такой информации, как пары "имя пользователя-пароль". Если адреса отличаются от ожидаемых, это может привести к передаче информации неправильному получателю.

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

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

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

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

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

Получите доступ к IssuedTokenClientCredential через свойство IssuedToken класса ClientCredentials (возвращается свойством ClientCredentials класса ClientBase или через класс ChannelFactory), как показано в следующем примере кода.
```
Dim itcc As IssuedTokenClientCredential = client.ClientCredentials.IssuedToken
```
```
IssuedTokenClientCredential itcc = client.ClientCredentials.IssuedToken;
```
Если кэширование маркера не требуется, установите для свойства CacheIssuedTokens значение false. Свойство CacheIssuedTokens определяет, будут ли кэшироваться такие маркеры, полученные от службы маркеров безопасности. Если для этого свойства задано значение false, клиент запрашивает новый маркер у службы маркеров безопасности каждый раз, когда ему требуется заново подтвердить свою подлинность в федеративной службе, независимо от того, действует ли еще предыдущий маркер. Если для этого свойства задано значение true, клиент повторно использует существующий маркер, когда ему требуется заново подтвердить свою подлинность в федеративной службе (до тех пор, пока не истечет срок действия этого маркера). Значение по умолчанию — true.
Если для кэшированных маркеров требуется ограничение по времени, задайте для свойства MaxIssuedTokenCachingTime значение TimeSpan. Это свойство указывает, как долго маркер может оставаться в кэше. По истечении указанного времени маркер удаляется из кэша клиента. По умолчанию время нахождения маркеров в кэше не ограничено. В следующем примере задается промежуток времени 10 минут.
```
itcc.MaxIssuedTokenCachingTime = New TimeSpan(0, 10, 0)
```
```
itcc.MaxIssuedTokenCachingTime = new TimeSpan(0, 10, 0);
```
Необязательно. Задайте для IssuedTokenRenewalThresholdPercentage значение в процентах. По умолчанию используется значение 60 процентов. Это свойство задается в процентах от срока действия маркера. Например, если срок действия выданного маркера составляет 10 часов, и для параметра IssuedTokenRenewalThresholdPercentage задано значение 80, маркер обновляется через 8 часов. В следующем примере задается значение 80 процентов.
```
itcc.IssuedTokenRenewalThresholdPercentage = 80
```
```
itcc.IssuedTokenRenewalThresholdPercentage = 80;
```
Интервал обновления, заданный сроком действия маркера и значением IssuedTokenRenewalThresholdPercentage, заменяется значением MaxIssuedTokenCachingTime, если время кэширования меньше порогового времени обновления. Например, если произведение IssuedTokenRenewalThresholdPercentage и срока действия маркера равно восьми часам, а значение MaxIssuedTokenCachingTime равно 10 минутам, клиент обращается в службу маркеров безопасности за обновленным маркером каждые 10 минут.

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

itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy

itcc.DefaultKeyEntropyMode = SecurityKeyEntropyMode.ServerEntropy;

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

Настройте все поведения конечных точек, специфичных для издателя, добавив эти поведения в коллекцию, возвращаемую свойством IssuerChannelBehaviors.
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior)
```
```
itcc.LocalIssuerChannelBehaviors.Add(myEndpointBehavior);
```

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

Создайте элемент <issuedToken> как дочерний элемент элемента <clientCredentials> в поведении конечной точки.
Если кэширование маркера не требуется, установите для атрибута cacheIssuedTokens (элемента <issuedToken>) значение false.
Так как для кэшированных маркеров требуется ограничение по времени, задайте для атрибута maxIssuedTokenCachingTime элемента <issuedToken> соответствующее значение. Например:
<issuedToken maxIssuedTokenCachingTime='00:10:00' />
Если требуется значение, отличное от значения по умолчанию, задайте для атрибута issuedTokenRenewalThresholdPercentage элемента <issuedToken> соответствующее значение, например:
```
<issuedToken issuedTokenRenewalThresholdPercentage = "80" />
```
Если для привязки, не использующей безопасность сообщений или безопасность транспорта с учетными данными сообщения (например, в привязке отсутствует элемент SecurityBindingElement), требуется режим энтропии ключа, отличный от CombinedEntropy, задайте для атрибута defaultKeyEntropyMode элемента <issuedToken> требуемое значение ServerEntropy или ClientEntropy.
```
<issuedToken defaultKeyEntropyMode = "ServerEntropy" />
```
Необязательно. Настройте все поведения пользовательской конечной точки, специфичной для издателя, создав элемент <issuerChannelBehaviors> как дочерний элемент элемента <issuedToken>. Для каждого поведения создайте элемент <add> в качестве дочернего элемента элемента <issuerChannelBehaviors>. Укажите адрес издателя для поведения, задав атрибут issuerAddress элемента <add>. Укажите само поведение, задав атрибут behaviorConfiguration элемента <add>.
```
<issuerChannelBehaviors>
<add issuerAddress="http://fabrikam.org/sts" behaviorConfiguration="FabrikamSTS" />
</issuerChannelBehaviors>
```

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

Обратитесь к X509CertificateRecipientClientCredential через свойство ServiceCertificate свойства ClientCredentials класса ClientBase или свойство ChannelFactory.
```
Dim rcc As X509CertificateRecipientClientCredential = _
client.ClientCredentials.ServiceCertificate
```
```
X509CertificateRecipientClientCredential rcc =
    client.ClientCredentials.ServiceCertificate;
```
Если для сертификата для определенной конечной точки имеется экземпляр X509Certificate2, используйте метод Add коллекции, возвращаемой свойством ScopedCertificates.
```
rcc.ScopedCertificates.Add(New Uri("https://fabrikam.com/sts"), cert)
```
```
rcc.ScopedCertificates.Add(new Uri("https://fabrikam.com/sts"), cert);
```

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

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

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

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

Создайте элемент <scopedCertificates>, являющийся дочерним для элемента <serviceCertifcate>, который в свою очередь является дочерним для элемента <clientCredentials> в поведении конечной точки.
Создайте элемент <add>, являющийся дочерним для элемента <scopedCertificates>. Задайте значения атрибутов storeLocation, storeName, x509FindType и findValue, указывающие на соответствующий сертификат. Задайте для атрибута targetUri значение, предоставляющее адрес конечной точки, для которой предназначен сертификат, как показано в следующем примере.
```
<scopedCertificates>
 <add targetUri="https://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("ChannelFactory");
    }
    // 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 DefaulyKeyEntropyMode property
    cf.Credentials.IssuedToken.DefaultKeyEntropyMode = entropyMode;
}

Безопасность

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

Требуется LocalIssuer

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

Дополнительные сведения задании свойств LocalIssuerAddress, LocalIssuerBinding и LocalIssuerChannelBehaviors класса IssuedTokenClientCredential см. в разделе Как настраивать локальный издатель.

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

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

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

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

См. также

Задачи

Образец федерации
Как упорядочить отключения безопасных сеансов в WSFederationHttpBinding
Как создать WSFederationHttpBinding
Как настраивать учетные данные службы федерации
Как настраивать локальный издатель
How to: Secure Metadata Endpoints

Основные понятия

Security Considerations with Metadata

Поделиться через