使用 FedUtil 建立从 ASP.NET 信赖方应用程序到 STS 的信任

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

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

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

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

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

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

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

1. 创建本地 STS

在本练习中，您将创建一个本地 STS 以供声明感知 ASP.NET 依赖方应用程序使用。 请注意，必须从 Visual Studio 内运行 FedUtil 才能执行此操作。 此选项旨在通过非生产 STS 帮助开发声明感知依赖方 ASP.NET 应用程序。 稍后，您将了解到如何切换到使用生产 STS。

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

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

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

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

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

2. 应用程序 URI：指定 ASP.NET 服务的 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 已对其进行修改：

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

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

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

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

• 已将 WSFederationAuthenticationModule 和 SessionAuthenticationModule 添加到 <system.Web>/<httpModules> 元素：

  <httpModules> ... <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> </httpModules>
  

• 此外，还将它们添加到 <system.webServer>/<modules> 元素：

  <system.webServer> ... <modules> <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> </modules> ... </system.webServer>
  

• 最后，按如下方式修改了 <microsoft.identityModel>/<service> 元素：

  <microsoft.identityModel> <service> <audienceUris> <add value="https://localhost:58496/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication enabled="true"> <wsFederation passiveRedirectEnabled="true" issuer="https://localhost:58497/ClaimsAwareWebSite2_STS/" realm="https://localhost:58496/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <applicationService> <claimTypeRequired> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> </claimTypeRequired> </applicationService> <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>
  

  • 添加了 <audienceUris> 元素来指定声明感知 ASP.NET 信赖方应用程序的 URI。

  • 添加了 <federatedAuthentication> 元素来指定此声明感知 ASP.NET 信赖方应用程序的 STS 位置。 在本练习中，使用的是本地 STS。

  • 添加了 <applicationService>/<claimTypeRequired> 元素来指定应用程序在 STS 为其颁发的所有令牌中所需的声明。 在本练习中，使用的是默认声明“name”和“role”。 请注意，依赖方实际上并不依赖于这些声明类型要求。 这些要求存在于配置文件中有两个原因：

    1. 信赖方应用程序可以使用这些声明类型要求来验证传入的令牌是否具有这些声明。 此操作可以在 ClaimsAuthenticationManager 中完成。

    2. 借助这些要求，信赖方可以轻松地更新信赖方应用程序的声明类型要求。

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

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

请注意，此本地 STS 颁发的令牌未经过加密。

要添加本地 STS 颁发的其他声明，请打开 STS 项目中 App_Code 文件夹下的 CustomSecurityTokenService.cs，然后导航到 GetOutputClaimsIdentity 方法并添加其他声明。

2. 注册现有生产 STS

在本练习中，您将建立从 ASP.NET 信赖方到现有 STS 的信任。

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

在“应用程序信息”页面中，选择“使用现有 STS”：

您必须为生产 STS 指定联合元数据终结点的位置。 可以单击“测试位置”按钮以确保元数据文档可访问。 此按钮会向指定的终结点发出请求，并在默认 Web 浏览器中显示响应。 在本练习中，我们使用 Active Directory® Federation Service (AD FS) 2.0 STS。 指定联合元数据文档的位置后，单击“下一步”。

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

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

请与 STS 管理员确认生产 STS 是否支持令牌加密。 如果支持，建议启用加密。 在本练习中，选择“启用加密”。 现在，必须选择依赖方想要 STS 在加密令牌时使用的证书。

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

如果选择现有证书，FedUtil 会显示本地证书存储中的证书。 证书必须具有私钥和使用者名称。 请确保应用程序运行时使用的标识（例如 NETWORK SERVICE）有权访问证书的私钥。

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

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

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

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

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

“摘要”页面显示您在“应用程序信息”对话框中输入的信息、“使用现有 STS”选项、应用程序请求的声明以及 FedUtil 将对应用程序配置进行的更改。

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

单击“完成”。

下面是对信赖方的 web.config 文件的更改：

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

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

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

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

• 已将 WSFederationAuthenticationModule 和 SessionAuthenticationModule 添加到 <system.Web>/<httpModules> 元素：

  <httpModules> ... <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> </httpModules>
  

• 此外，还将它们添加到 <system.webServer>/<modules> 元素：

  <system.webServer> ... <modules> <add name="WSFederationAuthenticationModule" type="Microsoft.IdentityModel.Web.WSFederationAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> <add name="SessionAuthenticationModule" type="Microsoft.IdentityModel.Web.SessionAuthenticationModule, Microsoft.IdentityModel, Version=0.6.1.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" preCondition="managedHandler" /> </modules> ... </system.webServer>
  

• 最后，按如下方式修改了 <microsoft.identityModel>/<service> 元素。 “Specified STS”是指在 FedUtil 中指定的 STS。

  <microsoft.identityModel> <service> <audienceUris> <add value="https://localhost:57349/ClaimsAwareWebSite2/" /> </audienceUris> <federatedAuthentication> <wsFederation passiveRedirectEnabled="true" issuer="https://<specified STS>/FederationPassive/" realm="https://localhost:57349/ClaimsAwareWebSite2/" requireHttps="false" /> <cookieHandler requireSsl="false" /> </federatedAuthentication> <serviceCertificate> <certificateReference x509FindType="FindByThumbprint" findValue="48BF03FCEDA703DE09E0F1F0CEFED60BB92B3DD8" storeLocation="LocalMachine" storeName="My" /> </serviceCertificate> <applicationService> <claimTypeRequired> <!--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.--> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/CommonName" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/EmailAddress" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/Group" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/claims/UPN" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/webpage" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/title" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/picture" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/manager" optional="true" />--> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/department" optional="true" />--> </claimTypeRequired> </applicationService> <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>
  

  • 添加了 <audienceUris> 元素来指定声明感知 ASP.NET 信赖方应用程序的 URI。

  • 添加了 <federatedAuthentication> 元素来指定此声明感知 ASP.NET 信赖方应用程序的 STS 位置。 这是在 FedUtil 中指定的 STS。

  • 添加了 <serviceCertificate> 元素来指定声明感知 ASP.NET 信赖方应用程序在加密其与 STS 的通信时使用的证书的位置。 这是在 FedUtil 中指定的证书。

  • 添加了 <applicationService>/<claimTypeRequired> 元素来指定应用程序在 STS 为其颁发的所有令牌中所需的声明。 默认情况下，FedUtil 会将声明感知 ASP.NET 信赖方应用程序配置为仅需要名称和角色声明。 要查看如何配置依赖方应用程序以要求提供更多声明，请参阅“如何配置应用程序以要求提供更多声明”一节。

  • 添加了 <issuerNameRegistry>/<trustedIssuers> 元素，用于指定 STS 在对其所颁发的令牌进行签名时使用的证书。

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

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

3. 更新联合元数据

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

<claimTypeRequired> <!--Following are the claims offered by STS '<specified STS>', and added at 4/15/2009 3:57:07 PM. Add or uncomment claims that you require by your application and then update the federation metadata of this application.--> <claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" optional="true" /> <claimType type="https://schemas.microsoft.com/ws/2008/06/identity/claims/role" optional="true" /> <!--<claimType type="https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" optional="true" />--> ... </claimTypeRequired>

例如，在上面的代码片段中，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 策略。这样，应用程序才能发出新的声明类型。