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

2025-05-03

這很重要

自 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」)，請遵循下列步驟：

登入 Azure 入口網站。
確定您使用的目錄包含您的 Azure AD B2C 租用戶。選取入口網站工具列中的 [目錄 + 訂用帳戶] 圖示。
在 [入口網站設定] | [目錄 + 訂用帳戶] 頁面上，在 [目錄名稱] 清單中尋找 Azure AD B2C 目錄，然後選取 [切換]。
在 Azure 入口網站中，搜尋並選取 [Azure AD B2C]。
選取 [應用程式註冊]，然後選取 [[新增註冊]。
針對 [名稱]，輸入應用程式的名稱 (例如 my-api1)。保留 [重新導向 URI] 和 [支援的帳戶類型] 的預設值。
選取註冊。
當應用程式註冊完成之後，選取 [概觀]。
當您設定 Web 應用程式時，請記錄 [應用程式 (用戶端) 識別碼] 值，以供稍後使用。

步驟 1.1 定義 Web API 角色（範圍）

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

選取您建立的 Web API，例如 my-api1。
在 [管理] 底下，選取 [ 公開 API]。
選取 [應用程式識別碼 URI] 旁邊的 [設定] 連結。將預設值（GUID）替換為一個唯一的名稱（例如，api），然後選取 [儲存]。
複製 應用程式識別碼 URI。下列螢幕快照顯示如何複製應用程式識別碼 URI。
在 [管理] 底下，選取 [ 指令清單 ] 以開啟應用程式指令清單編輯器。在編輯器中找出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"
}],
```
在頁面頂端，選取 [ 儲存 ] 以儲存指令清單變更。

步驟 2：註冊應用程式

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

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

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

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

在 Azure 入口網站中，搜尋並選取 [Azure AD B2C]
選取 [應用程式註冊]，然後選取 [[新增註冊]。
輸入應用程式的 [名稱]。例如， ClientCredentials_app。
保留其他值，然後選取 [註冊]。
記錄 [應用程式 (用戶端) 識別碼]，以便在稍後的步驟中使用。

步驟 2.1 建立客戶端密碼

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

在 [管理] 下，選取 [ 憑證與秘密]。
選取 [新用戶端密碼]。
在 [ 描述 ] 方塊中，輸入客戶端密碼的描述（例如 clientsecret1）。
在 [到期] 下，選取祕密的有效持續時間，然後選取 [新增]。
記錄秘密的值。您可以在稍後的步驟中使用此值進行設定。

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

若要授與您的應用程式（App 1）許可權，請遵循下列步驟：

選取 [應用程式註冊]，然後選取您建立的應用程式（應用程式 1）。
在「管理」下方選取 [API 權限]。
在 [已設定的權限] 底下，選取 [新增權限]。
請選取「我的 API」索引標籤。
選取 Web 應用程式應授與存取權的 API （App 2）。例如，輸入 my-api1。
選取 [應用程式] 許可權。
在 [許可權] 底下，展開 應用程式，然後選取您稍早定義的範圍（例如 app.read 和 app.write）。
選取新增權限。
選取 [代表 <您的租用戶名稱> 授與管理員同意]。
選擇是。
選取 [重新整理]，然後驗證 [授與...] 會出現在這兩個範圍的 [狀態] 下方。

步驟 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>