共用方式為

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

  • 發行項

開始之前，請使用此頁面頂端的 [選擇原則類型] 選取器，選擇您要設定的原則類型。 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 範圍。

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

Diagram of a web app with web A P I call registrations and tokens.

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

在此步驟中，您註冊 Web API (App 2) 及其範圍。 稍後，您將這些範圍的權限授與您的應用程式 (App 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 應用程式時，請記錄 [應用程式 (用戶端) 識別碼] 值，以供稍後使用。

    Screenshot that demonstrates how to get a web A P I application I D.

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

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

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

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

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

  4. 複製 [應用程式識別碼 URI]。 下列螢幕擷取畫面顯示如何複製應用程式識別碼 URI。

    Screenshot shows how to copy the application I D.

  5. 在 [管理] 底下，選取 [資訊清單] 以開啟應用程式資訊清單編輯器。 在編輯器中，找出 appRoles 設定，並定義以 applications 為目標的應用程式角色。 資訊清單中的每個應用程式角色定義都必須有全域唯一識別碼 (GUID) 作為其 id 值。 在 Microsoft PowerShell 或線上 GUID 產生器中執行 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. 記錄 [應用程式 (用戶端) 識別碼]，以便在稍後的步驟中使用。

    Screenshot shows how to get the application I D.

步驟 2.1 建立用戶端密碼

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

  1. 在 [管理] 下，選取 [憑證和密碼]。

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

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

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

  5. 記錄祕密的 [值]。 您會在稍後的步驟中使用此值進行設定。

    Screenshot shows how to copy the application secret.

步驟 2.2 為 API 授與 Web 應用程式權限

若要為應用程式 (應用程式 1) 授與權限，請遵循下列步驟：

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

  2. 在 [管理] 之下選取 [API 權限]。

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

  4. 選取 [我的 API] 索引標籤。

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

  6. 選取 [應用程式權限]。

  7. 在 [權限] 下，展開 [應用程式]，然後選取您稍早定義的範圍 (例如 app.read 和 app.write)。

    Screenshot shows how to grant the application A P I permissions.

  8. 選取新增權限。

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

  10. 選取 [是]。

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

步驟 3：取得存取權杖

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

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

  • 使用您的 Azure AD B2C 租用戶名稱取代 <tenant-name>。 例如： contoso.b2clogin.com 。
  • 以使用者流程的完整名稱或自訂原則取代 <policy>。 請注意，所有類型的使用者流程和自訂原則都支援用戶端認證流程。 您可以使用您擁有的任何使用者流程或自訂原則，或是建立新的使用者流程，例如註冊或登入。
機碼 值
grant_type client_credentials
client_id 步驟 2 註冊應用程式的用戶端識別碼。
client_secret 步驟 2.1 建立用戶端密碼的用戶端密碼值。
範圍 (scope) 步驟 1.1 定義 Web API 角色 (範圍) 和 .default 中的應用程式識別碼 URI。 例如 https://contoso.onmicrosoft.com/api/.default 或 https://contoso.onmicrosoft.com/12345678-0000-0000-0000-000000000000/.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=33333333-0000-0000-0000-000000000000
&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": "33333333-0000-0000-0000-000000000000"
}

瞭解傳回存取權杖宣告。 下表列出與用戶端認證流程相關的宣告。

索賠 描述 值
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>

下一步

瞭解如何在 Azure AD B2C 中設定資源擁有者密碼認證流程