使用 OpenID Connect 或 OAuth 搭配 AD FS 2016 或更新版本時,自訂要在 id_token 中發出的宣告

概觀

本文說明如何建立使用 AD FS 進行 OpenID Connect 登入的應用程式。 不過,根據預設,id_token 中只會提供一組固定的宣告。 AD FS 2016 和更新版本可讓您在 OpenID Connect 案例中自訂 id_token。

何時使用自訂識別碼權杖?

在某些情況下,用戶端應用程式可能沒有其嘗試存取的資源。 因此,它其實不需要存取權杖。 在這種情況下,用戶端應用程式基本上只需要識別碼權杖,但是有一些額外的宣告可協助功能。

在識別碼權杖中取得自訂宣告有哪些限制?

案例 1

Screenshot showing Scenario 1 which is using relying party I D to equal client I D.

  1. response_mode 設定為 form_post
  2. 只有公用用戶端可以取得識別碼權杖中的自訂宣告
  3. (Web API 識別碼) 的信賴憑證者識別碼應與用戶端識別碼相同

案例 2

Screenshot showing Scenario 2 which is using allatclaims scope.

在 AD FS 伺服器上安裝 KB4019472 或更新版本的安全性更新

  1. response_mode 設定為 form_post
  2. 公用和機密用戶端都可以取得識別碼權杖中的自訂宣告
  3. 將範圍指派 allatclaims 給用戶端 – RP 配對。

您可以使用 Cmdlet 來指派範圍, Grant-ADFSApplicationPermission 如下列範例所示:

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

建立和設定 OAuth 應用程式以處理識別碼權杖中的自訂宣告

遵循下列步驟,在 AD FS 中建立及設定應用程式,以使用自訂宣告接收識別碼權杖。

在 AD FS 2016 或更新版本中建立和設定應用程式群組

  1. 在 AD FS 管理] 中,以滑鼠右鍵按一下 [應用程式群組],然後選取 [ 新增應用程式群組]。

  2. 在 [應用程式群組] 嚮導中,針對 [名稱] 輸入ADFSSSO ,在 [Client-Server 應用程式] 下,選取存取 web 應用程式範本的原生應用程式 按一下 [下一步] 。

    Screenshot of the Welcome page of the Add Application Group Wizard.

  3. 複製 用戶端識別碼 值。 稍後將用來作為應用程式 web.config 檔中 ida: ClientId 的值。

  4. 針對 [重新導向 URI] 輸入下列內容:https://localhost:44320/ 。 按一下 [新增]。 按一下 [下一步] 。

    Screenshot of the Native application page of the Add Application Group Wizard showing the redirect U R I .

  5. 在 [設定 WEB API ] 畫面上,針對 [識別碼] 輸入下列各項 。 按一下 [新增]。 按一下 [下一步] 。 此值稍後將用於 ida: 應用程式 web.config 檔中的 ResourceID。

    Screenshot of the Configure Web API page of the Add Application Group Wizard showing the correct identifier.

  6. 在 [選擇存取控制原則] 畫面上,選取 [允許所有人],然後按[下一步

    Screenshot of the Choose Access Control Policy page of the Add Application Group Wizard showing the Permit everyone option highlighted.

  7. 在 [ 設定應用程式許可權 ] 畫面上,確定已選取 openidAllatclaims ,然後按 [下一步]

    Screenshot of the Configure Application Permissions page of the Add Application Group Wizard.

  8. 在 [ 摘要 ] 畫面上,按 [下一步]

    Screenshot of the Summary page of the Add Application Group Wizard.

  9. 在 [ 完成 ] 畫面上,按一下 [ 關閉]。

  10. 在 AD FS 管理] 中,按一下 [應用程式群組] 以取得所有應用程式群組的清單。 以滑鼠右鍵按一下 ADFSSSO ,然後選取 [ 屬性]。 選取 [ ADFSSSO-WEB API ],然後按一下 [編輯]。

    Screenshot of the A D F S S O Properties dialog box showing the Web API listed in the Applications section.

  11. 在 [ ADFSSSO-WEB API 屬性] 畫面上,選取 [發行轉換規則] 索引標籤,然後按一下 [新增規則 ... ]。

    Screenshot of the A D F S S O Properties dialog box Showing the Issuance Transform Rules tab.

  12. 在 [新增轉換宣告規則]畫面上,從下拉式清單中選取 [使用自訂規則傳送宣告],然後按[下一步]

    Screenshot of the Select Rule Template page of the Add Transform Claim Rule Wizard showing the Send Claims Using a Custom Rule option selected.

  13. 在 [新增轉換宣告規則]頁面中,于 [宣告規則名稱] 和 [自訂規則中的下列宣告規則] 中輸入ForCustomIDToken 。 按一下 [完成]

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

    Screenshot of the Configure Rule page of the Add Transform Claim Rule Wizard showing the Claim rule name and Custom rule text fields populated.

    注意

    您也可以使用 PowerShell 來指派 allatclaimsopenid 範圍。

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

下載並修改範例應用程式,以在 id_token 中發出自訂宣告

本節討論如何下載範例 Web 應用程式,並在 Visual Studio 中加以修改。 我們將使用位於此處的 Azure AD 範例。

若要下載範例專案,請使用 Git Bash,然後輸入下列內容:

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

Screenshot of the Git Bash window showing the results of the git clone command.

若要修改應用程式

  1. 使用 Visual Studio 開啟範例。

  2. 重建應用程式,以便還原所有遺失的 NuGet 套件。

  3. 開啟 web.config 檔案。 修改下列值,使其看起來如下所示:

    <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 AD FS 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]" />
    

    Screenshot of the web config file showing the modified values.

  4. 開啟 [.cs] 檔案,並進行下列變更:

    • 使用下列變更來調整 OpenId 連線中介軟體初始化邏輯:

      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"];
      
    • 將下列內容批註:

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

      Screenshot of the Start up Auth file showing the commented out lines of code.

    • 在下一個步驟中,修改 OpenId 連線中介軟體選項,如下所示:

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

      Screenshot of the Start up Auth file showing the modified Open I D Connect middleware options.

  5. 開啟 HomeController .cs 檔案,並進行下列變更:

    • 新增下列內容:

      using System.Security.Claims;
      
    • 更新 About() 方法,如下所示:

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

      Screenshot of the Home Controller file with the requred updates.

測試識別碼權杖中的自訂宣告

完成上述變更之後,按 F5。 這會顯示範例頁面。 按一下 [登入]。

Screenshot of the sample app displayed in a browser.

系統會將您重新導向至 AD FS 登入頁面。 繼續進行並登入。

Screenshot of the A D F S Sign in page.

一旦成功,您應該會看到您現在已登入。

Screenshot of the sample app showing that the user is signed in.

按一下 [關於] 連結。 您會看到 "Hello [Username]",它是從識別碼權杖中的使用者名稱宣告取出的

Screenshot of the About page in the sample app.

後續步驟

AD FS 開發