在 Azure Active Directory B2C 自訂原則中定義 OAuth2 技術設定檔

發行項
01/11/2024

注意

在 Azure Active Directory B2C 中，自訂原則的主要用途為處理複雜的案例。在大部分情況下，我們建議使用內建的使用者流程。如果您尚未執行此操作，請於在 Active Directory B2C 中開始使用自訂原則中，了解自訂原則入門套件。

Azure Active Directory B2C (Azure AD B2C) 可提供對 OAuth2 通訊協定識別提供者的支援。 OAuth2 是用於授權和委派驗證的主要通訊協定。如需詳細資訊，請參閱 RFC 6749 The OAuth 2.0 授權架構。有了 OAuth2 技術設定檔，您就能與以 OAuth2 為基礎的識別提供者 (例如 Facebook) 同盟。與識別提供者同盟，可讓使用者使用其現有的社交或企業身分識別登入。

通訊協定

Protocol 元素的 Name 屬性必須設定為 OAuth2。例如，Facebook-OAUTH 技術設定檔的通訊協定是 OAuth2：

<TechnicalProfile Id="Facebook-OAUTH">
  <DisplayName>Facebook</DisplayName>
  <Protocol Name="OAuth2" />
  ...

輸入宣告

InputClaims 和 InputClaimsTransformations 元素不是必要項目。但您可以將更多參數傳送至您的識別提供者。下列範例會將 domain_hint 查詢字串參數 (包含 contoso.com 的值) 新增至授權要求。

<InputClaims>
  <InputClaim ClaimTypeReferenceId="domain_hint" DefaultValue="contoso.com" />
</InputClaims>

輸出宣告

OutputClaims 元素包含 OAuth2 識別提供者傳回的宣告清單。您可能需要將原則中定義的宣告名稱對應至識別提供者中定義的名稱。只要設定了 DefaultValue 屬性，也可以加入識別提供者未傳回的宣告。

OutputClaimsTransformations 元素可能含有 OutputClaimsTransformation 的集合，用於修改輸出宣告或產生新的輸出宣告。

下列範例顯示 Facebook 識別提供者傳回的宣告：

first_name 宣告對應至 givenName 宣告。
last_name 宣告對應至 surname 宣告。
沒有名稱對應的 displayName 宣告。
email 宣告沒有名稱對應。

技術設定檔也會傳回識別提供者未傳回的宣告：

包含識別提供者名稱的 identityProvider 宣告。
具有 socialIdpAuthentication 預設值的 authenticationSource 宣告。

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="id" />
  <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="first_name" />
  <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="last_name" />
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="email" />
  <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="facebook.com" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" />
</OutputClaims>

授權端點中繼資料

當 Azure AD B2C 將使用者導向 OAuth2 識別提供者 /authorize 端點時，便會開始授權流程。呼叫授權端點是與流程互動的過程，使用者要在其中採取動作。此時，系統會要求使用者在 OAuth2 識別提供者上完成登入。例如，輸入其使用者名稱與密碼。

Azure AD B2C 透過提供用戶端識別碼、範圍、重新導向 URI，以及它從識別提供者取得存取權杖所需的其他參數，來建立授權要求。此節說明授權端點中繼資料，可讓您設定對識別提供者 /authorize 端點的要求。

對授權端點的要求一律為 HTTP GET。下列範例示範如何呼叫授權端點。

GET https://login.contoso.com/oauth/v2/authorization?
client_id=12345
&response_type=code
&response_mode=query
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob
&scope=profile%20offline_access
&redirect_uri=https%3a%2f%2fabrikam.b2clogin.com%2fabrikam.onmicrosoft.com%2foauth2%2fauthresp
&state=...

下表列出授權端點中繼資料。

屬性	必要	描述
`authorization_endpoint`	是	依據 RFC 6749 的授權端點 URL。
`client_id`	Yes	識別提供者的應用程式識別碼。
`AdditionalRequestQueryParameters`	No	額外的要求查詢參數。例如，您可以將額外的參數傳送至識別提供者。您可以使用逗號分隔符號包含多個參數。
`response_mode`	No	識別提供者用來將結果傳送回 Azure AD B2C 的方法。可能的值：`query`、`form_post` (預設值) 或 `fragment`。
`scope`	No	根據 OAuth2 識別提供者規格定義的要求範圍。例如，`openid`、`profile` 和 `email`。
`UsePolicyInRedirectUri`	No	表明在建構重新導向 URI 時，是否使用原則。在設定識別提供者中的應用程式時，需要指定重新導向 URI。重新導向 URI 會指向 Azure AD B2C，`https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/oauth2/authresp`。如果指定 `true`，則需要為每個使用的原則新增重新導向 URI。例如：`https://{your-tenant-name}.b2clogin.com/{your-tenant-name}.onmicrosoft.com/{policy-name}/oauth2/authresp`。

權杖端點中繼資料

當使用者在識別提供者的授權端點上完成驗證之後，即會將包含授權 code 的回應傳回到 Azure AD B2C。 Azure AD B2C 會透過向識別提供者的 /token 端點傳送 POST 要求，來兌換存取權杖的授權碼。此節說明權杖端點中繼資料，可允許設定對識別提供者 /token 端點的要求。

下列 HTTP 要求顯示對識別提供者之權杖端點的 Azure AD B2C 呼叫。

POST https://contoso/oauth2/token 
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=12345&scope=profile offline_access&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...

下表列出權杖端點中繼資料。

屬性	必要	描述
`AccessTokenEndpoint`	是	權杖端點的 URL。例如： `https://www.linkedin.com/oauth/v2/accessToken` 。
`HttpBinding`	No	權杖端點的預期 HTTP 繫結。可能的值：`GET` 或 `POST`。
`AccessTokenResponseFormat`	No	存取權杖端點呼叫的格式。例如，Facebook 需要 HTTP GET 方法，但存取權杖回應採用 JSON 格式。可能的值：`Default`、`Json` 與 `JsonP`。
`ExtraParamsInAccessTokenEndpointResponse`	No	包含可在某些識別提供者的 AccessTokenEndpoint 回應中傳回的額外參數。例如，AccessTokenEndpoint 的回應中包含 `openid` 之類的額外參數，這是 ClaimsEndpoint 要求查詢字串中除了 access_token 以外的必要參數。多個參數名稱應逸出，並以逗號 ',' 分隔。
`token_endpoint_auth_method`	No	指定 Azure AD B2C 將驗證標頭傳送至權杖端點的方式。可能的值： `client_secret_post` (預設) 和 `client_secret_basic` 、 `private_key_jwt` 。如需詳細資訊，請參閱 OpenID Connect 用戶端驗證一節 \(英文\)。
`token_signing_algorithm`	No	當 `token_endpoint_auth_method` 設為 `private_key_jwt` 時，指定要使用的簽署演算法。可能的值：`RS256` (預設) 或 `RS512`。

設定 HTTP 繫結方法

根據預設，對權杖端點的要求會使用 HTTP POST。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">POST</Item>

下列 HTTP 呼叫示範如何使用 HTTP POST 要求來呼叫權杖端點：

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

對於需要在 /token 端點上使用 HTTP GET 方法的識別提供者，將 HttpBinding 中繼資料設定為 GET。請注意，在下列範例中，會將 AccessTokenResponseFormat 設定為 json，因為權杖端點會傳回 JSON 格式的回應。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>

GET /oauth2/token?client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

設定存取權杖回應格式

針對支援 HTTP POST 方法的識別提供者，預設會將 AccessTokenResponseFormat 設定為 json。如果識別提供者支援 HTTP GET 要求，您必須明確地將存取權杖回應格式設定為 json。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="HttpBinding">GET</Item>
<Item Key="AccessTokenResponseFormat">json</Item>

下列範例示範 JSON 格式的權杖端點回應：

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1637924390,
    "expires_in": 960000,
}

設定驗證方法

對權杖端點的要求一律需要驗證。 Azure AD B2C 預設會使用用戶端認證來提供識別提供者。根據預設，驗證方法是 client_secret_post，包括要求本文中的用戶端認證 (client_id 和 client_secret)。

下列對權杖端點的 HTTP 要求會在 POST 資料中包含 client_id 和 client_secret。如果是 GET 要求，client_id 和 client_secret 則會包含在查詢字串參數中。

POST /oauth2/token

client_id=abcd&client_secret=1234&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

針對要求在其 /token 端點上使用 HTTP 基本驗證的識別提供者，將 token_endpoint_auth_method 中繼資料設定為 client_secret_basic。使用這種類型的驗證方法時，會使用 HTTP 基本驗證配置來將用戶端認證傳遞至識別提供者。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">client_secret_basic</Item>

下列 HTTP 要求示範如何使用 HTTP 基本驗證來呼叫權杖端點。授權標頭包含用戶端識別碼和用戶端密碼，格式為以 Base64 編碼的 client_ID:client_secret。

POST /oauth2/token

Authorization: Basic YWJjZDoxMjM0

redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

針對支援私密金鑰 JWT 驗證的識別提供者，將 token_endpoint_auth_method 中繼資料設定為 private_key_jwt。使用這種類型的驗證方法時，提供給 Azure AD B2C 的憑證會用來產生已簽署的判斷提示，並透過 client_assertion 參數傳遞至識別提供者。將 client_assertion_type 設定為 urn:ietf:params:oauth:client-assertion-type:jwt-bearer。 token_signing_algorithm 中繼資料會指定 JWT 權杖的簽署演算法。

<Item Key="AccessTokenEndpoint">https://contoso.com/oauth2/token</Item>
<Item Key="token_endpoint_auth_method">private_key_jwt</Item>
<Item Key="token_signing_algorithm">RS256</Item>

下列 HTTP 要求示範如何使用私密金鑰 JWT 驗證來呼叫權杖端點。

POST /oauth2/token

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjJFRFg0dWRYeDIxbXNoaXdJVzczMUY3OUZSbFJiUDZXVXJyZmktR1RFeVkifQ.eyJpc3MiOiJhYmNkIiwiZXhwIjoxNjM3OTI5ODY0LCJuYmYiOjE2Mzc5Mjk1NjQsImF1ZCI6Imh0dHBzOi8vNWRlNC0xMDktNjQtMTI0LTUzLm5ncm9rLmlvL2FjY2Vzc190b2tlbiIsImp0aSI6IjVxQWlGV2lEODNDbU1KWWNrejBRdGc9PSIsInN1YiI6ImFiY2QiLCJpYXQiOjE2Mzc5Mjk1NjR9.C4OtRnrLaQatpT5LP45O5Nb418S4v8yZi_C42ld440w&client_id=abcd&client_assertion_type=urn%3aietf%3aparams%3aoauth%3aclient-assertion-type%3ajwt-bearer&redirect_uri=https%3a%2f%2fcontoso.b2clogin.com%2fcontoso.onmicrosoft.com%2foauth2%2fauthresp&code=12345&grant_type=authorization_code

使用者資訊端點中繼資料

在 Azure AD B2C 從 OAuth2 識別提供者取得存取權杖之後，就會呼叫使用者資訊端點。使用者資訊端點 (也稱為宣告端點) 是設計來擷取已經過驗證之使用者的相關宣告。 Azure AD B2C 會使用持有人權杖驗證 \(英文\)，來向識別提供者使用者資訊端點進行驗證。持有人權杖是 Azure AD B2C 從識別提供者 /token 端點取得的存取權杖。

對使用者資訊端點的要求一律為 HTTP GET。存取權杖會在名為 access_token 的查詢字串參數中傳送。下列 HTTP 要求會使用查詢字串參數中的存取權杖，來顯示對使用者資訊端點的呼叫。

GET /oauth2/claims?access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

下表列出使用者資訊端點中繼資料。

屬性	必要	描述
`ClaimsEndpoint`	是	使用者資訊端點的 URL。例如： `https://api.linkedin.com/v2/me` 。
`ClaimsEndpointAccessTokenName`	No	存取權杖查詢字串參數的名稱。預設值：`access_token`。
`ClaimsEndpointFormatName`	No	格式查詢字串參數的名稱。例如，您可以在 LinkedIn 宣告端點 `https://api.linkedin.com/v1/people/~?format=json` 中將名稱設定為 `format`。
`ClaimsEndpointFormat`	No	格式查詢字串參數的值。例如，您可以在 LinkedIn 宣告端點 `https://api.linkedin.com/v1/people/~?format=json` 中將值設定為 `json`。
`BearerTokenTransmissionMethod`	No	指定如何傳送權杖。預設方法是查詢字串。若要以要求標頭的形式傳送權杖，請設定為 `AuthorizationHeader`。
`ExtraParamsInClaimsEndpointRequest`	No	包含可在某些識別提供者的 ClaimsEndpoint 要求中傳回的額外參數。多個參數名稱應逸出，並以逗號 ',' 分隔。

設定存取權杖查詢字串參數

使用者資訊端點可能會要求在特定查詢字串參數中傳送存取權杖。若要變更包含存取權杖之查詢字串參數的名稱，請使用 ClaimsEndpointAccessTokenName 中繼資料。在下列範例中，會將存取權杖查詢字串參數設定為 token。

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointAccessTokenName">token</Item>

下列 HTTP 呼叫示範如何在 ClaimsEndpointAccessTokenName 已設定為 token 的情況下呼叫使用者資訊端點：

GET /oauth2/claims?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

設定宣告格式

ClaimsEndpointFormatName 和 ClaimsEndpointFormat 可讓您將機碼/值組查詢字串參數傳送至使用者資訊端點。下列範例會設定名為 format 的查詢字串參數，且值為 json。

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="ClaimsEndpointFormatName">format</Item>
<Item Key="ClaimsEndpointFormat">json</Item>

下列 HTTP 要求示範如何在已設定的 ClaimsEndpointFormatName 和 ClaimsEndpointFormat 的情況下呼叫使用者資訊端點。

GET /oauth2/claims?format=json&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

設定持有人權杖傳輸方法

預設會透過查詢字串參數，將存取權杖傳送至識別提供者使用者資訊端點。若要在 HTTP Authorization 標頭中傳送權杖，請將 BearerTokenTransmissionMethod 中繼資料設定為 AuthorizationHeader。

<Item Key="ClaimsEndpoint">https://contoso.com/oauth2/claims</Item>
<Item Key="BearerTokenTransmissionMethod">AuthorizationHeader</Item>

下列 HTTP 要求示範當 BearerTokenTransmissionMethod 設定為 AuthorizationHeader 時，如何傳遞存取權杖。

GET /oauth2/claims

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

傳遞權杖端點所傳回的參數

某些識別提供者會要求將從權杖端點傳回的額外參數傳遞至使用者資訊端點。例如，來自權杖端點的回應會包含名為 resource 的參數，其為使用者資訊端點的必要參數 (除了存取權杖之外)。使用 ExtraParamsInClaimsEndpointRequest 中繼資料來指定要傳遞的任何額外參數。多個參數名稱應逸出，並以逗號 ',' 分隔。

下列 JSON 示範具有名為 resource 之參數的權杖端點所傳回的 JSON 承載。

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...",
    "token_type": "Bearer",
    "not_before": 1549647431,
    "expires_in": 960000,
    "resource": "f2a76e08-93f2-4350-833c-965c02483b11"
}

若要將 resource 參數傳遞至使用者資訊端點，請新增下列中繼資料：

<Item Key="ExtraParamsInClaimsEndpointRequest">resource</Item>

下列 HTTP 要求示範如何將 resource 參數傳遞至使用者資訊端點。

GET /oauth2/claims?resource=f2a76e08-93f2-4350-833c-965c02483b11&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IlBFcG5...

結束工作階段端點

若要將使用者登出應用程式，請將使用者重新導向 Azure AD B2C 登出端點 (針對 OAuth2 和 OpenID Connect) 或傳送 LogoutRequest (針對 SAML)。 Azure AD B2C 將會從瀏覽器中清除使用者的工作階段。收到登出要求時，Azure AD B2C 會嘗試登出使用者可能已登入的任何同盟識別提供者。 OAuth2 識別提供者的登出 URI 會設定於 end_session_endpoint 中繼資料中。當使用者透過 Azure AD B2C 登出您的應用程式時，將建立隱藏的 iframe，以在其 Azure AD B2C 登出頁面上呼叫 end_session_endpoint。

下表列出使用者資訊端點中繼資料。

屬性	必要	描述
`end_session_endpoint`	是	根據 RFC 6749 的結束工作階段端點 URL。
`SingleLogoutEnabled`	No	指出在登入期間，技術設定檔是否會嘗試從同盟識別提供者登出。如需詳細資訊，請參閱 Azure AD B2C 工作階段登出。可能的值：`true` (預設) 或 `false`。

OAuth2 一般中繼資料

下表列出 OAuth2 識別提供者的一般中繼資料。中繼資料會描述 OAuth2 技術設定檔如何處理權杖驗證、取得宣告，以及回應錯誤訊息。

屬性	必要	描述
`IdTokenAudience`	否	id_token 的對象。如果已指定，Azure AD B2C 會檢查權杖是否在識別提供者傳回的宣告中，以及是否等於指定的宣告。
`ProviderName`	No	識別提供者的名稱。
`ResponseErrorCodeParamName`	No	包含透過 HTTP 200 (Ok) 傳回之錯誤訊息的參數名稱。
`IncludeClaimResolvingInClaimsHandling`	No	針對輸入和輸出宣告，指定技術設定檔中是否包含宣告解析。可能的值為：`true` 或 `false` (預設)。如果您想要在技術設定檔中使用宣告解析器，請將此設定為 `true`。
`ResolveJsonPathsInJsonTokens`	No	指出技術設定檔是否會解析 JSON 路徑。可能的值為：`true` 或 `false` (預設)。使用此中繼資料，從巢狀 JSON 元素中讀取資料。在 OutputClaim 中，將 `PartnerClaimType` 設定為您要輸出的 JSON 路徑元素。例如，`firstName.localized` 或 `data[0].to[0].email`。

密碼編譯金鑰

CryptographicKeys 元素包含下列屬性：

屬性	必要	描述
`client_secret`	是	識別提供者應用程式的用戶端密碼。只有在 response_types 中繼資料設為 `code` 時，才需要密碼編譯金鑰。在此情況下，Azure AD B2C 會進行另一次呼叫，以交換存取權杖的授權碼。如果將中繼資料設定為 `id_token`，則可省略密碼編譯金鑰。
`assertion_signing_key`	No	當 `token_endpoint_auth_method` 中繼資料設定為 `private_key_jwt` 時，請提供要用來簽署 JWT 金鑰的 X509 憑證。 OAuth2 識別提供者應為您提供此金鑰。

重新導向 URI

在設定識別提供者的重新導向 URI 時，請輸入 https://{tenant-name}.b2clogin.com/{tenant-name}.onmicrosoft.com/oauth2/authresp。務必使用您的租用戶名稱 (例如 contosob2c) 來取代 {tenant-name}。重新導向 URI 必須全部小寫。

後續步驟

了解如何將識別提供者新增至 Azure Active Directory B2C 租用戶

共用方式為