API コネクタを使用して、外部 ID データ ソースでサインアップ ユーザー フローとカスタム ポリシーをカスタマイズし、拡張する

開始する前に、[ポリシーの種類の選択] セレクターを使用して、設定するポリシーの種類を選択します。 Azure Active Directory B2C には、ユーザーがアプリケーションを操作する方法を定義する 2 つの方法 (定義済みのユーザー フローを使用する、または完全に構成可能なカスタム ポリシーを使用する) があります。 この記事で必要な手順は、方法ごとに異なります。

概要

開発者または IT 管理者は、API コネクタを使用し、サインアップ ユーザー フローと REST API を統合してサインアップ体験をカスタマイズしたり、外部システムと統合したりできます。 たとえば、API コネクタを使用すると、次のことができます。

• ユーザー入力データの検証。 不正な、または無効なユーザー データに対する検証を行います。 たとえば、ユーザーが提供したデータを外部データ ストア内の既存のデータまたは許可されている値の一覧と照らし合わせて検証することができます。 無効な場合は、有効なデータを提供するようユーザーに求めることも、ユーザーがサインアップ フローを続行できないようにすることもできます。
• ユーザー ID を確認します。 本人確認サービスまたは外部 ID データ ソースを使用して、アカウント作成の決定のセキュリティ レベルを向上させます。
• カスタム承認ワークフローと統合します。 アカウントの作成を管理したり、制限したりするには、カスタム承認システムに接続します。
• 外部ソースの属性を使用してトークンを拡張します。 Azure AD B2C の外部にあるクラウド システム、カスタム ユーザー ストア、カスタム アクセス許可システム、レガシ ID サービスなどのソースのユーザーに関する属性を使用して、トークンを強化します。
• ユーザー属性を上書する ユーザーから収集された属性を再フォーマットし、それに値を割り当てます。 たとえば、ユーザーが名をすべて小文字または大文字で入力する場合に、名の最初の文字だけを大文字にするように書式設定できます。
• カスタム ビジネス ロジックを実行します。 ご利用のクラウド システム内で下流イベントをトリガーすれば、プッシュ通知の送信、企業データベースの更新、アクセス許可の管理、データベースの監査、およびその他のカスタム アクションの実行を行うことができます。

API コネクタは、API 呼び出しに関する HTTP エンドポイントの URL と認証を定義することで、API エンドポイントを呼び出すために必要な情報を Azure AD B2C に提供します。 API コネクタを構成したら、それをユーザーフローの特定のステップに対して有効にすることができます。 サインアップ フローでユーザーがこのステップに達すると、API コネクタが呼び出され、HTTP POST 要求として具体化されて、ユーザー情報 ("クレーム") を JSON 本文のキーと値のペアとして送信します。 API 応答は、ユーザー フローの実行に影響を与える可能性があります。 たとえば、API 応答によって、ユーザーのサインアップがブロックされたり、ユーザーが情報の再入力を求められたり、ユーザー属性が上書きされたりする可能性があります。

ユーザー フロー内で API コネクタを有効にできる場所

ユーザー フロー内には、API コネクタを有効にできる場所が 3 か所あります。

• サインアップ時に ID プロバイダーとのフェデレーションを行った後 - 当てはまるのはサインアップ エクスペリエンスのみです
• ユーザーを作成する前 - 当てはまるのはサインアップ エクスペリエンスのみです
• トークンを送信する前 (プレビュー) - サインアップとサインインに当てはまります

サインアップ時に ID プロバイダーとのフェデレーションを行った後

サインアップ プロセスのこの手順での API コネクタは、ID プロバイダー (Google、Facebook、Microsoft Entra ID など) でユーザーが認証された直後に呼び出されます。 このステップは、属性コレクション ページ (ユーザーに提示される、ユーザー属性を収集するためのフォーム) の前にあります。 ユーザーがローカル アカウントを使用して登録している場合、このステップは呼び出されません。 このステップでお客様が有効する可能性がある API コネクタのシナリオの例を次に示します。

• ユーザーが入力した電子メールまたはフェデレーション ID を使用して、既存のシステム内でクレームを検索します。 既存のシステムからこれらのクレームを返し、属性コレクション ページを事前に入力して、それらをトークンで返すことができるようにします。
• ソーシャル ID に基づいて許可または禁止リストを実装します。

ユーザーを作成する前

サインアップ プロセスのこのステップでの API コネクタは、属性コレクション ページが含まれている場合、その後に呼び出されます。 このステップは、ユーザー アカウントが作成される前に必ず呼び出されます。 お客様がサインアップ中にこのポイントで有効にする可能性があるシナリオの例を次に示します。

• ユーザー入力データを検証し、データの再送信をユーザーに求めます。
• ユーザーが入力したデータに基づいてユーザーのサインアップをブロックします。
• ユーザー ID を確認します。
• 外部システムに対して、ユーザーに関する既存のデータをクエリして、それをアプリケーション トークンで返すか、Microsoft Entra ID に格納します。

トークンを送信する前 (プレビュー)

注意

この機能はパブリック プレビュー段階にあります。

サインアップまたはサインイン プロセスの、このステップでの API コネクタは、トークンが発行される前に呼び出されます。 以下に、このステップで有効する可能性があるシナリオの例を示します。

• レガシ ID システム、人事システム、外部ユーザー ストアなど、ディレクトリとは異なるソースからのユーザーに関する属性を使用してトークンを強化します。
• 独自のアクセス許可システムに格納して管理するグループまたはロールの属性を使用してトークンを強化します。
• ディレクトリ内の要求の値に、要求の変換または操作を適用します。

Azure Active Directory B2C (Azure AD B2C) の基盤となる Identity Experience Framework は、ユーザー体験における RESTful API と統合することができます。 この記事では、RESTful 技術プロファイル を使用して RESTful サービスと対話するユーザー体験を作成する方法について説明します。

Azure AD B2C を使用すると、自分の RESTful サービスを呼び出すことで、独自のビジネス ロジックをユーザー体験に追加できます。 Identity Experience Framework は、RESTful サービスからデータを送受信して、要求を交換できます。 たとえば、次のように操作できます。

• 外部 ID データ ソースを使用して、ユーザー入力データを検証します。 たとえば、ユーザーによって入力されたメール アドレスが顧客データベースに存在するかどうかを確認できます。存在しない場合、エラーが表示されます。 サインアップなどのイベントが発生したときに呼び出しが行われるため、API コネクタは送信 Webhook をサポートする手段と考えることができます。
• 要求を処理します。 ユーザーが名をすべて小文字または大文字で入力する場合に、お使いの REST API は名の最初の文字だけを大文字にするように書式設定でき、それを Azure AD B2C に返すことができます。 ただし、カスタム ポリシーを使用する場合は、RESTful API の呼び出しよりも ClaimsTransformations が優先されます。
• 企業の基幹業務アプリケーションとさらに緊密に統合することでユーザー データを動的に拡充します。 RESTful サービスでは、ユーザーのメール アドレスを受け取り、顧客のデータベースを照会し、ユーザーのロイヤルティ番号を Azure AD B2C に返すことができます。 返された要求は、ユーザーの Microsoft Entra アカウントに格納するか、次のオーケストレーション手順で評価するか、アクセス トークンに含めることができます。
• カスタム ビジネス ロジックを実行します。 プッシュ通知の送信、企業データベースの更新、ユーザーの移行プロセスの実行、アクセス許可の管理、データベースの監査、およびその他のワークフローを実行できます。

注意

RESTful サービスから Azure AD B2C への応答が遅い場合または応答がない場合、タイムアウトは 30 秒であり、再試行回数は 2 回です (つまり、合計 3 回試行されます)。 現時点では、タイムアウトと再試行回数の設定を構成することはできません。

RESTful サービスの呼び出し

対話には REST API 要求と Azure AD B2C の間の情報の要求の交換が含まれています。 次の方法で、RESTful サービスとの統合を設計できます。

• 検証技術プロファイル。 RESTful サービスへの呼び出しは、指定された セルフアサート技術プロファイル の 検証技術プロファイル 内、または 表示コントロール の 確認表示コントロール 内で行われます。 検証技術プロファイルは、ユーザー体験を進める前に、ユーザーが入力したデータを検証します。 検証技術プロファイルでは、次を行うことができます。

  • REST API に要求を送信します。
  • 要求を検証し、ユーザーに表示されるカスタム エラー メッセージをスローします。
  • REST API から次のオーケストレーション手順に要求を送り返します。

• 要求の交換。 ユーザー体験のオーケストレーションの手順から REST API 技術プロファイルを直接呼び出して、ダイレクトな要求交換を構成することができます。 この定義は次に制限されます。

  • REST API に要求を送信します。
  • 要求を検証し、アプリケーションに返されるカスタム エラー メッセージをスローします。
  • REST API から次のオーケストレーション手順に要求を送り返します。

カスタム ポリシーによって定義されているユーザー体験の任意のステップで、REST API 呼び出しを追加できます。 たとえば、次のタイミングで REST API を呼び出すことができます。

• サインイン時の、Azure AD B2C によって資格情報が検証される直前。
• サインインの直後。
• Azure AD B2C によってディレクトリに新しいアカウントが作成される前。
• Azure AD B2C によってディレクトリに新しいアカウントが作成された後。
• Azure AD B2C によってアクセス トークンが発行される前。

データの送信

RESTful 技術プロファイル では、InputClaims 要素には、RESTful サービスに送信する要求のリストが含まれています。 要求の名前を、RESTful サービスで定義されている名前にマップし、既定値を設定して、要求リゾルバー を使用できます。

SendClaimsIn 属性を使用して、RESTful 要求プロバイダーに入力要求を送信する方法を構成できます。 指定できる値は、

• 本文、JSON 形式で HTTP POST 要求本文で送信されます。
• 書式、キーの値をアンパサンド "&" で区切った形式で HTTP POST 要求本文で送信されます。
• ヘッダー、HTTP GET 要求ヘッダーで送信されます。
• QueryString、HTTP GET 要求クエリ文字列で送信されます。

本文 のオプションが構成されると、REST API 技術プロファイルで複雑な JSON ペイロードをエンドポイントに送信できます。 詳細については、JSON ペイロードの送信 を参照してください。

データの受信

RESTful 技術プロファイル の OutputClaims 要素には、REST API によって返された要求のリストが含まれています。 お使いのポリシーで定義される要求の名前を、REST API で定義される名前にマップする必要があるかもしれません。 また、DefaultValue 属性を設定している限り、REST API ID プロバイダーにより返されない要求を追加することもできます。

RESTful 要求プロバイダーが解析する出力要求は、次のような、常にフラットな JSON 本文の応答を解析することを想定しています。

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

出力要求は次の xml スニペットのようになります。

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

null 値の処理

列の値が不明であるか存在しないときには、データベース内の null 値が使用されます。 null 値を持つ JSON キーは含めないでください。 次の例では、メールから null 値が返されます。

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

要素が null のときには次のいずれかになります。

• JSON からキーと値のペアが省略されます。
• Azure AD B2C の要求データ型に対応する値が返されます。 たとえば、string データ型の場合、空の文字列 "" が返されます。 integer データ型の場合、0 値の 0 が返されます。 dateTime データ型の場合、最小値の 1970-00-00T00:00:00.0000000Z が返されます。

次の例は、null 値の処理方法を示しています。 メールは JSON から省略されています。

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

入れ子になった JSON 本文を解析する

入れ子になった JSON 本文の応答を解析するには、ResolveJsonPathsInJsonTokens メタデータを true に設定します。 出力要求で、PartnerClaimType を出力する JSON パス要素に設定します。

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

出力要求は次の xml スニペットのようになります。

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

REST API をローカライズする

RESTful 技術プロファイルでは、現在のセッションの言語/ロケールを送信し、必要に応じて、ローカライズされたエラー メッセージを生成することができます。 要求リゾルバーを使用すると、ユーザー言語などのコンテキスト要求を送信できます。 このシナリオを示す RESTful 技術プロファイルの例を次に示します。

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</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.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

エラー メッセージの処理

REST API では、"ユーザーが CRM システムで見つかりませんでした。" などのエラー メッセージを返すことが必要になる場合があります。エラーが発生した場合、REST API では HTTP 409 のエラーメッセージ (競合応答の状態コード) を返す必要があります。 詳細については、「RESTful 技術プロファイル」を参照してください。

この動作は、検証技術プロファイルから REST API 技術プロファイルを呼び出すことによってのみ実現できます。 ユーザーはページのデータを修正して、ページの送信時に検証を再度実行します。

ユーザー体験から REST API の技術プロファイルを直接参照した場合、ユーザーは関連するエラー メッセージと共に証明書利用者アプリケーションにリダイレクトされます。

REST API の開発

REST API は、セキュリティで保護され、要求を JSON 形式で送受信できる限り、どのプラットフォームでも開発でき、任意のプログラミング言語で記述できます。

REST API サービスへの要求は Azure AD B2C サーバーから作成されます。 REST API サービスは、パブリックにアクセスできる HTTPS エンドポイントに公開する必要があります。 REST API の呼び出しは、Azure データ センターの IP アドレスから受け取ります。

開発が容易になるよう、Azure Functions の HTTP トリガーのようなサーバーレス クラウド関数を使用できます。

REST API サービスとその基になるコンポーネント (データベースやファイル システムなど) は、高可用性を備えるように設計する必要があります。

重要

エンドポイントは、Azure AD B2C のセキュリティ要件に準拠している必要があります。 以前の TLS バージョンと暗号は非推奨です。 詳細については、Azure AD B2C の TLS および暗号スイートの要件に関するページを参照してください。

次のステップ

• API コネクタを追加してサインアップ エクスペリエンスを変更する方法を確認します
• API コネクタを追加し、外部要求によってトークンを強化する方法を確認します
• API コネクタをセキュリティで保護する方法を確認します
• サンプルを使用して作業を開始します

RESTful 技術プロファイルの使用例については、次の記事を参照してください。

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

• 外部プロセスとの連携時に回復力を実現する方法について説明します
• 開発者のベスト プラクティスにより回復力を実現する方法について説明します。