当使用 OpenID Connect 或 OAuth 与 AD FS 2016 或更高版本时,自定义要在 id_token 中发出的声明Customize claims to be emitted in id_token when using OpenID Connect or OAuth with AD FS 2016 or later

概述Overview

本文介绍如何生成使用 AD FS 进行 OpenID connect 登录的应用。The article here shows you how to build an app that uses AD FS for OpenID Connect sign on. 但是,在默认情况下,id_token 中只提供一组固定的声明。However, by default there are only a fixed set of claims available in the id_token. AD FS 2016 及更高版本可在 OpenID Connect 方案中自定义 id_token。AD FS 2016 and later releases have the capability to customize the id_token in OpenID Connect scenarios.

何时使用自定义 ID 令牌?When are custom ID tokens used?

在某些情况下,客户端应用程序可能没有要尝试访问的资源。In certain scenarios, it is possible that the client application does not have a resource that it is trying to access. 因此,它并不真正需要访问令牌。Therefore, it doesn't really need an access token. 在这种情况下,客户端应用程序实质上只需要一个 ID 令牌,但有一些其他声明可帮助提供此功能。In such cases, the client application essentially needs only an ID token, but with some additional claims to help in the functionality.

在 ID 令牌中获取自定义声明有哪些限制?What are the restrictions on getting custom claims in ID token?

方案 1Scenario 1

限制

  1. response_mode设置为form_postresponse_mode is set as form_post
  2. 只有公用客户端才能获取 ID 令牌中的自定义声明Only public clients can get custom claims in ID token
  3. (Web API 标识符) 的信赖方标识符应与客户端标识符相同Relying party identifier (Web API identifier) should be the same as the client identifier

方案 2Scenario 2

限制

在 AD FS 服务器上安装KB4019472或更高版本的安全更新With KB4019472 or later security update installed on your AD FS servers

  1. response_mode设置为 form_postresponse_mode is set as form_post
  2. 公共和机密客户端都可以在 ID 令牌中获取自定义声明Both public and confidential clients can get custom claims in ID token
  3. 将作用域分配 allatclaims 到客户端– RP 配对。Assign scope allatclaims to the client – RP pair.

可以按照 Grant-ADFSApplicationPermission 以下示例中所示,使用 cmdlet 来分配作用域:You can assign the scope by using the Grant-ADFSApplicationPermission cmdlet as indicated in the example below:

Grant-AdfsApplicationPermission -ClientRoleIdentifier "https://my/privateclient" -ServerRoleIdentifier "https://rp/fedpassive" -ScopeNames "allatclaims","openid"

创建和配置 OAuth 应用程序以处理 ID 令牌中的自定义声明Creating and configuring an OAuth application to handle custom claims in ID token

按照以下步骤,在用于接收 ID 令牌的 AD FS 中创建和配置应用程序,并提供自定义声明。Follow the steps below to create and configure the application in AD FS for receiving ID token with custom claims.

在 AD FS 2016 或更高版本中创建和配置应用程序组Create and configure an Application Group in AD FS 2016 or later

  1. 在 AD FS 管理 "中,右键单击" 应用程序组 ",然后选择"添加应用程序组"。In AD FS Management, right-click on Application Groups and select Add Application Group.

  2. 在应用程序组向导上,为 "输入ADFSSSO ",在 "客户端-服务器应用程序" 下,选择本机应用程序访问 web 应用程序模板。On the Application Group Wizard, for the name enter ADFSSSO and under Client-Server applications select the Native application accessing a web application template. 单击“下一步”。Click Next.

    客户端

  3. 复制 "客户端标识符" 值。Copy the Client Identifier value. 它稍后将用作应用程序 web.config 文件中的 ida: ClientId 的值。It will be used later as the value for ida:ClientId in the applications web.config file.

  4. 对于 "重定向 URI",请输入以下内容: - https://localhost:44320/Enter the following for Redirect URI: - https://localhost:44320/. 单击 添加Click Add. 单击“下一步”。Click Next.

    客户端

  5. 在 "配置 WEB API " 屏幕上,输入以下标识符作为标识符 - https://contoso.com/WebAppOn the Configure Web API screen, enter the following for Identifier - https://contoso.com/WebApp. 单击 添加Click Add. 单击“下一步”。Click Next. 稍后会将此值用于应用程序 web.config 文件中的ida: ResourceIDThis value will be used later for ida:ResourceID in the applications web.config file.

    客户端

  6. 在 "选择访问控制策略" 屏幕上,选择 "允许每个人" 并单击 "下一步"On the Choose Access Control Policy screen, select Permit everyone and click Next.

    客户端

  7. 在 "配置应用程序权限" 屏幕上,确保已选中 " openid and allatclaims ",然后单击 "下一步"。On the Configure Application Permissions screen, make sure openid and allatclaims are selected and click Next.

    客户端

  8. 在 "摘要" 屏幕上,单击 "下一步"。On the Summary screen, click Next.

    客户端

  9. 在 "完成" 屏幕上,单击 "关闭"。On the Complete screen, click Close.

  10. 在 AD FS 管理 "中,单击" 应用程序组 "以获取所有应用程序组的列表。In AD FS Management, click on Application Groups to get list of all application groups. 右键单击ADFSSSO ,然后选择 "属性"。Right-click on ADFSSSO and select Properties. 选择ADFSSSO-WEB API ,然后单击 "编辑 ... "Select ADFSSSO - Web API and click Edit...

    客户端

  11. ADFSSSO-WEB API 属性屏幕上,选择 "颁发转换规则" 选项卡,然后单击 "添加规则 ... "On ADFSSSO - Web API Properties screen, select Issuance Transform Rules tab and click Add Rule...

    客户端

  12. 在 "添加转换声明规则向导" 屏幕上,从下拉菜单中选择 "使用自定义规则发送声明",然后单击 "下一步"On Add Transform Claim Rule Wizard screen, select Send Claims Using a Custom Rule from the drop-down and click Next

    客户端

  13. 在 "添加转换声明规则" 向导屏幕上,在 "声明规则名称" 中输入ForCustomIDToken ,并在自定义规则中输入以下声明规则。On the Add Transform Claim Rule Wizard screen, enter ForCustomIDToken in the Claim rule name and the following claim rule in Custom rule. 单击“完成”Click Finish

    x:[]
    => issue(claim=x);
    

    客户端

    备注

    你还可以使用 PowerShell 来分配 allatclaimsopenid 作用域。You can also use PowerShell to assign the allatclaims and openid scopes.

    Grant-AdfsApplicationPermission -ClientRoleIdentifier "[Client ID from #3 above]" -ServerRoleIdentifier "[Identifier from #5 above]" -ScopeNames "allatclaims","openid"
    

下载并修改示例应用程序,以便在 id_token 中发出自定义声明Download and modify the sample application to emit custom claims in id_token

本部分介绍如何在 Visual Studio 中下载示例 Web 应用并对其进行修改。This section discusses how to download the sample Web APP and modify it in Visual Studio. 我们将使用此处的 Azure AD 示例。We will be using the Azure AD sample located here.

若要下载示例项目,请使用 Git Bash,并键入以下内容:To download the sample project, use Git Bash and type the following:

git clone https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/1-WebApp-OIDC

AD FS OpenID

修改应用程序To Modify the app

  1. 使用 Visual Studio 打开示例。Open the sample using Visual Studio.

  2. 重新生成应用,以便还原所有缺少的 Nuget。Rebuild the app so that all of the missing NuGets are restored.

  3. 打开 web.config 文件。Open the web.config file. 修改以下值,使其类似于以下内容:Modify the following values so the look like the following:

    <add key="ida:ClientId" value="[Replace this Client Id from #3 above under section Create and configure an Application Group in AD FS 2016 or later]" />
    <add key="ida:ResourceID" value="[Replace this with the Web API Identifier from #5 above]"  />
    <add key="ida:ADFSDiscoveryDoc" value="https://[Your ADFS hostname]/adfs/.well-known/openid-configuration" />
    <!--<add key="ida:Tenant" value="[Enter tenant name, e.g. contoso.onmicrosoft.com]" />
    <add key="ida:AADInstance" value="https://login.microsoftonline.com/{0}" />-->
    <add key="ida:PostLogoutRedirectUri" value="[Replace this with the Redirect URI from #4 above]" />
    

    AD FS OpenID

  4. 打开 Startup.Auth.cs 文件并进行以下更改:Open the Startup.Auth.cs file and make the following changes:

    • 调整 OpenId Connect 中间件初始化逻辑,并进行以下更改:Tweak the OpenId Connect middleware initialization logic with the following changes:

      private static string clientId = ConfigurationManager.AppSettings["ida:ClientId"];
      //private static string aadInstance = ConfigurationManager.AppSettings["ida:AADInstance"];
      //private static string tenant = ConfigurationManager.AppSettings["ida:Tenant"];
      private static string metadataAddress = ConfigurationManager.AppSettings["ida:ADFSDiscoveryDoc"];
      private static string resourceId = ConfigurationManager.AppSettings["ida:ResourceID"];
      private static string postLogoutRedirectUri = ConfigurationManager.AppSettings["ida:PostLogoutRedirectUri"];
      
    • 注释掉以下内容:Comment out the following:

      //string Authority = String.Format(CultureInfo.InvariantCulture, aadInstance, tenant);
      

      AD FS OpenID

    • 再往下修改 OpenId Connect 中间件选项,如下所示:Further down, modify the OpenId Connect middleware options as in the following:

      app.UseOpenIdConnectAuthentication(
           new OpenIdConnectAuthenticationOptions
           {
               ClientId = clientId,
               //Authority = authority,
               Resource = resourceId,
               MetadataAddress = metadataAddress,
               PostLogoutRedirectUri = postLogoutRedirectUri,
               RedirectUri = postLogoutRedirectUri
      

      AD FS OpenID

  5. 打开 HomeController.cs 文件并进行以下更改:Open the HomeController.cs file and make the following changes:

    • 添加以下内容:Add the following:

      using System.Security.Claims;
      
    • 更新 About() 方法,如下所示:Update the About() method as shown below:

      [Authorize]
      public ActionResult About()
      {
           ClaimsPrincipal cp = ClaimsPrincipal.Current;
           string userName = cp.FindFirst(ClaimTypes.WindowsAccountName).Value;
           ViewBag.Message = String.Format("Hello {0}!", userName);
           return View();
      }
      

      AD FS OpenID

在 ID 令牌中测试自定义声明Test the custom claims in ID token

进行上述更改后,按 F5。Once the above changes have been made, hit F5. 这将显示示例页。This will bring up the sample page. 单击 "登录"。Click on sign in.

AD FS OpenID

你将被重定向到 AD FS 登录页。You will be redirected to the AD FS sign-in page. 继续登录。Go ahead and sign in.

AD FS OpenID

成功后,你应该会看到你现在已登录。Once this is successful, you should see that you are now signed in.

AD FS OpenID

单击“关于”链接。Click the About link. 你将看到 "Hello [Username]",它从 ID 令牌中的用户名声明检索You will see "Hello [Username]" which is retrieved from the username claim in ID token

AD FS OpenID

后续步骤Next Steps

AD FS 开发AD FS Development