次の方法で共有

カスタム認証拡張機能の概要

  • [アーティクル]

Microsoft Entra ID 認証パイプラインは、ユーザー資格情報の検証、条件付きアクセス ポリシー、多要素認証、セルフサービス パスワード リセットなど、いくつかの組み込み認証イベントで構成されます。

Microsoft Entra カスタム認証拡張機能を使用すると、認証フロー内の特定のポイントで独自のビジネス ロジックを使用して認証フローを拡張できます。 カスタム認証拡張機能は、基本的にイベント リスナーであり、アクティブ化されると、ワークフロー アクションを定義する REST API エンドポイントへの HTTP 呼び出しを行います。

たとえば、カスタム クレーム プロバイダーを使用して、トークンが発行される前に外部ユーザー データをセキュリティ トークンに追加できます。 属性コレクション ワークフローを追加して、サインアップ時にユーザーが入力した属性を検証できます。 この記事では、Microsoft Entra ID カスタム認証拡張機能の概要について説明します。

Microsoft Entra カスタム認証拡張機能の概要ビデオでは、カスタム認証拡張機能の主な機能の概要を説明します。

コンポーネント

構成する必要があるコンポーネントは 2 つあります。Microsoft Entra のカスタム認証拡張機能と REST API です。 カスタム認証拡張機能は、REST API エンドポイント、REST API を呼び出すタイミング、および REST API を呼び出す資格情報を指定します。

このビデオでは、Microsoft Entra カスタム認証拡張機能の構成について詳しく説明し、最適な実装のためのベスト プラクティスと貴重なヒントを提供します。

サインイン フロー

次の図は、カスタム拡張機能と統合されたサインイン フローを示しています。

外部ソースからの要求で拡張されているトークンを示す図。

  1. ユーザーがアプリにサインインしようとすると、Microsoft Entra サインイン ページにリダイレクトされます。
  2. ユーザーが認証で特定の手順を完了すると、イベント リスナーがトリガーされます。
  3. カスタム認証拡張機能を使うと、REST API エンドポイントに HTTP 要求が送信されます。 要求には、イベント、ユーザー プロファイル、セッション データ、およびその他のコンテキスト情報に関する情報が含まれています。
  4. REST API はカスタム ワークフローを実行します。
  5. REST API は Microsoft Entra ID に HTTP 応答を返します。
  6. Microsoft Entra カスタム認証拡張機能 は応答を処理し、イベントの種類と HTTP 応答ペイロードに基づいて認証をカスタマイズします。
  7. アプリにトークンが返されます。

REST API エンドポイント

イベントが発生すると、Microsoft Entra ID は、所有している REST API エンドポイントを呼び出します。 REST API への要求には、イベント、ユーザー プロファイル、認証要求データ、およびその他のコンテキスト情報に関する情報が含まれています。

任意のプログラミング言語、フレームワーク、ホスティング環境を使用して、カスタム拡張機能 REST API を作成してホストできます。 手っ取り早く始めるには、C# Azure 関数を使用します。 Azure Functions を使用すると、最初に仮想マシン (VM) を作成したり、Web アプリケーションを発行したりしなくても、サーバーレス環境でコードを実行できます。

REST API で次の処理を行う必要があります。

  • REST API 呼び出しをセキュリティで保護するためのトークン検証。
  • ビジネス ロジック
  • HTTP 要求スキーマと応答スキーマの受信と送信の検証。
  • 監査とログ記録。
  • 可用性、パフォーマンス、およびセキュリティ制御。

Azure Functions で REST API を実行する開発者の場合は、 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet ライブラリを使用することを検討してください。これは、Microsoft Azure の組み込み認証機能を使用したトークン検証の実装に役立ちます。 さまざまなイベントの種類のデータ モデルを提供し、受信と送信の要求と応答の処理を開始するため、ビジネス ロジックにより焦点を当てることができます。

REST API を保護する

カスタム拡張機能と REST API 間の通信を適切にセキュリティで保護するには、複数のセキュリティ制御を適用する必要があります。

  1. カスタム認証拡張機能が REST API を呼び出すと、Microsoft Entra ID によって発行されたベアラー トークンを含む HTTP Authorization ヘッダーが送信されます。
  2. ベアラー トークンには、appid または azp 要求が含まれています。 それぞれの要求に 99045fe1-7639-4a75-9d4a-577b6ca3810f 値が含まれていることを検証します。 この値により、REST API を呼び出すのが Microsoft Entra ID であることが保証されます。
    1. V1 アプリケーションの場合は、appid 要求を検証します。
    2. V2 アプリケーションの場合は、azp 要求を検証します。
  3. ベアラー トークン aud 対象ユーザー要求には、関連付けられているアプリケーション登録の ID が含まれています。 REST API エンドポイントでは、その特定の対象ユーザーに対してベアラー トークンが発行されていることを検証する必要があります。
  4. ベアラー トークン iss 発行者要求には、Microsoft Entra 発行者 URL が含まれています。 テナントの構成に応じて、発行者 URL は以下のいずれかになります。
    • 従業員: https://login.microsoftonline.com/{tenantId}/v2.0。
    • 顧客: https://{domainName}.ciamlogin.com/{tenantId}/v2.0。

カスタム認証イベントの種類

このセクションでは、Microsoft Entra ID のカスタム認証イベントの一覧を示します。 イベントの詳細については、それぞれのドキュメントを参照してください。

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

トークン発行開始イベント OnTokenIssuanceStart は、トークンがアプリケーションに発行されるときにトリガーされます。 これは、カスタム クレーム プロバイダー内で設定されるイベントの種類です。 カスタム クレーム プロバイダーは、REST API を呼び出して外部システムから要求をフェッチするカスタム認証拡張機能です。 カスタム クレーム プロバイダーは、外部システムからの要求をトークンにマップし、ディレクトリ内の 1 つまたは複数のアプリケーションに割り当てることができます。

このビデオでは、Microsoft Entra カスタム クレーム プロバイダーを使用して、外部システムからの要求をセキュリティ トークンにマッピングする手順について説明します。

詳細については、 カスタム クレーム プロバイダーに関するページを参照してください。

属性コレクションの開始

属性コレクションの開始イベントをカスタム認証拡張機能と共に使用して、ユーザーから属性を収集する前にロジックを追加できます。 OnAttributeCollectionStart イベントは、属性コレクション ステップの開始時、かつ属性コレクション ページがレンダリングされる前に発生します。 これにより、値の事前入力やブロック エラーの表示などのアクションを追加できます。

注

属性コレクションの開始イベントは、外部テナントの Microsoft Entra 外部 ID のユーザー フローでのみ使用できます。 詳細については、独自のビジネス ロジックの追加に関する記事を参照してください。

属性コレクションを提出する

属性コレクションの送信イベントは、カスタム認証拡張機能と共に使用して、ユーザーから属性を収集した後にロジックを追加できます。 OnAttributeCollectionSubmit イベントは、ユーザーが属性を入力して送信した後にトリガーします。これにより、入力の検証や属性の変更などのアクションを追加できます。

注

属性コレクションの送信イベントは、外部テナントの Microsoft Entra 外部 ID のユーザー フローでのみ使用できます。 詳細については、独自のビジネス ロジックの追加に関する記事を参照してください。

ワンタイム パスコード送信イベント

OnOtpSend イベントは、ワンタイム パスコード電子メールがアクティブになるとトリガーされます。 REST API を呼び出して、独自の電子メール プロバイダーを使用できます。 このイベントを使用すると、サインアップ、パスワードのリセット、メールとワンタイム パスコードを使用したサインインを行うユーザーに、カスタマイズされた電子メールを送信できます。

OnOtpSend イベントがアクティブになると、Microsoft Entra は、所有する指定した REST API にワンタイム パスコードを送信します。 その後、REST API は、選択した電子メール プロバイダー (Azure Communication Service や SendGrid など) を使用して、アドレス、電子メールの件名からカスタム電子メール テンプレートを使用してワンタイム パスコードを送信し、ローカライズもサポートします。

注

ワンタイム パスコード送信イベントは、現在、外部テナントの Microsoft Entra External ID のユーザー フローでのみ使用できます。 詳細については、「1 回限りパスコード送信イベントのカスタム 電子メール プロバイダーを構成する を参照してください。

関連コンテンツ