Azure Active Directory B2C カスタム ポリシーで RESTful 技術プロファイルを定義する

注意

Azure Active Directory B2C で、カスタム ポリシーは、主に、複雑なシナリオに取り組む用途向けに設計されています。 ほとんどのシナリオで、組み込みユーザー フローを使用することをお勧めします。 まだ行っていない場合は、Active Directory B2C でのカスタム ポリシーの概要に関する記事で、カスタム ポリシー スターター パックの詳細を確認してください。

Azure Active Directory B2C (Azure AD B2C) では、独自の RESTful サービスの統合に対するサポートを提供しています。 Azure AD B2C は、入力要求コレクションでデータを RESTful サービスに送信し、出力要求コレクションで返却データを受信します。 詳細については、「REST API 要求交換の Azure AD B2C カスタム ポリシーへの統合」を参照してください。

Protocol

Protocol 要素の Name 属性は Proprietary に設定する必要があります。 handler 属性には、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 として、surnamelastName として、REST API に送信されます。 email 要求はそのまま送信されます。

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

InputClaimsTransformations 要素には、REST API に送信する前に、入力要求を修正したり新しい要求を生成するために使用される、InputClaimsTransformation 要素のコレクションが存在する場合があります。

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 で定義される名前にマップする必要があるかもしれません。 DefaultValue 属性を設定している限り、REST API によって返されないクレームも含めることができます。

OutputClaimsTransformations 要素には、出力要求を修正したり新しい要求を生成するために使用される、OutputClaimsTransformation 要素のコレクションが含まれている場合があります。

次の例は、REST API により返される要求を示しています。

  • loyaltyNumber 要求名にマップされている MembershipId 要求。

また、技術プロファイルは、ID プロバイダーにより返されない要求も返します。

  • 既定値が true に設定されている loyaltyNumberIsNew 要求。
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

Metadata

属性 必須 説明
ServiceUrl はい REST API エンドポイントの URL。
AuthenticationType はい RESTful 要求プロバイダーにより実行されている認証の種類。 使用可能な値: NoneBasicBearerClientCertificate、または 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 いいえ 運用環境で AuthenticationTypenone に設定できるかどうかを示します (TrustFrameworkPolicyDeploymentModeProduction に設定するか、指定しません)。 有効な値: true または false (既定値)。
SendClaimsIn いいえ RESTful クレーム プロバイダーへの入力要求の送信方法を指定します。 指定できる値: Body (既定)、FormHeaderUrl、または QueryString
Body の値は、要求本文で、JSON 形式で送信される入力要求です。
Form の値は、要求本文で、キーの値をアンパサンド ' &' で区切った形式で送信される入力要求です。
Header の値は、要求本文で送信される入力要求です。
Url の値は、URL で送信される入力要求です。例: https://api.example.com/{claim1}/{claim2}?{claim3}={claim4} 。 URL のホスト名部分にクレームを含めることはできません。
QueryString の値は、要求クエリ文字列で送信される入力要求です。
それぞれによって呼び出される HTTP 動詞は次のとおりです。
  • Body:POST
  • Form:POST
  • Header:GET
  • Url:GET
  • QueryString:GET
ClaimsFormat いいえ 現在使用されていません。無視してもかまいません。
ClaimUsedForRequestPayload いいえ REST API に送信されるペイロードを含む文字列要求の名前。
DebugMode いいえ 技術プロファイルをデバッグ モードで実行します。 指定できる値: true または false (既定値)。 デバッグ モードでは、REST API はより多くの情報を返すことができます。 返却エラー メッセージのセクションを参照してください。
IncludeClaimResolvingInClaimsHandling いいえ 入力と出力の要求について、要求の解決を技術プロファイルに含めるかどうかを指定します。 指定できる値: true または false (既定値)。 技術プロファイルで要求リゾルバーを使用する場合は、これを true に設定します。
ResolveJsonPathsInJsonTokens いいえ 技術プロファイルが JSON パスを解決するかどうかを示します。 指定できる値: true または false (既定値)。 このメタデータを使用して、入れ子になった JSON 要素からデータを読み取ります。 OutputClaim で、PartnerClaimType を、出力する JSON パス要素に設定します。 例: firstName.localized、または data[0].to[0].email
UseClaimAsBearerToken いいえ ベアラー トークンを含む要求の名前。

エラー処理

次のメタデータを使用して、REST API の失敗時に表示されるエラー メッセージを構成できます。 エラー メッセージは、ローカライズできます。

属性 必須 説明
DefaultUserMessageIfRequestFailed いいえ すべての REST API 例外に関する既定のカスタマイズされたエラーメッセージ。
UserMessageIfCircuitOpen いいえ REST API に到達できない場合のエラーメッセージ。 指定しない場合、DefaultUserMessageIfRequestFailed が返されます。
UserMessageIfDnsResolutionFailed いいえ DNS 解決例外のエラーメッセージ。 指定しない場合、DefaultUserMessageIfRequestFailed が返されます。
UserMessageIfRequestTimeout いいえ 接続がタイムアウトしたときのエラーメッセージ。指定しない場合、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 はい 認証に使用されるユーザー名。
BasicAuthenticationPassword はい 認証に使用されるパスワード。

次の例は、基本的な認証を用いた技術プロファイルを示しています。

<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 はい 認証に使用する 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 いいえ 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-keyx-api-key など)。 はい 認証に使用されるキー。

注意

現時点で Azure AD B2C が認証でサポートするのは、1 つの HTTP ヘッダーのみです。 RESTful 呼び出しでクライアント ID やクライアント シークレット値などの複数のヘッダーが必要な場合は、何らかの方法で要求をプロキシ経由にする必要があります。

<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 によって 400 (無効な要求) や 409 (競合) の応答状態コードなど、HTTP 4xx エラー メッセージが返されます。 応答本文には、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 はい ご利用の REST API バージョン。 次に例を示します。1.0.1
status はい HTTP 応答の状態コードに似た番号。409 である必要があります。 REST サービスは HTTP 4XX 状態コードを返すことができますが、JSON 形式の status 応答本文にファイルされる値は 409.
code いいえ DebugMode が有効な場合に表示される、RESTful エンドポイント プロバイダーからのエラー コード。
requestId いいえ DebugMode が有効な場合に表示される、RESTful エンドポイント プロバイダーからの要求識別子。
userMessage はい ユーザーに示されるエラー メッセージ。
developerMessage いいえ DebugMode が有効な場合に表示される、問題の詳細な説明とそれを修正する方法。
moreInfo いいえ DebugMode が有効な場合に表示される、追加情報をポイントする URI。

次の例は、エラー メッセージを返す 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 技術プロファイルの使用例については、次の記事を参照してください。