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

概要

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

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

API コネクタは、API 呼び出しの HTTP エンドポイント URL と認証を定義することで、API エンドポイントを呼び出すために必要な情報を Azure AD B2C に提供します。 API コネクタを構成したら、それをユーザーフローの特定のステップに対して有効にすることができます。 ユーザーがサインアップ フローでそのステップに到達すると、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 サービスの呼び出し

この相互作用には、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 クレーム プロバイダーに送信する方法を構成できます。 指定できる値は次のとおりです。

• 本文。HTTP POST 要求本文で JSON 形式で送信されます。
• フォームは、アンパサンド '&' で区切られたキー値の形式で HTTP POST リクエスト本文で送信されます。
• HTTP GET 要求ヘッダーで送信されるヘッダー。
• HTTP GET 要求クエリ文字列で送信される QueryString。

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

データの受信

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データ型の場合は、0001-01-01T00: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 技術プロファイルを直接参照する場合、ユーザーは関連するエラー メッセージを含む証明書利用者アプリケーションにリダイレクトされます。

• API コネクタを追加してサインアップ エクスペリエンスを変更する方法について説明します
• 外部要求を使用してトークンを強化する API コネクタを追加する方法について説明します
• API コネクタをセキュリティで保護する方法について説明します
• サンプルから始めましょう

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

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