API コネクタを使用して外部ソースからの要求でトークンをエンリッチする

トークンを送信する前に (プレビュー) ステップに適用された API コネクタを使用して、外部ソースからの情報でアプリケーションのトークンを強化できます。 ユーザーがサインインまたはサインアップすると、Azure AD B2C は API コネクタで構成された API エンドポイントを呼び出し、クラウド サービス、カスタム ユーザー ストア、カスタム アクセス許可システム、レガシ ID システムなどのダウンストリーム サービスのユーザーに関する情報を照会できます。

サンプルのいずれかを使用して API エンドポイントを作成できます。

[前提条件]

• API エンドポイント。 サンプルのいずれかを使用して API エンドポイントを作成できます。

API コネクタを作成する

API コネクタを使用するには、まず API コネクタを作成してから、ユーザー フローで有効にします。

1. Azure portal にサインインします。

2. Azure サービスで、Azure AD B2C を選択します。

3. [API コネクタ] を選択し、[新しい API コネクタ] を選択します。

   

4. 呼び出しの表示名を指定します。 たとえば、 外部ソースからトークンをエンリッチします。

5. API 呼び出しの エンドポイント URL を 指定します。

6. [認証の種類] を選択し、API を呼び出すための認証情報を構成します。 API コネクタをセキュリティで保護する方法について説明します。

   

7. 保存 を選択します。

ユーザー フローで API コネクタを有効にする

サインアップ ユーザー フローに API コネクタを追加するには、次の手順に従います。

1. Azure portal にサインインします。

2. Azure サービスで、Azure AD B2C を選択します。

3. [ユーザー フロー] を選択し、API コネクタを追加するユーザー フローを選択します。

4. [API コネクタ] を選択し、ユーザー フローの [トークンを送信する前に (プレビュー)] ステップで呼び出す API エンドポイントを選択します。

   

5. 保存 を選択します。

この手順は、サインアップとサインイン (推奨)、サインアップ (推奨)、サインイン (推奨) のユーザー フローにのみ存在します。

この手順で API に送信される要求の例

この手順の API コネクタは、サインインとサインアップ中にトークンが発行されるときに呼び出されます。 API コネクタによってユーザー属性 ("要求") が HTTP POST 要求として具体化され、JSON 本文のキーと値のペアとして送信されます。 属性は Microsoft Graph ユーザー プロパティと同様にシリアル化されます。

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

API に送信される要求は、ユーザーに対して定義されている情報によって異なります。 要求で送信できるのは、 Azure AD B2C>User 属性 エクスペリエンスに記載されているユーザー プロパティとカスタム属性のみです。 カスタム属性は、ディレクトリの extension_<extensions-app-id>_CustomAttribute 形式に存在します。 API では、これと同じシリアル化された形式で要求を受け取ることを想定しています。 カスタム属性の詳細については、「 Azure AD B2C でのカスタム属性の定義」を参照してください。 さらに、これらの要求は、通常、この手順のすべての要求で送信されます。

• UI ロケール ('ui_locales') - デバイスで構成されているエンド ユーザーのロケール。 これを API で使用して、国際化された応答を返すことができます。
• ステップ ('step') - API コネクタが呼び出されたユーザー フローのステップまたはポイント。 このステップの値は「
• クライアント ID ('client_id') - エンド ユーザーがユーザー フローで認証しているアプリケーションの appId 値。 これは、アクセス トークン内のリソース アプリケーションのappId。
• objectId - ユーザーの識別子。 これを使用して、ダウンストリーム サービスに対してユーザーに関する情報をクエリできます。

この手順での Web API からの予期される応答の種類

Web API は、ユーザー フロー中に Microsoft Entra ID から HTTP 要求を受信すると、"継続応答" を返すことができます。

継続応答

継続応答は、ユーザー フローが次の手順 (トークンの発行) に進む必要があることを示します。 継続応答では、API は追加の要求を返すことができます。 API によって返され、トークンで返す要求は、組み込みの要求であるか、 カスタム属性として定義されている 必要があり、ユーザー フローの アプリケーション要求 構成で選択されている必要があります。 トークン内の要求値は、ディレクトリ内の値ではなく、API によって返される値になります。 一部の要求値は、API 応答で上書きできません。 API によって返される要求は、を除き、emailで見つかったセットに対応します。

応答の例

継続応答の例

HTTP/1.1 200 OK
Content-type: application/json
{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

このシナリオでは、企業の基幹業務ワークフローと統合することで、ユーザーのトークン データを充実させます。 サインアップ中、またはローカル アカウントまたはフェデレーション アカウントでのサインイン中に、Azure AD B2C は REST API を呼び出して、リモート データ ソースからユーザーの拡張プロファイル データを取得します。 このサンプルでは、Azure AD B2C はユーザーの一意の識別子 objectId を送信します。 その後、REST API はユーザーのアカウント残高 (乱数) を返します。 このサンプルを出発点として使用して、独自の CRM システム、マーケティング データベース、または任意の基幹業務ワークフローと統合します。 また、インタラクションを検証技術プロファイルとして設計することもできます。 これは、REST API が画面上のデータを検証し、要求を返す場合に適しています。 詳細については、「 チュートリアル: サインアップ ユーザー フローに API コネクタを追加する」を参照してください。

[前提条件]

• 「カスタムポリシーの使用を開始する」のステップを完了します。 サインアップとローカル アカウントでのサインインに有効なカスタム ポリシーが必要です。
• REST API 要求交換を Azure AD B2C カスタム ポリシーに統合する方法について説明します。

REST API エンドポイントを準備する

このチュートリアルでは、ユーザーの Azure AD B2C objectId がバックエンド システムに登録されているかどうかを検証する REST API が必要です。 登録されている場合、REST API はユーザーアカウントの残高を返します。 それ以外の場合、REST API は新しいアカウントをディレクトリに登録し、開始残高 50.00を返します。 次の JSON コードは、Azure AD B2C が REST API エンドポイントに送信するデータを示しています。

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

REST API がデータを検証したら、次の JSON データを含む HTTP 200 (OK) を返す必要があります。

{
    "balance": "760.50"
}

REST API エンドポイントのセットアップは、この記事の範囲外です。 Azure Functions サンプルを作成しました。 完全な Azure 関数コードには GitHub でアクセスできます。

要求を定義する

要求は、Azure AD B2C ポリシーの実行中にデータの一時的なストレージを提供します。 要求スキーマ セクション内で 要求 を宣言できます。

1. ポリシーの拡張ファイルを開きます。 たとえば、SocialAndLocalAccounts/TrustFrameworkExtensions.xml のようにします。
2. BuildingBlocks 要素を検索します。 要素が存在しない場合は、追加します。
3. ClaimsSchema 要素を見つけます。 要素が存在しない場合は、追加します。
4. ClaimsSchema 要素に次の要求を追加します。

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

RESTful API 技術プロファイルを追加する

RESTful テクニカル プロファイルは、独自の RESTful サービスとのインターフェイスをサポートします。 Azure AD B2C は、 InputClaims コレクション内の RESTful サービスにデータを送信し、 OutputClaims コレクション内のデータを受信します。 ファイルで TrustFrameworkExtensions.xml 要素を見つけ、次のように新しい要求プロバイダーを追加します。

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

この例では、は JSON ペイロード内のとして REST サービスに送信されます。 userLanguage要求の値には、現在のユーザー言語 ID が含まれています。 詳細については、 要求リゾルバーを参照してください。

RESTful API 技術プロファイルを構成する

REST API をデプロイしたら、次のような独自の REST API を反映するように REST-GetProfile 技術プロファイルのメタデータを設定します。

• ServiceUrl。 REST API エンドポイントの URL を設定します。
• SendClaimsIn。 入力要求を RESTful 要求プロバイダーに送信する方法を指定します。
• AuthenticationType。 RESTful クレーム プロバイダーによって実行される認証の種類 ( Basic や ClientCertificate
• AllowInsecureAuthInProduction。 本番環境では、このメタデータを false に設定してください。

その他の構成については、 RESTful 技術プロファイルのメタデータ を参照してください。 上記のコメントAuthenticationTypeAllowInsecureAuthInProduction、運用環境に移行するときに行う必要がある変更を指定します。 本番環境で RESTful API を保護する方法については、「 RESTful API のセキュリティ保護」を参照してください。

オーケストレーション ステップを追加する

ユーザー体験では、証明書利用者アプリケーションがユーザーの任意の要求を取得できるようにする、ポリシーの明示的なパスを指定します。 ユーザー体験は、トランザクションを成功させるために従う必要のあるオーケストレーション シーケンスとして表されます。 オーケストレーション ステップを追加または削除できます。 この場合は、ユーザーがサインアップするか、REST API 呼び出しを介してサインインした後に、アプリケーションに提供される情報を補強するために使用される新しいオーケストレーション ステップを追加します。

1. ポリシーのベース ファイルを開きます。 たとえば、SocialAndLocalAccounts/TrustFrameworkBase.xml のようにします。
2. <UserJourneys> 要素を検索します。 要素全体をコピーしてから削除します。
3. ポリシーの拡張ファイルを開きます。 たとえば、SocialAndLocalAccounts/TrustFrameworkExtensions.xml のようにします。
4. <UserJourneys> 要素を閉じた後、<ClaimsProviders>を拡張機能ファイルに貼り付けます。
5. <UserJourney Id="SignUpOrSignIn">を見つけて、最後のオーケストレーション ステップの前に次のオーケストレーション ステップを追加します。

   <OrchestrationStep Order="7" Type="ClaimsExchange">
     <ClaimsExchanges>
       <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
     </ClaimsExchanges>
   </OrchestrationStep>
   

6. 最後のオーケストレーション ステップをリファクタリングするには、 Order を 8 に変更します。 最後の 2 つのオーケストレーション手順は次のようになります。

   <OrchestrationStep Order="7" Type="ClaimsExchange">
     <ClaimsExchanges>
       <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
     </ClaimsExchanges>
   </OrchestrationStep>
   <OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />
   

7. ProfileEdit と PasswordReset のユーザー体験について、最後の 2 つの手順を繰り返します。

トークンに要求を含める

balance 要求を証明書利用者アプリケーションに返すには、出力要求を SocialAndLocalAccounts/SignUpOrSignIn.xml ファイルに追加します。 出力要求を追加すると、ユーザー体験が成功した後にトークンに要求が発行され、アプリケーションに送信されます。 証明書利用者セクション内の技術プロファイル要素を変更して、出力要求として balance を追加します。

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

ProfileEdit.xml、および PasswordReset.xml ユーザージャーニーに対してこの手順を繰り返します。 変更したファイル ( TrustFrameworkBase.xml、 TrustFrameworkExtensions.xml、 SignUpOrSignin.xml、 ProfileEdit.xml、 PasswordReset.xml) を保存します。

カスタム ポリシーをテストする

1. Azure portal にサインインします。
2. 複数のテナントにアクセスできる場合は、上部メニューの [設定] アイコンを選択して、[ ディレクトリ + サブスクリプション ] メニューから Microsoft Entra テナントに切り替えます。
3. Azure portal の左上隅にある [ すべてのサービス ] を選択し、[ アプリの登録] を検索して選択します。
4. [Identity Experience Framework] を選択します。
5. [ カスタムポリシーのアップロード] を選択し、変更したポリシーファイル ( TrustFrameworkBase.xml、 TrustFrameworkExtensions.xml、 SignUpOrSignin.xml、 ProfileEdit.xml、 PasswordReset.xml) をアップロードします。
6. アップロードしたサインアップまたはサインイン ポリシーを選択し、[ 今すぐ実行 ] ボタンをクリックします。
7. メールアドレスまたはFacebookアカウントを使用してサインアップできる必要があります。
8. アプリケーションに送り返されるトークンには、 balance 要求が含まれます。

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "11112222-bbbb-3333-cccc-4444dddd5555",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

ベスト プラクティスとトラブルシューティングの方法

サーバーレス クラウド機能の使用

Azure Functions の HTTP トリガーなどのサーバーレス機能を使用すると、API コネクタで使用する API エンドポイントを作成できます。 複雑なシナリオには、サーバーレス クラウド機能を使用して、他の Web API、データ ストア、および他のクラウド サービスを呼び出して起動することもできます。

ベスト プラクティス

次のことを確認してください。

• API は、上で説明した API 要求と応答のコントラクトに従っています。
• API コネクタの エンドポイント URL は、正しい API エンドポイントを指します。
• API によって、それが依存する受信済み要求の null 値が明示的に確認されます。
• API は、「 API コネクタのセキュリティ保護」で説明されている認証方法を実装します。
• API が可能な限り迅速に応答することで、スムーズなユーザー エクスペリエンスが保証されます。
  • Azure AD B2C は、応答を受信するまで最大 20 秒間 待機します。 何も受信しない場合は、API の呼び出しが もう一度実行 (再試行) されます。
  • サーバーレス関数またはスケーラブルな Web サービスを使用している場合は、本番環境で API を "起動" または "ウォーム" に保つホスティング プランを使用します。 Azure Functions の場合は、少なくとも Premium プラン を運用環境で使用することをお勧めします。
• API の高可用性を保証します。
• ダウンストリームの API、データベース、または API のその他の依存関係のパフォーマンスを監視し、最適化します。

ログの使用

サーバーレス クラウド機能の使用

Azure Functions の HTTP トリガーなどのサーバーレス機能を使用すると、API コネクタで使用する API エンドポイントを作成できます。 複雑なシナリオには、サーバーレス クラウド機能を使用して、他の Web API、データ ストア、および他のクラウド サービスを呼び出して起動することもできます。

ロギングの使用

一般に、予期しないエラー コード、例外、およびパフォーマンスの低下について API を監視するには、ご使用の Web API サービスによって有効になっているログ ツール (Application insights など) を使うと便利です。

• HTTP 200 または 400 以外の HTTP 状態コードを監視します。
• 401 または 403 HTTP 状態コードは、通常、認証に問題があることを示しています。 API コネクタで API の認証レイヤーとそれに対応する構成を再確認します。
• 開発では、必要に応じて、より積極的なログ レベル ("トレース" や "デバッグ" など) を使用します。
• APIの応答時間が長くならないように監視します。

さらに、Azure AD B2C は、ユーザー フローを介してユーザー認証中に発生する API トランザクションに関するメタデータをログに記録します。 これらを見つけるには:

1. Azure AD B2C に移動する
2. [ アクティビティ] で、[ 監査ログ] を選択します。
3. リスト ビューをフィルター処理する: [日付] で目的の時間間隔を選択し、[ アクティビティ] で [ API がユーザー フローの一部として呼び出されました] を選択します。
4. 個々のログを検査します。 各行は、ユーザー フロー中に呼び出そうとしている API コネクタを表します。 API 呼び出しが失敗し、再試行が発生した場合でも、1 つの行として表されます。 numberOfAttemptsは、API が呼び出された回数を示します。 この値は、 1または 2できます。 API 呼び出しに関するその他の情報については、ログで詳しく説明します。

• サンプルの使用を開始します。
• API コネクタをセキュリティで保護する

API をセキュリティで保護する方法については、次の記事を参照してください。

• チュートリアル: REST API 要求交換をオーケストレーション手順として Azure AD B2C ユーザー体験に統合する
• RESTful APIを保護
• リファレンス: RESTful 技術プロファイル