如何：创建联合客户端

  • 项目

在 Windows Communication Foundation (WCF) 中，创建联合服务**的客户端包括三个主要步骤：

  1. 配置 wsFederationHttpBinding element或类似的自定义绑定。有关 创建适当绑定的更多信息，请参见如何：创建 WSFederationHttpBinding。或者，也可以针对联合服务的元数据终结点运行 ServiceModel Metadata Utility Tool (Svcutil.exe) 以生成一个配置文件，以便用于与联合服务以及一个或多个安全令牌服务进行通信。
  2. 设置 IssuedTokenClientCredential 的属性，它可以控制客户端与安全令牌服务之间交互的各个方面。
  3. 设置 X509CertificateRecipientClientCredential 的属性，它允许使用所需的证书来与给定终结点（例如安全令牌服务）进行安全通信。

提示

当客户端使用模拟凭据、WSFederationHttpBinding 绑定或自定义颁发令牌以及非对称密钥时，可能会引发 CryptographicException。当将 IssuedKeyType 和 KeyType 属性分别设置为 AsymmetricKey 时，将非对称密钥与 WSFederationHttpBinding 绑定和自定义颁发令牌一起使用。当客户端尝试发送消息，而客户端模拟的标识不存在对应的用户配置文件时，将引发 CryptographicException。若要缓解此问题，请在发送消息之前登录客户端计算机或调用 LoadUserProfile。

本主题提供有关这些过程的详细信息。有关 创建适当的绑定的信息，请参见如何：创建 WSFederationHttpBinding。有关 联合服务如何工作的更多信息，请参见联合。

生成并检查联合服务的配置

  1. 使用服务的元数据 URL 地址作为命令行参数来运行 ServiceModel Metadata Utility Tool (Svcutil.exe)。

  2. 在适当的编辑器中打开生成的配置文件。

  3. 检查任何生成的 <issuer> 和 <issuerMetadata> 元素的属性和内容。这些元素位于 <wsFederationHttpBinding> 的 <security> 元素或自定义绑定元素内。确保地址包含所需的域名或其他地址信息。一定要检查此信息，因为客户端将对这些地址进行身份验证，可能会泄露信息（例如用户名/密码对）。如果地址不是预期的地址，则会导致将信息泄漏给非目标接收方。

  4. 在注释掉的 <alternativeIssuedTokenParameters> 元素内检查任何其他的 <issuedTokenParameters> 元素。当使用 Svcutil.exe 工具生成联合服务的配置时，如果联合服务或任何中间安全令牌服务没有指定颁发者地址，而是指定公开了多个终结点的安全令牌服务的元数据地址，则生成的配置文件将引用第一个终结点。其他终结点将在配置文件中作为注释掉的 <alternativeIssuedTokenParameters> 元素。

    确定这些 <issuedTokenParameters> 中是否有一个适合于已在配置中存在的元素。例如，客户端可能倾向于使用 Windows CardSpace 令牌而非用户名/密码对来对安全令牌服务进行身份验证。

    提示

    对于在与服务进行通信之前必须遍历多个安全令牌服务的情况，中间安全令牌服务有可能会将客户端引导到不正确的安全令牌服务。因此，请确保 <issuedTokenParameters> 中的安全令牌服务的终结点是预期的安全令牌服务，并且不是未知的安全令牌服务。

在代码中配置 IssuedTokenClientCredential

  1. 通过 ClientCredentials 类的 IssuedToken 属性（通过 ClientBase 类的 ClientCredentials 属性或通过 ChannelFactory 类返回）访问 IssuedTokenClientCredential，如以下示例代码中所示。

  2. 如果不需要缓存令牌，则将 CacheIssuedTokens 属性设置为 false。CacheIssuedTokens 属性控制是否缓存安全令牌服务中的这类令牌。如果将此属性设置为 false，则只要客户端必须向联合服务对自己重新进行身份验证，客户端就会从安全令牌服务请求一个新令牌，而不管上一个令牌是否仍然有效。如果将此属性设置为 true，则只要客户端必须向联合服务对自己重新进行身份验证，客户端就会重用现有的令牌（只要令牌未过期）。默认值为 true。

  3. 如果缓存令牌需要一个时间限制，则将 MaxIssuedTokenCachingTime 属性设置为 TimeSpan 值。该属性指定可以缓存令牌的时间。在指定的时间间隔结束之后，将从客户端缓存中移除令牌。默认情况下，缓存令牌的时间将不限。下面的示例将时间间隔设置为 10 分钟。

  4. 可选。将 IssuedTokenRenewalThresholdPercentage 设置为一个百分比。默认值为 60（百分比）。该属性指定令牌有效期的百分比。例如，如果颁发的令牌在 10 个小时内有效，并将 IssuedTokenRenewalThresholdPercentage 设置为 80，则在 8 小时后续订令牌。下面的示例将值设置为 80％。

    在缓存时间少于续订阈值时间的情况下，MaxIssuedTokenCachingTime 值将重写通过令牌有效期和 IssuedTokenRenewalThresholdPercentage 值确定的续订时间间隔。例如，如果 IssuedTokenRenewalThresholdPercentage 与令牌持续时间的乘积是 8 个小时，而 MaxIssuedTokenCachingTime 值为 10 分钟，则客户端每 10 分钟就会联系安全令牌服务以获取更新的令牌。

  5. 如果在一个绑定上需要除 CombinedEntropy 之外的密钥平均信息量模式，并且该绑定对消息凭据不使用消息安全或传输安全（例如，该绑定没有 SecurityBindingElement），则将 DefaultKeyEntropyMode 属性设置为适当的值。平均信息量**模式确定是否可以使用 DefaultKeyEntropyMode 属性来控制对称密钥。此默认值为 CombinedEntropy，其中，客户端和令牌颁发者都提供数据，并将这些数据组合在一起以生成实际密钥。其他值为 ClientEntropy 和 ServerEntropy，这意味着整个密钥由客户端或服务器分别指定。下面的示例将该属性设置为只使用服务器数据来生成密钥。

    提示

    如果在安全令牌服务或服务绑定中存在 SecurityBindingElement，则通过 SecurityBindingElement 的 KeyEntropyMode 属性来重写 IssuedTokenClientCredential 上的 DefaultKeyEntropyMode 集。

  6. 配置任何特定于颁发者的终结点行为，方法是将这些行为添加到由 IssuerChannelBehaviors 属性返回的集合中。

在配置中配置 IssuedTokenClientCredential

  1. 创建一个 <issuedToken> 元素作为终结点行为中的 <clientCredentials> 元素的子级。

  2. 如果不需要缓存令牌，则将（<issuedToken> 元素的）cacheIssuedTokens 属性设置为 false。

  3. 如果缓存令牌需要一个时间限制，则将 <issuedToken> 元素上的 maxIssuedTokenCachingTime 属性设置为一个适当的值。例如：
    <issuedToken maxIssuedTokenCachingTime='00:10:00' />

  4. 如果需要使用默认值之外的值，则将 <issuedToken> 元素上的 issuedTokenRenewalThresholdPercentage 属性设置为一个适当的值，例如：

    <issuedToken issuedTokenRenewalThresholdPercentage = "80" />

  5. 如果在一个绑定上需要除 CombinedEntropy 之外的密钥平均信息量模式，并且该绑定对消息凭据不使用消息安全或传输安全（例如，该绑定没有 SecurityBindingElement），则根据需要将 <issuedToken> 元素上的 defaultKeyEntropyMode 属性设置为 ServerEntropy 或 ClientEntropy。

    <issuedToken defaultKeyEntropyMode = "ServerEntropy" />

  6. 可选。配置任何特定于颁发者的自定义终结点行为，方法是创建一个 <issuerChannelBehaviors> 元素作为 <issuedToken> 元素的子级。对于每个行为，创建一个 <add> 元素作为 <issuerChannelBehaviors> 元素的子级。通过设置 <add> 元素上的 issuerAddress 属性，指定行为的颁发者地址。通过设置 <add> 元素上的 behaviorConfiguration 属性，指定行为本身。

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

在代码中配置 X509CertificateRecipientClientCredential

  1. 通过 ClientBase 类的 ClientCredentials 属性的 ServiceCertificate 属性或 ChannelFactory 属性来访问 X509CertificateRecipientClientCredential。

  2. 如果 X509Certificate2 实例可用于给定终结点的证书，则使用通过 ScopedCertificates 属性返回的集合的 Add 方法。

  3. 如果 X509Certificate2 实例不可用，则使用 X509CertificateRecipientClientCredential 类的 SetScopedCertificate 方法，如以下示例中所示。

在配置中配置 X509CertificateRecipientClientCredential

  1. 创建一个 <scopedCertificates> 元素作为 <serviceCertifcate> 元素的子级，而后者本身是终结点行为中 <clientCredentials> 元素的子级。

  2. 创建一个 <add> 元素，作为 <scopedCertificates> 元素的子元素。指定 storeLocation、storeName、x509FindType 和 findValue 属性的值以引用适当的证书。将 targetUri 属性设置为一个值，该值提供证书所要用于的终结点的地址，如以下示例中所示。

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

示例

下面的代码示例在代码中配置 IssuedTokenClientCredential 类的实例。

安全

要防止可能的信息泄漏，运行 Svcutil.exe 工具以处理联合终结点中的元数据的客户端应确保生成的安全令牌服务地址是预期的地址。在安全令牌服务公开多个终结点时，这一点尤为重要，因为 Svcutil.exe 工具产生的最终配置文件会使用第一个此类终结点，而该终结点有可能不是客户端应在使用的那个终结点。

必需的 LocalIssuer

如果客户端始终应使用一个本地颁发者，则请注意以下事项：如果链中的倒数第二个安全令牌服务指定了一个颁发者地址或颁发者元数据地址，则 Svcutil.exe 的默认输出会导致使用的不是本地颁发者。

有关 设置 IssuedTokenClientCredential 类的 LocalIssuerAddress、LocalIssuerBinding 和 LocalIssuerChannelBehaviors 属性的更多信息，请参见如何：配置本地颁发者。

作用域证书

如果必须指定服务证书才能与任何安全令牌服务进行通信，则通常是因为没有使用证书协商，可以使用 X509CertificateRecipientClientCredential 类的 ScopedCertificates 属性来指定证书。SetDefaultCertificate 方法采用 Uri 和 X509Certificate2 作为参数。在与指定的 URI 处的终结点进行通信时将使用指定的证书。或者，可以使用 SetScopedCertificate 方法将证书添加到由 ScopedCertificates 属性返回的集合中。

提示

作用域限定为给定的 URI 的证书的客户端想法仅适用于对服务（这些服务公开这些 URI 处的终结点）进行出站调用的应用程序。此想法不适用于对颁发的令牌进行签名的证书，例如那些在服务器的由 IssuedTokenServiceCredential 类的 KnownCertificates 返回的集合中配置的证书。有关更多信息，请参见 如何：在联合身份验证服务上配置凭据。

另请参见

任务

如何：在 WSFederationHttpBinding 上禁用安全会话
如何：创建 WSFederationHttpBinding
如何：在联合身份验证服务上配置凭据
如何：配置本地颁发者
如何：保护元数据终结点

概念

元数据的安全注意事项

其他资源

Federation Sample