Azure Active Directory B2C カスタム ポリシーで RESTful 技術プロファイルを定義するDefine a RESTful technical profile in an Azure Active Directory B2C custom policy

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

プロトコル

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 要素には、REST API に送信する前に入力要求を変更したり、新しい要求を生成したりするために使用される InputClaimsTransformation 要素のコレクションが含まれる場合があります。

JSON ペイロードを送信する

REST API 技術プロファイルを使用すると、複雑な JSON ペイロードをエンドポイントに送信できます。

複雑なJSONペイロードを送信するには:

1. GenerateJson 要求変換を使用して JSON ペイロードをビルドします。
2. REST API 技術プロファイルでは、次のようになります。
   1. GenerateJson クレーム変換への参照を使用して、入力クレーム変換を追加します。
   2. SendClaimsInメタデータオプションをbody
   3. ClaimUsedForRequestPayload メタデータ オプションを、JSON ペイロードを含む要求の名前に設定します。
   4. input 要求で、JSON ペイロードを含む input 要求への参照を追加します。

次の例では、 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 要求。

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

メタデータ

エラー処理

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

暗号化キー

認証の種類が 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 要素には次の属性が含まれます。

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

<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 要素には次の属性が含まれます。

<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 要素には次の属性が含まれます。

<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 要素には次の属性が含まれます。

<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"
}

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

• REST API 要求交換を Azure AD B2C カスタム ポリシーに統合する
• チュートリアル: サインアップ ユーザー フローに API コネクタを追加する
• チュートリアル: Azure Active Directory B2C のカスタム ポリシーに REST API 要求交換を追加する
• REST API サービスをセキュリティで保護する