Share via

在 Azure Active Directory B2C 自定義原則中定義 RESTful 技術配置檔

  • 發行項

注意

在 Azure Active Directory B2C 中， 自定義原則 的設計主要是為了解決複雜的案例。 在大部分情況下，我們建議您使用內 建的使用者流程。 如果您尚未這麼做，請了解開始使用 Active Directory B2C 中的自定義原則入門套件。

Azure Active Directory B2C （Azure AD B2C） 支援整合您自己的 RESTful 服務。 Azure AD B2C 會將數據傳送至輸入宣告集合中的 RESTful 服務，並在輸出宣告集合中接收數據。 如需詳細資訊，請參閱 在 Azure AD B2C 自定義原則中整合 REST API 宣告交換。

通訊協定

Protocol 元素的 Name 屬性必須設定為 Proprietary。 處理程式屬性必須包含 Azure AD B2C 所使用的通訊協定處理程式元件完整名稱：Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null。

下列範例顯示 RESTful 技術設定檔：

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

輸入宣告

InputClaims 元素包含要傳送至 REST API 的宣告清單。 您也可以將宣告的名稱對應至 REST API 中定義的名稱。 下列範例顯示原則與 REST API 之間的對應。 givenName 宣告會以 firstName 的形式傳送至 REST API，而 surname 則傳送為 lastName。 電子郵件宣告已設定為 。

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

InputClaimsTransformations 元素可能包含 InputClaimsTransformation 元素的集合，這些專案可用來修改輸入宣告，或在傳送至 REST API 之前產生新的宣告。

傳送 JSON 承載

REST API 技術配置檔可讓您將複雜的 JSON 承載傳送至端點。

若要傳送複雜的 JSON 承載：

  1. 使用 GenerateJson 宣告轉換來建置您的 JSON 承載。
  2. 在 REST API 技術設定檔中：
    1. 使用宣告轉換的 GenerateJson 參考來新增輸入宣告轉換。
    2. 將 SendClaimsIn 元數據選項設定為 body
    3. 將 ClaimUsedForRequestPayload 元數據選項設定為包含 JSON 承載的宣告名稱。
    4. 在輸入宣告中，新增包含 JSON 承載的輸入宣告參考。

下列範例 TechnicalProfile 會使用第三方電子郵件服務傳送驗證電子郵件（在此案例中為 SendGrid）。

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

輸出宣告

OutputClaims 元素包含 REST API 所傳回的宣告清單。 您可能需要將原則中定義的宣告名稱對應至 REST API 中定義的名稱。 您也可以包含 REST API 未傳回的宣告，只要您設定 DefaultValue 屬性即可。

OutputClaimsTransformations 元素可能包含 OutputClaimsTransformation 元素的集合，這些元素可用來修改輸出宣告或產生新的宣告。

下列範例顯示 REST API 所傳回的宣告：

  • 與 loyaltyNumber 宣告名稱對應的 MembershipId 宣告。

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

  • loyaltyNumberIsNew 宣告，其預設值設定為 true。
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

中繼資料

屬性 必要 描述
ServiceUrl Yes REST API 端點的 URL。
AuthenticationType Yes RESTful 宣告提供者所執行的驗證類型。 可能的值：None、、BasicBearer、 ClientCertificate或 ApiKeyHeader。
  • 值 None 表示 REST API 是匿名的。
  • 值 Basic 表示 REST API 受到 HTTP 基本身份驗證的保護。 只有已驗證的使用者，包括 Azure AD B2C，才能存取您的 API。
  • ClientCertificate [建議] 值表示 REST API 會使用用戶端憑證驗證來限制存取。 只有具有適當憑證的服務，例如 Azure AD B2C，才能存取您的 API。
  • 值 Bearer 表示 REST API 會使用用戶端 OAuth2 持有人令牌來限制存取。
  • 值 ApiKeyHeader 表示 REST API 受到 API 金鑰 HTTP 標頭保護，例如 x-functions-key。
AllowInsecureAuthInProduction No 指出是否可以AuthenticationType在生產環境中將 設定為 none （DeploymentModeTrustFrameworkPolicy 的 設定為 Production，或未指定）。 可能的值：true 或 false （預設值）。
SendClaimsIn No 指定如何將輸入宣告傳送至 RESTful 宣告提供者。 可能的值： Body （預設值）、Form、、 HeaderUrl 或 QueryString。
值 Body 是以 JSON 格式以要求本文傳送的輸入宣告。
值 Form 是在要求本文中以 『&』 分隔的索引鍵值格式傳送的輸入宣告。
值 Header 是要求標頭中傳送的輸入宣告。
值 Url 是在 URL 中傳送的輸入宣告，例如 https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}。 URL 的主機名部分不能包含宣告。
值 QueryString 是在要求查詢字串中傳送的輸入宣告。
每個叫用的 HTTP 動詞如下：
  • Body：發佈
  • Form：發佈
  • Header：獲取
  • Url：獲取
  • QueryString：獲取
ClaimsFormat No 目前無法使用，可以忽略。
ClaimUsedForRequestPayload No 字串宣告的名稱，其中包含要傳送至 REST API 的承載。
DebugMode No 以偵錯模式執行技術配置檔。 可能的值： true、 或 false （預設值）。 在偵錯模式中，REST API 可以傳回詳細資訊。 請參閱傳 回錯誤訊息 一節。
IncludeClaimResolvingInClaimsHandling No 針對輸入和輸出宣告，指定宣告解析是否包含在技術配置檔中。 可能的值： true、 或 false （預設值）。 如果您要在技術設定檔中使用宣告解析程式，請將此設定為 true。
ResolveJsonPathsInJsonTokens No 指出技術配置檔是否解析 JSON 路徑。 可能的值： true、 或 false （預設值）。 使用此元數據從巢狀 JSON 元素讀取數據。 在 OutputClaim 中，將設定PartnerClaimType為您要輸出的 JSON 路徑專案。 例如： firstName.localized、 或 data[0].to[0].email。
UseClaimAsBearerToken No 包含持有人令牌的宣告名稱。

錯誤處理

下列元數據可用來設定 REST API 失敗時所顯示的錯誤訊息。 錯誤訊息可以 當地語系化。

屬性 必要 描述
DefaultUserMessageIfRequestFailed No 所有 REST API 例外狀況的預設自定義錯誤訊息。
UserMessageIfCircuitOpen No 無法連線到 REST API 時的錯誤訊息。 如果未指定，則會傳回 DefaultUserMessageIfRequestFailed。
UserMessageIfDnsResolutionFailed No DNS 解析例外狀況的錯誤訊息。 如果未指定，則會傳回 DefaultUserMessageIfRequestFailed。
UserMessageIfRequestTimeout No 線上逾時時的錯誤訊息。如果未指定，則會傳回 DefaultUserMessageIfRequestFailed。

密碼編譯金鑰

如果驗證類型設定為 None， 則不會使用 CryptographicKeys 元素。

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

如果驗證類型設定為 Basic， CryptographicKeys 元素會包含下列屬性：

屬性 必要 描述
BasicAuthenticationUsername Yes 用來驗證的用戶名稱。
BasicAuthenticationPassword Yes 用來驗證的密碼。

下列範例顯示具有基本身份驗證的技術配置檔：

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

如果驗證類型設定為 ClientCertificate， CryptographicKeys 元素會包含下列屬性：

屬性 必要 描述
ClientCertificate Yes 要用來驗證的 X509 憑證（RSA 金鑰集）。 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

如果驗證類型設定為 Bearer， CryptographicKeys 元素會包含下列屬性：

屬性 必要 描述
BearerAuthenticationToken No OAuth 2.0 持有人令牌。 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

如果驗證類型設定為 ApiKeyHeader， CryptographicKeys 元素會包含下列屬性：

屬性 必要 描述
HTTP 標頭的名稱，例如 x-functions-key、 或 x-api-key。 Yes 用來驗證的金鑰。

注意

目前，Azure AD B2C 僅支援一個 HTTP 標頭進行驗證。 如果您的 RESTful 呼叫需要多個標頭，例如用戶端識別碼和客戶端密碼值，您必須以某種方式 Proxy 要求。

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

傳回驗證錯誤訊息

您的 REST API 可能需要傳回錯誤訊息，例如「在 CRM 系統中找不到使用者」。 如果發生錯誤，REST API 應該會傳回 HTTP 4xx 錯誤訊息，例如 400 （不正確的要求），或 409 （衝突） 回應狀態代碼。 回應本文包含 JSON 格式的錯誤訊息：

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}
屬性 必要 描述
version Yes 您的 REST API 版本。 例如：1.0.1
status Yes 類似 HTTP 回應狀態代碼的數位，且必須是 409。 REST 服務可以傳回 HTTP 4XX 狀態代碼，但 JSON 格式回應本文中提交的值 status 必須是 409。
code No 來自 RESTful 端點提供者的錯誤碼，會在啟用時 DebugMode 顯示。
requestId No 來自 RESTful 端點提供者的要求識別碼，會在啟用時 DebugMode 顯示。
userMessage Yes 向用戶顯示的錯誤訊息。
developerMessage No 問題的詳細資訊描述，以及如何修正此問題，這會在啟用時 DebugMode 顯示。
moreInfo No 指向其他資訊的 URI，會在啟用時 DebugMode 顯示。

下列範例顯示傳回錯誤訊息的 C# 類別：

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

下一步

如需使用 RESTful 技術配置檔的範例，請參閱下列文章：