独自のビジネス ロジックを使用して認証フローを拡張する

Microsoft Entra 外部 ID は、柔軟性を考慮して設計されています。 サインアップおよびサインイン ユーザー フロー内の組み込みの認証イベントに加えて、認証フロー内のさまざまなポイントにカスタム認証拡張機能を追加できます。 カスタム認証拡張機能は、基本的にイベント リスナーであり、アクティブ化されると、ワークフロー アクションを定義した REST API エンドポイントへの HTTP 呼び出しを行います。 たとえば、サインアップ時にユーザーが入力した属性を検証する "属性コレクション" ワークフローを追加したり、カスタム クレーム プロバイダーを使用して、発行前に外部ユーザー データをトークンに追加したりできます。

構成する必要があるコンポーネントには、カスタム認証拡張機能と REST API の 2 つがあります。 カスタム認証拡張機能によって、REST API エンドポイント、REST API を呼び出すタイミング、REST API を呼び出すための資格情報が指定されます。 カスタム認証拡張機能は、認証フロー内の次のポイントで作成できます。

• サインアップ中、属性コレクションの前後:
  • OnAttributeCollectionStart イベントは、属性コレクション ステップの開始時、かつ属性コレクション ページがレンダリングされる前に発生します。
  • OnAttributeCollectionSubmit イベントは、ユーザーが属性を入力して送信した後に発生します。
• OnTokenIssuanceStart イベントを使用してトークンが発行されるとき。これは、アプリケーションにトークンが発行される直前にトリガーされます。

これらのポイントのいずれかでカスタム認証拡張機能が構成されている場合、Microsoft Entra ID からユーザーが定義した REST API が呼び出されます。 REST API への要求には、イベント、ユーザー プロファイル、認証要求データ、およびその他のコンテキスト情報に関する情報が含まれています。 さらに、REST API でワークフロー アクションが実行されます。

この記事では、Microsoft Entra 外部 ID のカスタム認証拡張機能の概要を示します。

属性コレクションの開始イベントと送信イベント

カスタム認証拡張機能を使用して、セルフサービス サインアップ ユーザー フローの属性コレクションにワークフローを追加できます。 たとえば、属性フィールドにカスタム値を事前入力したり、ユーザーのエントリを検証したり、属性を変更したり、エラーを表示したりできます。 次の 2 つのイベントが有効になります。

• OnAttributeCollectionStart - OnAttributeCollectionStart イベントは、属性コレクション プロセスの開始時、かつ属性コレクション ページがレンダリングされる前に発生します。 このイベントは、ユーザーがドメインに基づいてサインアップできないようにしたり、収集する属性を追加したりするシナリオに使用できます。 OnAttributeCollectionStart イベントに対して、次のシナリオを構成できます。

  • continueWithDefaultBehavior - 属性コレクション ページを通常どおりにレンダリングします。
  • setPreFillValues - サインアップ フォームの属性を事前入力します。
  • showBlockPage - エラー メッセージを表示し、ユーザーのサインアップをブロックします。

• OnAttributeCollectionSubmit - OnAttributeCollectionSubmit イベントは、ユーザーが属性を入力して送信した後に発生します。 このイベントは、ユーザーが提供する情報の検証や変更などのシナリオで使用できます。 たとえば、招待コードやパートナー番号を検証したり、アドレス形式を変更したり、エラーを返したりすることができます。

  • continueWithDefaultBehavior - サインアップ フローを続行します。
  • modifyAttributeValues - サインアップ フォームでユーザーが送信した値を上書きします。
  • showValidationError - 送信された値に基づいてエラーを返します。
  • showBlockPage - エラー メッセージを表示し、ユーザーのサインアップをブロックします。

属性コレクションの開始イベントと送信イベントを構成するには、カスタム認証拡張機能 REST API を作成します。 イベントが発生すると、Microsoft Entra ID から REST API エンドポイントに HTTP 要求が送信されます。 REST API には、Azure 関数、Azure ロジック アプリ、または別の一般公開されている API エンドポイントを指定できます。 REST API エンドポイントは、実行するワークフロー アクションを定義する役割を担います。

詳細については、「属性コレクションのカスタム拡張機能をユーザー フローに追加する」を参照してください。

トークン発行開始イベント

トークン発行開始イベントは、ユーザーがすべての認証チャレンジを完了し、セキュリティ トークンがまもなく発行されるときにトリガーされます。

ユーザーが Microsoft Entra ID を使用してアプリケーションに対して認証を行うと、セキュリティ トークンがアプリケーションに返されます。 セキュリティ トークンには、名前、一意識別子、アプリケーション ロールなどの、ユーザーに関するステートメントであるクレームが含まれています。 セキュリティ トークンに含まれるクレームの既定のセット以外に、開発した REST API を使用して外部システムから独自のカスタム クレームを定義できます。

場合によっては、セカンダリ メール、課金レベル、機密情報などの、Microsoft Entra 外部のシステムに主要なデータが格納される場合があります。 外部システムの情報を Microsoft Entra ディレクトリに格納することが可能であるとは限りません。 このようなシナリオでは、カスタム認証拡張機能とカスタム クレーム プロバイダーを使用して、アプリケーションに返されるトークンにこの外部データを追加できます。

トークン発行イベント拡張機能には、次のコンポーネントが含まれます。

• カスタム クレーム プロバイダー。 カスタム クレーム プロバイダーは、外部システムからデータをフェッチするカスタム拡張機能の一種です。 アプリケーションに返されるセキュリティ トークンに追加する属性がカスタム クレーム プロバイダーによって指定されます。 複数のクレーム プロバイダーで同じカスタム拡張機能を共有できるため、異なる属性セットを各アプリケーションのセキュリティ トークンに追加できます。

• REST API エンドポイント。 イベントが発生すると、Microsoft Entra ID から REST API エンドポイントに HTTP 要求が送信されます。 REST API には、Azure 関数、Azure ロジック アプリ、またはその他の一般公開されている API エンドポイントを指定できます。 REST API エンドポイントは、ダウンストリーム データベース、既存の API、LDAP ディレクトリ、またはトークン構成に追加する属性を格納する他のストアとのインターフェイスを担当します。

  REST API からは、属性を含む Microsoft Entra ID に HTTP 応答、またはアクションが返されます。 REST API によって返される属性は、トークンに自動的には追加されません。 代わりに、任意の属性をトークンに含めるために、アプリケーションの要求マッピング ポリシーを構成する必要があります。

詳細については、次の情報を参照してください。

• カスタム認証拡張機能について
• カスタム クレーム プロバイダーを使用して、トークン発行イベント用にカスタム クレーム プロバイダーを構成する。

関連項目

• カスタム拡張機能のしくみの詳細については、「カスタム認証拡張機能」を参照してください。
• トークン発行開始イベントを使って REST API を作成する。
• トークン発行イベント用にカスタム クレーム プロバイダーを構成する。
• OpenID Connect のサンプル アプリケーションを使用して、属性コレクションの開始イベントと終了イベントのカスタム認証拡張機能を構成します。
• 最新の開発者向けコンテンツとリソースについては、Microsoft Entra 外部 ID デベロッパー センターを参照してください。