共用方式為


在 Azure Active Directory B2C 中設定 OAuth 2.0 用戶端認證流程

這很重要

自 2025 年 5 月 1 日起,Azure AD B2C 將不再可供新客戶購買。 在我們的常見問題中深入瞭解

開始之前,請使用此頁面頂端的 [選擇原則類型] 選取器,選擇您要設定的原則類型。 Azure Active Directory B2C 提供兩種方法來定義使用者如何與您的應用程式互動:透過預先定義的使用者流程,或透過完全可設定的自訂原則。 此文章中所需的步驟隨各方法而異。

OAuth 2.0 用戶端認證授與流程允許應用程式(機密用戶端)使用自己的認證,而不是模擬使用者,以在呼叫 WEB 資源時進行驗證,例如 REST API。 這類型的授權通常用於伺服器間的互動,這些互動需要在背景中運行,無需立即與使用者互動。 這些類型的應用程式通常稱為精靈或服務帳戶。

在客戶端認證流程中,許可權會由系統管理員直接授與應用程式本身。 當應用程式將令牌呈現給資源時,資源會強制應用程式本身具有執行動作的授權,因為沒有任何使用者參與驗證。 本文涵蓋授權應用程式呼叫 API 所需的步驟,以及如何取得呼叫該 API 所需的令牌。

備註

這項功能處於公開預覽狀態。

應用程式註冊概觀

若要讓應用程式使用用戶端認證登入,然後呼叫 Web API,請在 Azure AD B2C 目錄中註冊兩個應用程式。

  • 應用程式註冊可讓您 的應用程式 使用 Azure AD B2C 登入。 應用程式註冊流程會產生可唯一識別您應用程式的「應用程式識別碼」 (也稱為「用戶端識別碼」)。 您也會建立「用戶端密碼」,讓應用程式用來安全地取得權杖。

  • Web API 註冊讓您的應用程式能夠呼叫安全的 Web API。 註冊包含 Web API「範圍」。 範圍提供一種方式,讓您可以管理受保護資源的權限,例如您的 Web API。 然後,您會將應用程式許可權授與 Web API 範圍。 要求存取令牌時,您的應用程式會 .default 指定要求的範圍參數。 Azure AD B2C 會傳回授與應用程式的 Web API 範圍。

下圖說明應用程式結構和註冊:

包含 Web A P I 呼叫註冊和令牌的 Web 應用程式圖表。

步驟 1:註冊 Web API 應用程式

在此步驟中,您會將 Web API(App 2)註冊其所屬範圍。 稍後,您會將應用程式 (應用程式 1) 許可權授與這些範圍。 如果您已經有這類應用程式註冊,請略過此步驟,然後移至下一個步驟:步驟 1.1 定義 Web API 角色(範圍)。

若要建立 Web API 應用程式註冊 (「應用程式識別碼:2」),請遵循下列步驟:

  1. 登入 Azure 入口網站

  2. 確定您使用的目錄包含您的 Azure AD B2C 租用戶。 選取入口網站工具列中的 [目錄 + 訂用帳戶] 圖示。

  3. 在 [入口網站設定] | [目錄 + 訂用帳戶] 頁面上,在 [目錄名稱] 清單中尋找 Azure AD B2C 目錄,然後選取 [切換]

  4. 在 Azure 入口網站中,搜尋並選取 [Azure AD B2C]

  5. 選取 [應用程式註冊],然後選取 [[新增註冊]。

  6. 針對 [名稱],輸入應用程式的名稱 (例如 my-api1)。 保留 [重新導向 URI] 和 [支援的帳戶類型] 的預設值。

  7. 選取 註冊

  8. 當應用程式註冊完成之後,選取 [概觀]

  9. 當您設定 Web 應用程式時,請記錄 [應用程式 (用戶端) 識別碼] 值,以供稍後使用。

    示範如何取得 Web A P I 應用程式識別碼的螢幕快照。

步驟 1.1 定義 Web API 角色 (範圍)

在此步驟中,您會設定 Web API 應用程式識別碼 URI,然後定義 應用程式角色。 OAuth 2.0 範圍所使用的應用程式角色,並在代表 API 的應用程式註冊上定義。 您的應用程式會使用應用程式識別碼 URI 搭配 .default 範圍。 若要定義應用程式角色,請遵循下列步驟:

  1. 選取您建立的 Web API,例如 my-api1

  2. [管理] 底下,選取 [ 公開 API]。

  3. 選取 [應用程式識別碼 URI] 旁邊的 [設定] 連結。 將預設值 (GUID)替換為一個唯一的名稱(例如,api),然後選取 [儲存]。

  4. 複製 應用程式識別碼 URI。 下列螢幕快照顯示如何複製應用程式識別碼 URI。

    顯示如何複製應用程式識別碼的螢幕快照。

  5. [管理] 底下,選取 [ 指令清單 ] 以開啟應用程式指令清單編輯器。 在編輯器中找出appRoles設定,並定義以applications為目標的應用程式角色。 每個應用程式角色定義都必須有其 id 值的全域唯一標識碼(GUID)。 在 Microsoft PowerShell 或new-guid中執行命令,以產生新的 GUID。 每個應用程式角色定義的value屬性會出現在scp宣告的範圍中。 屬性 value 不能包含空格。 下列範例示範兩個應用程式角色:讀取和寫入:

    "appRoles": [
    {
      "allowedMemberTypes": ["Application"],
      "displayName": "Read",
      "id": "d6a15e20-f83c-4264-8e61-5082688e14c8",
      "isEnabled": true,
      "description": "Readers have the ability to read tasks.",
      "value": "app.read"
    },
    {
      "allowedMemberTypes": ["Application"],
      "displayName": "Write",
      "id": "204dc4ab-51e1-439f-8c7f-31a1ebf3c7b9",
      "isEnabled": true,
      "description": "Writers have the ability to create tasks.",
      "value": "app.write"
    }],
    
  6. 在頁面頂端,選取 [ 儲存 ] 以儲存指令清單變更。

步驟 2:註冊應用程式

若要讓應用程式使用用戶端認證流程使用 Azure AD B2C 登入,您可以使用現有的應用程式或註冊新的應用程式(應用程式 1)。

如果您使用現有的應用程式,請確定應用程式的 accessTokenAcceptedVersion 設定為 2

  1. 在 Azure 入口網站中,搜尋並選取 [Azure AD B2C]
  2. 選取 [應用程式註冊],然後從清單中選取現有的應用程式。
  3. 在左側功能表中的 [ 管理] 底下,選取 [ 指令清單 ] 以開啟指令清單編輯器。
  4. 定位 accessTokenAcceptedVersion 元素,並將其值設定為 2
  5. 在頁面頂端,選取 [ 儲存 ] 以儲存變更。

若要建立新的 Web 應用程式註冊,請遵循下列步驟:

  1. 在 Azure 入口網站中,搜尋並選取 [Azure AD B2C]

  2. 選取 [應用程式註冊],然後選取 [[新增註冊]。

  3. 輸入應用程式的 [名稱]。 例如, ClientCredentials_app

  4. 保留其他值,然後選取 [註冊]

  5. 記錄 [應用程式 (用戶端) 識別碼],以便在稍後的步驟中使用。

    顯示如何取得應用程式識別碼的螢幕快照。

步驟 2.1 建立客戶端密碼

為已註冊的應用程式建立用戶端密碼。 您的應用程式會在要求令牌時,使用用戶端密碼來證明其身分識別。

  1. [管理] 下,選取 [ 憑證與秘密]。

  2. 選取 [新用戶端密碼]

  3. 在 [ 描述 ] 方塊中,輸入客戶端密碼的描述(例如 clientsecret1)。

  4. 在 [到期] 下,選取祕密的有效持續時間,然後選取 [新增]

  5. 記錄秘密的 。 您可以在稍後的步驟中使用此值進行設定。

    截圖顯示如何複製應用程式密鑰。

步驟 2.2 授與 Web API 的應用程式許可權

若要授與您的應用程式 (App 1) 許可權,請遵循下列步驟:

  1. 選取 [應用程式註冊],然後選取您建立的應用程式(應用程式 1)。

  2. 「管理」下方選取 [API 權限]

  3. 在 [已設定的權限] 底下,選取 [新增權限]

  4. 請選取「我的 API」 索引標籤。

  5. 選取 Web 應用程式應授與存取權的 API (App 2)。 例如,輸入 my-api1

  6. 選取 [應用程式] 許可權

  7. [許可權] 底下,展開 應用程式,然後選取您稍早定義的範圍(例如 app.readapp.write)。

    顯示如何授與應用程式 A P I 許可權的螢幕快照。

  8. 選取新增權限

  9. 選取 [代表 <您的租用戶名稱> 授與管理員同意]

  10. 選擇

  11. 選取 [重新整理],然後驗證 [授與...] 會出現在這兩個範圍的 [狀態] 下方。

步驟 3:取得存取令牌

沒有特定動作可啟用使用者流程或自定義原則的客戶端認證。 Azure AD B2C 使用者流程和自定義原則都支援客戶端認證流程。 如果您尚未這麼做,請建立 使用者流程或自定義原則。 然後,使用您慣用的 API 開發應用程式來產生授權要求。 請使用下列資訊作為 POST 要求的本文,以建構與此範例類似的呼叫:

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy>/oauth2/v2.0/token

  • <tenant-name> 用於您的 Azure AD B2C 租戶的 名稱 。 例如: contoso.b2clogin.com
  • <policy> 替換為使用者流程的完整名稱或自訂政策。 請注意,所有類型的使用者流程和自定義原則都支援客戶端認證流程。 您可以使用您擁有的任何使用者流程或自定義原則,或建立新的流程,例如註冊或登入。
鑰匙 價值觀
grant_type (授權類型) client_credentials
client_id (客戶識別碼) 步驟 2 註冊應用程式的用戶端識別碼
用戶端密鑰 步驟 2.1 建立客戶端密碼中的用戶端密碼值。
範圍 步驟 1.1 定義 Web API 角色(範圍)中獲取應用程式識別碼 URI.default。 例如 https://contoso.onmicrosoft.com/api/.default, 或 https://contoso.onmicrosoft.com/00001111-aaaa-2222-bbbb-3333cccc4444/.default

實際的 POST 要求與以下範例類似:

要求

POST /<tenant-name>.onmicrosoft.com/B2C_1A_SUSI/oauth2/v2.0/token HTTP/1.1
Host: <tenant-name>.b2clogin.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_secret=FyX7Q~DuPJ...
&scope=https%3A%2F%2Fcontoso.onmicrosoft.com%2Fapi%2F.default

回應:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5OZDlnUkNWWUc2dUs...",
    "token_type": "Bearer",
    "not_before": 1645172292,
    "expires_in": 3600,
    "expires_on": 1645175892,
    "resource": "11112222-bbbb-3333-cccc-4444dddd5555"
}

了解傳回 存取令牌 宣告。 下表列出與客戶端認證流程相關的宣稱。

索賠 說明 價值觀
aud 識別權杖的預定接收者。 API 的 用戶端識別碼
sub 發起請求的應用程式所關聯的服務主體。 授權請求的服務主體是 client_id
azp 已授權的一方 - 發出存取令牌的一方。 起始要求之應用程式的 用戶端標識碼 。 這是您在授權要求中指定的 client_id 相同值。
scp 應用程式 API 公開的範圍集(空格分隔符)。 在客戶端認證流程中,授權要求會要求 .default 範圍,而令牌則包含 API 公開的範圍清單(並由應用程式管理員同意)。 例如: app.read app.write

步驟 3.1 使用腳本取得存取令牌

使用下列 PowerShell 腳本來測試您的設定:

$appId = "<client ID>"
$secret = "<client secret>"
$endpoint = "https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy>/oauth2/v2.0/token"
$scope = "<Your API id uri>/.default"
$body = "grant_type=client_credentials&scope=" + $scope + "&client_id=" + $appId + "&client_secret=" + $secret

$token = Invoke-RestMethod -Method Post -Uri $endpoint -Body $body

使用下列 cURL 腳本來測試您的設定:

curl --location --request POST 'https://<your-tenant>.b2clogin.com/<your-tenant>.onmicrosoft.com/<policy>/oauth2/v2.0/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--form 'grant_type="client_credentials"' \
--form 'client_id="<client ID>"' \
--form 'client_secret="<client secret>"' \
--form 'scope="<Your API id uri>/.default"'

步驟 4:自定義令牌

此功能僅適用於自訂原則。 如需設定步驟,請在前述選取器中選取 [自訂原則]

自訂原則提供擴充令牌發行流程的方式。 若要自定義 OAuth 2.0 用戶端認證的使用者旅程圖,請遵循 如何設定客戶端認證使用者旅程圖的指引。 然後在 JwtIssuer 技術配置檔中,新增 ClientCredentialsUserJourneyId 元數據,並參考您所建立的使用者旅程。

下列範例示範如何將 新增 ClientCredentialsUserJourneyId 至令牌簽發者技術配置檔。

<TechnicalProfile Id="JwtIssuer">
  <Metadata>
    <Item Key="ClientCredentialsUserJourneyId">ClientCredentialsJourney</Item>
  </Metadata>
</TechnicalProfile>

下列範例顯示客戶端認證使用者旅程圖。 需要第一個和最後一個編排流程步驟。

<UserJourneys>
  <UserJourney Id="ClientCredentialsJourney">
    <OrchestrationSteps>
      <!-- [Required] Do the client credentials -->
      <OrchestrationStep Order="1" Type="ClaimsExchange">
        <ClaimsExchanges>
          <ClaimsExchange Id="ClientCredSetupExchange" TechnicalProfileReferenceId="ClientCredentials_Setup" />
        </ClaimsExchanges>
      </OrchestrationStep>

      <!-- [Optional] Call a REST API or claims transformation -->
      <OrchestrationStep Order="2" Type="ClaimsExchange">
        <ClaimsExchanges>
          <ClaimsExchange Id="TokenAugmentation" TechnicalProfileReferenceId="TokenAugmentation" />
        </ClaimsExchanges>
      </OrchestrationStep>

      <!-- [Required] Issue the access token -->
      <OrchestrationStep Order="3" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
    </OrchestrationSteps>
  </UserJourney>
</UserJourneys>