Azure AD B2C の API コネクタについて

[アーティクル]
06/01/2023

開始する前に、[ポリシーの種類の選択] セレクターを使用して、設定するポリシーの種類を選択します。 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 プロバイダーとのフェデレーションを行った後 - 当てはまるのはサインアップエクスペリエンスのみです
ユーザーを作成する前 - 当てはまるのはサインアップエクスペリエンスのみです
トークンを送信する前 (プレビュー) - サインアップとサインインに当てはまります

サインアッププロセスのこの手順での 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 サービスの要求交換の図

注意

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 コネクタを有効にできる場所

ユーザーを作成する前

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

RESTful サービスの呼び出し

データの送信

データの受信

null 値の処理

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

REST API をローカライズする

エラーメッセージの処理

REST API の開発

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

概要

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

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

ユーザーを作成する前

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

RESTful サービスの呼び出し

データの送信

データの受信

null 値の処理

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

REST API をローカライズする

エラー メッセージの処理

REST API の開発

次のステップ

フィードバック

その他のリソース

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

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

エラーメッセージの処理