使用 FedUtil 建立从 WCF 信赖方服务到 STS 的信任

FedUtil.exe 随 Windows® Identity Foundation (WIF) 一起提供。 它可帮助您建立从信赖方 (RP) 应用程序到安全令牌服务 (STS) 的信任。 它提供以下功能：

• 将现有生产 STS 注册为 RP 应用程序的受信任颁发者。

• 通过提供本地 STS 来帮助开发声明感知应用程序。

• 使现有应用程序成为声明感知应用程序。

• 更新 RP 应用程序的联合元数据。

• 安排 RP 应用程序联合元数据的自动更新。

以下各节将说明如何使用 FedUtil 执行这些任务。 也可以手动执行这些任务，方法是对 RP 应用程序的 web.config 文件进行 FedUtil 所执行的更改。

使用 FedUtil 建立从 WCF RP 到 STS 的信任不同于建立从 ASP.NET RP 到 STS 的信任，因为您还必须指定要配置的服务端点，而且必须启用加密。

1. 创建本地 STS

在此练习中，您将创建一个本地 STS 以供声明感知 WCF 服务使用。 请注意，必须从 Visual Studio 内运行 FedUtil 才能执行此操作。 这对于使用非生产 STS 充分测试 WCF 应用程序非常有用。 稍后，您将了解到如何切换到使用生产 STS。

在 Visual Studio 中，打开“文件”菜单，然后选择“新建”、“网站”。 选择“声明感知 WCF 服务”。

接下来，在解决方案资源管理器中右键单击您的项目，然后选择“添加 STS 引用”：

此时将运行 FedUtil 工具。 您会看到 FedUtil 对话框，第一个页面是“欢迎使用 Federation Utility 工具”：

在此页面上，必须输入两个字段：

1. 应用程序配置位置：指定用于 WCF 服务的 web.config 文件的路径。 如果从 Visual Studio 外运行 FedUtil，或者在未打开项目的情况下从 Visual Studio 中的“工具”菜单运行它，则此字段为空。 如果通过在 Visual Studio 中右键单击项目来运行 FedUtil，则此字段已包含用于项目的 web.config 文件的路径。 web.config 文件必须已经存在，并且应处于默认状态（即与 Visual Studio 生成时一样）。 如果对同一 web.config 文件运行多次 FedUtil，FedUtil 将仅覆盖其添加到 web.config 文件的内容。

2. 应用程序 URI：指定 WCF 服务的 URI。 请注意，这是一个 .svc 文件。 如果从 Visual Studio 外运行 FedUtil，或者在未打开项目的情况下从 Visual Studio 中的“工具”菜单运行它，则此字段为空。 如果通过在 Visual Studio 中右键单击项目来运行 FedUtil，则此字段已包含用于项目的两个 URI：一个使用 localhost，而另一个则使用计算机的完全限定域名（如果有）。 在为声明配置应用程序时，可将此 URI 用作领域值。 此外，还可将其用作第一个受众 URI。 如果想要指定其他受众 URI，必须手动执行此操作。 如果该 URI 不安全（即未以“https://”开头），则您会在单击“下一步”时收到警告。

提供相应信息后，单击“下一步”。 此时将看到“应用程序信息”页面：

选择要配置的服务名称和终结点协定名称，然后单击“下一步”。 如果服务上有多个终结点，而您仅想要为某些终结点配置声明，请选择所需终结点。

在“安全令牌服务”页面中，选择“在当前解决方案中创建新的 STS 项目”：

请注意，如果从 Visual Studio 外运行 FedUtil，或者在未打开项目的情况下从 Visual Studio 中的“工具”菜单运行它，则无法使用“在当前解决方案中创建新的 STS 项目”选项。

单击“下一步”。 此时将出现“摘要”页面：

“摘要”页面显示您在“应用程序信息”对话框中输入的信息、您选择的服务和终结点、“创建新 STS”选项、应用程序请求的声明以及 FedUtil 将对应用程序配置进行的更改。

单击“完成”。

如果查看 web.config 文件，将会发现 FedUtil 已对其进行修改：

• <configuration>/<configSections> 元素现在包含对 IdentityModel 配置部分的引用：

  <section name="microsoft.identityModel" type="Microsoft.IdentityModel.Configuration.MicrosoftIdentityModelSection, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  

• 添加了以下应用程序设置：

  <appSettings> <add key="FederationMetadataLocation" value="C:\inetpub\wwwroot\ClaimsAwareService1_STS\FederationMetadata\2007-06\FederationMetadata.xml" /> </appSettings>
  

• 为所有用户授予了访问联合元数据的权限：

  <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  

• <system.Web>/<assemblies> 元素现在包含对 Microsoft.IdentityModel.dll 程序集的引用：

  <add assembly="Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
  

• 在 <system.serviceModel> 元素中，可以看到您在 FedUtil 中选择的服务现在有了新终结点：

  <services> <service name="Service" behaviorConfiguration="ServiceBehavior"> <endpoint address="https://localhost:54280/ClaimsAwareService1/Service.svc" binding="ws2007FederationHttpBinding" contract="ClaimsAwareService1.IService" bindingConfiguration="ClaimsAwareService1.IService_ws2007FederationHttpBinding" /> <!-- Service Endpoints --> <!--Commented out by FedUtil--> <!--<endpoint address="" binding="wsHttpBinding" contract="ClaimsAwareService1.IService"><identity><dns value="localhost" /></identity></endpoint>--> <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" /> </service> </services>
  

• <system.ServiceModel>/<behaviors>/<serviceBehavior>/<behavior> 元素现在包含 <federatedServiceHostConfiguration /> 元素，该元素引用的是您在 FedUtil 中选择的服务。 下面是将服务配置为声明感知服务的代码：

  <behaviors> <serviceBehaviors> <behavior name="ClaimsAwareService1.ServiceBehavior" > <!-- Behavior extension to make the service claims aware --> <federatedServiceHostConfiguration name="ClaimsAwareService1.Service" /> <!-- To avoid disclosing metadata information, set the value below to false and remove the metadata endpoint above before deployment --> <serviceMetadata  httpGetEnabled="true"/> <!-- To receive exception details in faults for debugging purposes, set the value below to true.  Set to false before deployment to avoid disclosing exception information --> <serviceDebug includeExceptionDetailInFaults="false"/> </behavior> </serviceBehaviors> </behaviors>
  

• <system.ServiceModel>/<behaviors>/<serviceBehavior>/<behavior> 元素还包含 <serviceCredentials> 元素，该元素引用的是本地计算机上的测试证书。

  <serviceCredentials> <!--Certificate added by FedUtil.  Subject='CN=DefaultApplicationCertificate', Issuer='CN=DefaultApplicationCertificate'.--> <serviceCertificate findValue="48BF03FCEDA703DE09E0F1F0CEFED60BB92B3DD8" storeLocation="LocalMachine" storeName="My" x509FindType="FindByThumbprint" /> </serviceCredentials>
  

• <system.serviceModel> 元素现在包含 <bindings> 元素，该元素用于列出 WCF 服务需要的声明：

  <bindings> <ws2007FederationHttpBinding> <binding name="ClaimsAwareService1.IService_ws2007FederationHttpBinding"> <security mode="Message"> <message> <issuerMetadata address="https://localhost:54908/ClaimsAwareService1_STS/Service.svc/mex" /> <claimTypeRequirements> <!--Following are the claims offered by STS 'https://localhost:54908/ClaimsAwareService1_STS/Service.svc'. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" isOptional="true" /> <add claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" isOptional="true" /> </claimTypeRequirements> </message> </security> </binding> </ws2007FederationHttpBinding> </bindings>
  

• 最后，<configuration> 元素包含 Microsoft.IdentityModel 的配置部分，其中将本地 STS 指定为受信任令牌提供方：

  <microsoft.identityModel> <service name="ClaimsAwareService1.Service"> <audienceUris> <add value="https://localhost:54904/ClaimsAwareService1/Service.svc" /> </audienceUris> <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"> <trustedIssuers> <add thumbprint="0E2A9EB75F1AFC321790407FA4B130E0E4E223E2" name="CN=STSTestCert" /> </trustedIssuers> </issuerNameRegistry> </service> </microsoft.identityModel>
  

  添加了 <issuerNameRegistry>/<trustedIssuers> 元素，用于指定 STS 在对其所颁发的令牌进行签名时使用的证书。 STS 将使用默认证书来签署其所生成的令牌。 此证书的名称为“STSTestCert”，系统已自动将该证书添加到您的证书存储区以供 STS 使用。 该证书文件存在于 STS 项目中。 该文件的密码为“STSTest”。 在生产练习中，不应使用此密码。 您可以将默认证书替换为任何其他证书。 请确保 IIS 进程的用户有权访问任何此类证书的私钥。 还可以选择创建从 IssuerNameRegistry 派生的类型，以通过编程方式对受信任颁发者的证书进行验证。

此外，如果查看解决方案资源管理器，将会看到 FedUtil 已向您的解决方案添加一个新项目。 此项目为本地 STS。 另请注意，依赖方应用程序和本地 STS 中都添加了一个联合元数据文档。

2. 注册现有生产 STS

在此练习中，您将对声明感知 WCF 服务使用经过加密的生产 STS。 请注意，与 ASP.NET 依赖方应用程序不同，WCF 服务必须使用加密。

在 Visual Studio 中，打开“文件”菜单，然后选择“新建”、“网站”。 选择 WCF 服务。 在解决方案资源管理器中右键单击您的项目，然后选择“添加 STS 引用”。 此时将运行 FedUtil 工具。 在“欢迎使用 Federation Utility 工具”页面中，确认应用程序配置位置和应用程序 URI 都正确无误，然后单击“下一步”。

在“应用程序信息”页面中，选择要配置的服务名称和终结点协定名称，然后单击“下一步”。

在“安全令牌服务”页面中，选择“使用现有 STS”：

您必须为生产 STS 指定联合元数据终结点的位置。 可以单击“测试位置”按钮以确保位置正确。 此按钮会向指定的终结点发出请求，并在默认 Web 浏览器中显示响应。 指定 STS 后，单击“下一步”。

请注意，如果指定的 STS 的证书不受本地证书存储信任，将显示以下警告消息：“ID1025: 已处理证书链，但是在不受信任提供程序信任的根证书中终止。” 如果仍要继续，请单击“是”。 否则，请单击“否”，然后选择其他 STS。

此时将显示另一个“应用程序信息”页面，这一次系统将要求您选择“无加密”或“启用加密”：

选择“启用加密”。 现在，您必须选择服务在对其与 STS 的通信进行加密时使用的证书。

使用默认证书意味着如果本地 STS 已创建用于加密令牌的证书，则还会使用此证书来进行解密。 注册生产 STS 时，此情况并不很常见，因为生产 STS 可能不会使用本地 STS 所使用的证书。 在生产解决方案中，不应使用此选项。 如果您已经拥有服务证书，则可能想要使用该证书。

如果选择现有证书，FedUtil 会显示本地证书存储中的证书。 证书必须具有私钥和使用者名称。

在本练习中，您可以使用默认证书，也可以选择现有证书。 完成后，单击“下一步”。

此时将出现“所提供的声明”页面：

其中包含由 STS 提供的声明的列表。 FedUtil 会通过从 STS 下载元数据并对其进行分析来获取此列表。 默认情况下，FedUtil 将声明感知 WCF 服务配置为仅需要名称和角色声明。 要查看如何配置服务以要求提供更多声明，请参阅“如何配置应用程序以要求提供更多声明”一节。 如果有服务所需但 STS 未提供的声明，则应与 STS 管理员联系并达成必要的协议。

单击“下一步”。 此时将出现“摘要”页面：

“摘要”页面显示您在“应用程序信息”对话框中输入的信息、您选择的服务和终结点、“使用现有 STS”选项、是否选择启用加密、应用程序请求的声明以及 FedUtil 将对应用程序配置进行的更改。

如果选择了测试证书，应用程序信息将包括以下注释：“所选的应用程序证书: 将向“个人”和“受信任人”证书存储区添加使用者名称为“CN=DefaultApplicationCertificate”的新证书(如果尚未存在)。” 如果选择了现有证书，将会看到该证书的指纹。

“摘要”页面还包含一个标签为“为此应用程序安排每日元数据更新”的复选框。 如果选中此复选框，FedUtil 会安排一个在每晚午夜更新应用程序元数据的任务。 有关详细信息，请参阅如何使用 FedUtil 执行信任管理。

单击“完成”。

如果查看 web.config 文件，将会发现 FedUtil 已对其进行修改：

• <configuration>/<configSections> 元素现在包含对 IdentityModel 配置部分的引用：

  <section name="microsoft.identityModel" type="Microsoft.IdentityModel.Configuration.MicrosoftIdentityModelSection, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  

• 添加了以下应用程序设置。 “Specified STS”是指在 FedUtil 中指定的 STS。

  <appSettings> <add key="FederationMetadataLocation" value="<specified STS>" /> </appSettings>
  

• 为所有用户授予了访问联合元数据的权限：

  <location path="FederationMetadata"> <system.web> <authorization> <allow users="*" /> </authorization> </system.web> </location>
  

• <system.Web>/<assemblies> 元素现在包含对 Microsoft.IdentityModel.dll 程序集的引用：

  <add assembly="Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
  

• 在 <system.serviceModel> 元素中，可以看到您在 FedUtil 中选择的服务现在有一个使用 WS-Federation HTTP 绑定的新终结点。

  <services> <service name="Service" behaviorConfiguration="ServiceBehavior"> <endpoint address="https://localhost:54280/ClaimsAwareService2/Service.svc" binding="ws2007FederationHttpBinding" contract="ClaimsAwareService2.IService" bindingConfiguration="ClaimsAwareService2.IService_ws2007FederationHttpBinding" /> <!-- Service Endpoints --> <!--Commented out by FedUtil--> <!--<endpoint address="" binding="wsHttpBinding" contract="ClaimsAwareService2.IService"><identity><dns value="localhost" /></identity></endpoint>--> <endpoint address="mex" binding="mexHttpBinding" contract="IMetadataExchange" /> </service> </services>
  

• <system.ServiceModel>/<behaviors>/<serviceBehavior>/<behavior> 元素现在包含 <federatedServiceHostConfiguration /> 元素，该元素引用的是您在 FedUtil 中选择的服务。 下面是将服务配置为声明感知服务的代码：

  <behaviors> <serviceBehaviors> <behavior name="ClaimsAwareService2.ServiceBehavior" > <!-- Behavior extension to make the service claims aware --> <federatedServiceHostConfiguration name="ClaimsAwareService2.Service" /> <!-- To avoid disclosing metadata information, set the value below to false and remove the metadata endpoint above before deployment --> <serviceMetadata  httpGetEnabled="true"/> <!-- To receive exception details in faults for debugging purposes, set the value below to true.  Set to false before deployment to avoid disclosing exception information --> <serviceDebug includeExceptionDetailInFaults="false"/> </behavior> </serviceBehaviors> </behaviors>
  

• <system.ServiceModel>/<behaviors>/<serviceBehavior>/<behavior> 元素还包含 <serviceCredentials> 元素，该元素引用的是本地计算机上的测试证书。 这是在 FedUtil 中指定的证书。

  <serviceCredentials> <!--Certificate added by FedUtil.  Subject='CN=DefaultApplicationCertificate', Issuer='CN=DefaultApplicationCertificate'.--> <serviceCertificate findValue="48BF03FCEDA703DE09E0F1F0CEFED60BB92B3DD8" storeLocation="LocalMachine" storeName="My" x509FindType="FindByThumbprint" /> </serviceCredentials>
  

• The <system.serviceModel> 元素现在包含 <bindings> 元素，该元素用于列出 WCF 服务需要的声明。 “Specified STS”是指在 FedUtil 中指定的 STS。

  <bindings> <ws2007FederationHttpBinding> <binding name="ClaimsAwareService2.IService_ws2007FederationHttpBinding"> <security mode="Message"> <message> <issuerMetadata address="https://<specified STS>/Trust/Mex" /> <claimTypeRequirements> <!--Following are the claims offered by STS '<specified STS>'. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" isOptional="true" /> <add claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" isOptional="true" /> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/CommonName" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/EmailAddress" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/Group" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/UPN" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/title" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/picture" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/manager" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/department" isOptional="true" />--> </claimTypeRequirements> </message> </security> </binding> </ws2007FederationHttpBinding> </bindings>
  

  请注意，除名称和角色声明外的所有声明都被注释掉。 要查看如何配置服务以要求提供更多声明，请参阅“如何配置应用程序以要求提供更多声明”一节。

• 最后，<configuration> 元素包含 Microsoft.IdentityModel 的配置部分，其中将生产 STS 指定为受信任令牌提供方：

  <microsoft.identityModel> <service name="ClaimsAwareService2.Service"> <audienceUris> <add value="https://localhost:54966/ClaimsAwareService2/Service.svc" /> </audienceUris> <issuerNameRegistry type="Microsoft.IdentityModel.Tokens.ConfigurationBasedIssuerNameRegistry, Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"> <trustedIssuers> <add thumbprint="5C8885A8E3D29D6BF6C9365E00B1BEA5EB284D1E" name="CN=<specified STS>, OU=US-Federated Identity, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" /> </trustedIssuers> </issuerNameRegistry> </service> </microsoft.identityModel>
  

请注意，可以重复运行 FedUtil 以便在本地 STS 与生产 STS 之间来回切换。 每次运行 FedUtil 时，它只会覆盖自己之前创建的配置。 不过，不能利用 FedUtil 从使用本地或生产 STS 切换到不使用 STS。

另请注意，如果运行 FedUtil 并创建本地 STS，然后切换到生产 STS，则配置文件中的 <issuerNameRegistry> 元素将包含两个受信任颁发者。 一个是本地 STS，另一个是生产 STS。 在准备好部署应用程序后，应该从颁发者名称注册表中删除本地 STS。

3. 更新联合元数据

默认情况下，当您使用 FedUtil 并执行生产 STS 时，FedUtil 会将应用程序配置为仅需要名称和角色声明。 通过查看应用程序 web.config 文件中的 <claimTypeRequirements> 元素可了解这一情况：

<bindings> <ws2007FederationHttpBinding> <binding name="ClaimsAwareService2.IService_ws2007FederationHttpBinding"> <security mode="Message"> <message> <issuerMetadata address="https://<specified STS>/Trust/Mex" /> <claimTypeRequirements> <!--Following are the claims offered by STS 'http://<specified STS>/Trust'. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" isOptional="true" /> <add claimType="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" isOptional="true" /> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/CommonName" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/EmailAddress" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/Group" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/claims/UPN" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/title" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/picture" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/manager" isOptional="true" />--> <!--<add claimType="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/department" isOptional="true" />--> </claimTypeRequirements> </message> </security> </binding> </ws2007FederationHttpBinding> </bindings>

例如，在上面的代码片段中，emailaddress 声明被注释掉。 要将应用程序配置为需要其他声明，请取消注释所需的声明。 接下来，在解决方案资源管理器中，右键单击应用程序项目，然后选择“更新联合元数据”：

FedUtil 将更新应用程序的联合元数据，以反映对所需声明列表的更改。 随后，打开应用程序的 FederationMetadata.xml 文件，然后查看更新后的所需声明列表。 该列表此时应包含应用程序 web.config 文件中已取消注释的所有其他声明。 请注意，FedUtil 还会生成应用程序 web.config 文件的备份副本。

<fed:ClaimTypesRequested> <auth:ClaimType Uri="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> <auth:ClaimType Uri="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" Optional="True" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706" /> ... </fed:ClaimTypesRequested>

此外，还可以将自定义声明类型添加到应用程序的 web.config 文件中。 但这之后必须要求 STS 管理员更新应用程序的 STS 策略。这样，应用程序才能发出新的声明类型。