アカウント回復要求の検証用のカスタム認証拡張機能を作成する

この記事では、Microsoft Entraアカウントの復旧中に検証済みIDの要求を検証するカスタム認証拡張機能を設定する方法について説明します。アカウント回復フローでは、イベントリスナーを使用して要求検証プロセスを拡張できます。

OnVerifiedIdClaimValidation イベントは、ユーザーがアカウントの回復を開始し、検証済み ID 要求を提示するときに発生します。権限のあるデータソース (人事システム、アプリケーションデータベース、従業員レコードシステムなど) に対する要求の検証や、合格または失敗の決定の返しなどのアクションを追加できます。

カスタム認証拡張機能を作成するだけでなく、イベントに対して実行するワークフローアクションを定義する REST API を作成する必要があります。この記事では、サンプルリポジトリからデプロイされた C# Azure関数の使用を簡単に開始する方法について説明します。 Azure Functionsでは、最初に仮想マシン (VM) を作成したり、Web アプリケーションを発行したりする必要なく、サーバーレス環境でコードを実行できます。

前提条件

Azure サブスクリプション。既存のAzure アカウントがない場合は、無料試用版にサインアップします。
account 回復が有効になっているMicrosoft Entra ID テナント。
少なくともアプリケーション管理者のロールと認証管理者のロール。

どのように機能するのか

アカウントの回復中に、すべての認証方法を失ったユーザーは、ID を再確立する必要があります。カスタム認証拡張機能は、このフローに要求検証ステップを追加します。

OnVerifiedIdClaimValidation イベントは、復旧パイプラインの事前証明フックです。復旧を進める前に、カスタム検証ロジック（HR の照会、外部データベースチェック、パートナー信頼の検証）を適用できます。

手順 1: カスタム認証拡張機能 REST API を作成する (Azure関数アプリ)

この手順では、カスタム認証拡張機能の REST API として機能するAzure関数アプリをデプロイします。この関数は、アカウントの復旧中にMicrosoft Entra IDから検証済み ID 要求を受け取り、権限のあるデータソースに対して検証します。

サンプル関数は、ワンクリックデプロイとして使用できます。 Application Insights とストレージアカウントを使用して、従量課金プランに Azure Function App (.NET 10 の分離ワーカーモデル) をデプロイします。

1.1 Azure関数をデプロイする

[Azure] ボタンを選択します。

デプロイパラメーターを入力します。

パラメーター	Description
関数アプリ名	Function App のグローバルに一意の名前 (たとえば、 `contoso-recovery-claims`)。
リポジトリ URL	GitHub リポジトリの URL が事前に入力されています。
ブランチ	`main`
ストレージアカウントの種類	`Standard_LRS` (既定値)。
場所	ユーザーの近くのAzureリージョンを選択します。

ここでは省略可能なパラメーターを空白のままにします。次の手順で構成します。

[ 確認と作成]、[ 作成] の順に選択します。
デプロイが完了するまで待ちます (通常は 2 ~ 3 分)。

Note

ARM テンプレートは、 従量課金プラン (Y1/動的レベル) に Function App をデプロイします。スケーリングは完全に自動化されます。Azureは、受信要求ボリュームに基づいてインスタンスを追加および削除します。テストまたは開発の場合は、コールドスタートを回避するために Premium プラン (EP1 以降) に切り替えることができます。プランを変更するには、Function App >App Service プラン>Change App Service プランに移動>目的のレベルでプランを選択または作成します。

1.2 関数の URL を取得する

デプロイが完了したら、Function App リソースに移動します。
[ 関数>CustomClaimMatching>関数の URL を取得 を選択します。
URL をコピーします。 https://<your-function-app>.azurewebsites.net/api/CustomClaimMatching のように表示されます。

1.3 テストデータソースを構成する

テスト用に、この関数は、データソースとして読み取りアクセス権を持つ任意の Web サーバーでホストされているExcel ファイルをサポートします。運用環境では、HR API プロバイダーに切り替えることができます (運用への切り替え: HR API プロバイダーの使用を参照)。

リポジトリの SampleData フォルダーからサンプル Excel ファイルをダウンロードするか、次の列を使用して独自のファイルを作成します。

社員ID	UPN	firstName	lastName	fullName	dateOfBirth	ドキュメントタイプ	documentId	文書有効期限
E001	user@contoso.com	John	雌鹿	John Doe	1990-01-15	Passport	AB123456	2028-01-15

Tip

新しい要求を追加するには、要求名をヘッダーとして持つ列を追加します。この関数は、要求からの要求キーと列ヘッダーを動的に照合します。コードの変更は必要ありません。

Note

既定では、関数アプリは ドキュメント番号 (documentId) 要求のみを検証します。 firstName、dateOfBirth、employeeId などの追加の要求を照合するには、Azure関数コードで検証ロジックを更新します。

Web サーバー、ファイル共有、またはクラウドストレージサービス (Azure Blob Storage、SharePoint、HTTP アクセス可能な場所など) にファイルをアップロードします。
ファイルの直接ダウンロード URL を取得します。対話型サインインなしで URL にアクセスできる必要があります。

Azure ポータルで、Function App の>設定>環境変数に移動します。デプロイテンプレートでは、これらの変数が既定値で事前に作成されます。次のことを確認して更新します。

名前	アクション	価値
`ClaimsValidator__Provider`	確認 ( `excel`として事前に作成済み)	`excel`
`Excel__ShareUrl`	更新（空のまま事前に作成された）	Excel ファイルの直接ダウンロード URL。
`Excel__SheetName`	確認 ( `Sheet1`として事前に作成済み)	`Sheet1` (またはワークシート名)。

[適用] を選んでから、[確認] を選びます。

手順 2: カスタム認証拡張機能を作成して登録する

この手順では、Azure関数の呼び出しに使用Microsoft Entra IDカスタム認証拡張機能を登録します。カスタム認証拡張機能には、REST API エンドポイント、REST API から解析する要求検証アクション、および REST API に対する認証方法に関する情報が含まれています。

Note

最大 100 個のカスタム拡張機能ポリシーを使用できます。ただし、OnVerifiedIdClaimValidation イベントの種類では、テナントごとに 1 つのカスタム認証拡張機能のみが許可されます。

Azure Portal
Microsoft Graph

Microsoft Entra管理センターに少なくともアプリケーション管理者および認証管理者としてサインインします。
Entra ID>Enterprise apps>Custom 認証拡張機能に移動します。
[ カスタム拡張機能の作成] を選択します。
[基本] で OnVerifiedIdClaimValidation イベントを選択し、[次へ] を選択します。
エンドポイント構成で、次のプロパティを入力します。
- 名前： カスタム認証拡張機能の名前。たとえば、「 Account Recovery Claims Validation 」のように入力します。
- Target URL: Azure Function の URL。例えば： https://<your-function-app>.azurewebsites.net/api/CustomClaimMatching
- 説明： 拡張機能の説明。たとえば、「 Validates VID claims against HR data during account recovery 」のように入力します。
次へを選択します。
API 認証で、[新しいアプリ登録の作成] オプションを選択して、関数アプリを表すアプリ登録を作成します。
アプリに名前を付けます (例: Azure Functions authentication events API)。
次へを選択します。
[ 作成] を選択すると、カスタム認証拡張機能と関連付けられているアプリケーションの登録が作成されます。

アプリケーションを登録する

カスタム認証拡張機能を管理するテナントがホームテナントであるアカウントを使用して Graph Explorer にサインインします。このアカウントには、テナントでアプリケーション登録を作成および管理するための特権が必要です。

次の要求を実行します。

POST https://graph.microsoft.com/v1.0/applications
Content-type: application/json

{
    "displayName": "authenticationeventsAPI"
}

応答から、 id と appId の値を記録します。これらの値は、この記事の後半でそれぞれ {authenticationeventsAPI_ObjectId} と {authenticationeventsAPI_AppId} として参照されます。

authenticationeventsAPI アプリ登録のためのサービスプリンシパルを作成する

Graph エクスプローラーで、次の要求を実行します。 {authenticationeventsAPI_AppId}を、前の手順で記録した appId 値に置き換えます。

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
    "appId": "{authenticationeventsAPI_AppId}"
}

アプリ ID URI、アクセストークンのバージョン、必要なリソースアクセスを設定する

新しく作成したアプリケーションを更新して、アプリケーション ID URI の値、アクセストークンのバージョン、必要なリソースアクセスを設定します。

Graph エクスプローラーで、次の要求を実行します。

identifierUris プロパティでアプリケーション ID URI 値を設定します。 {Function_Url_Hostname}を、Azure関数 URL のホスト名 (例: contoso-recovery-claims.azurewebsites.net) に置き換えます。
{authenticationeventsAPI_AppId}を、前に記録した appId に置き換えます。
{authenticationeventsAPI_ObjectId}は、前に記録した ID に置き換えます。

identifierUris値の例はapi://contoso-recovery-claims.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444。この値は、この記事の後半で {functionApp_IdentifierUri}の代わりに使用する際に書き留めます。

PATCH https://graph.microsoft.com/v1.0/applications/{authenticationeventsAPI_ObjectId}
Content-type: application/json

{
    "identifierUris": [
        "api://{Function_Url_Hostname}/{authenticationeventsAPI_AppId}"
    ],
    "api": {
        "requestedAccessTokenVersion": 2,
        "acceptMappedClaims": null,
        "knownClientApplications": [],
        "oauth2PermissionScopes": [],
        "preAuthorizedApplications": []
    },
    "requiredResourceAccess": [
        {
            "resourceAppId": "00000003-0000-0000-c000-000000000000",
            "resourceAccess": [
                {
                    "id": "214e810f-fda8-4fd7-a475-29461495eb00",
                    "type": "Role"
                }
            ]
        }
    ]
}

カスタム認証拡張機能を登録する

次に、カスタム認証拡張機能を登録します。 Azure関数のアプリ登録と、Azure関数エンドポイント {Function_Url}に関連付けます。

Graph エクスプローラーで、次の要求を実行します。 {Function_Url}をAzure関数アプリの URL (たとえば、https://contoso-recovery-claims.azurewebsites.net/api/CustomClaimMatching) に置き換えます。 {functionApp_IdentifierUri}を、前の手順で設定したidentifierUris値に置き換えます。

委任された CustomAuthenticationExtension.ReadWrite.All 権限が必要です。

POST https://graph.microsoft.com/v1.0/identity/customAuthenticationExtensions
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.onVerifiedIdClaimValidationCustomExtension",
    "displayName": "Account Recovery Claims Validation",
    "description": "Validates VID claims against HR data during account recovery",
    "endpointConfiguration": {
        "@odata.type": "#microsoft.graph.httpRequestEndpoint",
        "targetUrl": "{Function_Url}"
    },
    "authenticationConfiguration": {
        "@odata.type": "#microsoft.graph.azureAdTokenAuthentication",
        "resourceId": "{functionApp_IdentifierUri}"
    },
    "clientConfiguration": {
        "timeoutInMilliseconds": 2000,
        "maximumRetries": 1
    }
}

作成されたカスタム認証拡張機能の ID 値を記録します。この記事の後半では、 {customExtensionObjectId}として使用します。

カスタム認証拡張機能が作成された後は、登録済みアプリに管理者の同意を付与します。これにより、カスタム認証拡張機能が API に対する認証を行えるようになります。

Entra ID>Enterprise apps>Custom 認証拡張機能に移動します。
一覧からカスタム認証拡張機能を選択します。
[ 概要 ] タブで、[ アクセス許可の付与 ] ボタンを選択して、登録済みのアプリに管理者の同意を与えます。カスタム認証拡張機能では、client_credentials を使用して、Receive custom authentication extension HTTP requests アクセス許可を使用してAzure関数アプリに対する認証を行います。 [Accept](承認) を選択します。

手順 3: カスタム認証拡張機能をアカウント回復ポリシーに追加する

次に、カスタム認証拡張機能を ID 検証プロファイルのアカウント検証設定に関連付け、復旧フロー中に呼び出されるようにします。

Azure Portal
Microsoft Graph

Microsoft Entra管理センターに少なくともアプリケーション管理者および認証管理者としてサインインします。
Entra ID>アカウント回復>本人確認プロファイルに移動します。
更新する ID 検証プロファイルを選択します (または、新しく作成します)。
[アカウントの検証] ステップで、[追加の要求の検証] で [有効] を [オン] に切り替えます。
[ 選択した拡張機能 ] ドロップダウンで、手順 2 で作成したカスタム認証拡張機能 (Account Recovery Claims Validation) を選択します。
[ 確認して最終処理]、[ 保存] の順に選択します。

カスタム認証拡張機能をアカウント回復フローにバインドする認証イベントリスナーを作成します。

カスタム認証拡張機能を管理するテナントがホームテナントであるアカウントを使用して Graph Explorer にサインインします。

次の要求を実行します。 {customExtensionObjectId}を、手順 2 で記録したカスタム認証拡張機能の ID に置き換えます。

委任された EventListener.ReadWrite.All 権限が必要です。

POST https://graph.microsoft.com/v1.0/identity/authenticationEventListeners
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.onVerifiedIdClaimValidationListener",
    "handler": {
        "@odata.type": "#microsoft.graph.onVerifiedIdClaimValidationCustomExtensionHandler",
        "customExtension": {
            "id": "{customExtensionObjectId}"
        }
    }
}

応答の ID 値を記録します。これは、アカウント回復イベントリスナーの {eventListenerId} です。

手順 4: 関数をテストする (認証を追加する前に)

認証を構成する前に (手順 5) 、関数の要求照合ロジックが直接呼び出されて機能することを確認します。この時点で、関数には認証が構成されていない必要があります。EasyAuth ID プロバイダーは構成されておらず、 EntraId__TenantId / EntraId__ClientId 環境変数は空である必要があります。

4.1 関数を直接テストする

Warnung

この手順では、認証が構成されていない状態で関数をテストします。これは開発とテスト専用です。運用環境では、認証なしで関数を公開しないでください。運用環境にデプロイする前に、手順 5 を完了して認証を構成します。

Note

認証 ID プロバイダーが構成されていない場合でも、Azure Functionsには Authorization: Bearer ヘッダーが必要です。ローカルテスト中に任意の値 (たとえば、 Bearer test) を渡すことができます。運用環境では、Microsoft Entra IDは有効なトークンを自動的に提供します。

ターミナルを開き、次のコマンドを実行します。

$body = @'
{
    "type": "microsoft.graph.authenticationEvent.verifiedIdClaimValidation",
    "source": "/tenants/<tenant-guid>/applications/<app-id>",
    "data": {
        "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationCalloutData",
        "tenantId": "<tenant-guid>",
        "authenticationContext": {
            "correlationId": "00000000-0000-0000-0000-000000000001",
            "user": {
                "userPrincipalName": "user@contoso.com"
            }
        },
        "verifiedIdClaimsContext": {
            "additionalInfo": {
                "employeeId": "E001"
            },
            "claims": {
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1990-01-15"
            }
        }
    }
}
'@

(Invoke-WebRequest -Method Post `
  -Uri "https://<your-function-app>.azurewebsites.net/api/CustomClaimMatching" `
  -ContentType "application/json" `
  -Headers @{ Authorization = "Bearer test" } `
  -Body $body).Content

応答を確認します。

成功した一致:

{
    "data": {
        "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.verifiedIdClaimValidation.pass"
            }
        ]
    }
}

一致しませんでした（一致しなかったクレームを返します）:

{
    "data": {
        "@odata.type": "microsoft.graph.onVerifiedIdClaimValidationResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.verifiedIdClaimValidation.failed",
                "failedClaims": ["dateOfBirth"]
            }
        ]
    }
}

手順 5: Azure関数を保護する

カスタム認証拡張機能Microsoft Entra、サーバー間フローを使用して、HTTP Authorization ヘッダーで Azure 関数に送信されるアクセストークンを取得します。特に運用環境で関数をAzureに発行する場合は、承認ヘッダーで送信されたトークンを検証する必要があります。

Azure関数を保護するには、次の手順に従って、受信トークンを検証するためのMicrosoft Entra認証を Azure Functions 認証イベント API アプリケーションの登録と統合します。

5.1 Azure関数に ID プロバイダーを追加する

Azure ポータルにサインインします。
以前にデプロイした Function App に移動して選択します。
左側のメニューで [ 認証 ] を選択します。
[ ID プロバイダーの追加] を選択します。
ID プロバイダーとして Microsoft を選択します。
[ テナントの選択] で、[ Workforce configuration (current tenant)]\(ワークフォース構成 (現在のテナント)\) を選択します。
App registration で、このディレクトリ内の既存のアプリ登録を選択を選択し、手順 2 で作成した Azure Functions 認証イベント API アプリの登録を選択します。
[ クライアントシークレットの有効期限] で、有効期限を選択します。
[ サポートされているアカウントの種類] で、[ 現在のテナント - シングルテナント] を選択します。
追加のチェックの下で次の手順を実行します。
- Client アプリケーション要件:特定のクライアントアプリケーションからの要求を許可を選択し、99045fe1-7639-4a75-9d4a-577b6ca3810f を追加します (これは、Microsoft Entra のカスタム認証拡張機能のファーストパーティアプリ ID です)。
- ID 要件: [ 任意の ID からの要求を許可する] を選択します。
- テナントの要件: [ 特定のテナントからの要求を許可する ] を選択し、従業員テナント ID を入力します。
[ 認証されていない要求] で、[ HTTP 401 Unauthorized: APIに推奨] を選択します。
Issuer URL に「https://login.microsoftonline.com/{tenantId}/v2.0」と入力します。ここで、{tenantId} はMicrosoft Entra テナントのテナント ID です。
[トークンストア] オプションの選択を解除します。
Add を選択して、Azure関数に認証を追加します。

5.2 OpenID Connect ID プロバイダーを使用する

Azure関数が、カスタム認証拡張機能が登録されているテナントとは異なるテナントでホストされている場合は、代わりに次の手順に従います。

Azure ポータルにサインインし、Function App に移動します。
左側のメニューで [ 認証 ] を選択します。
[ ID プロバイダーの追加] を選択します。
ID プロバイダーとして OpenID Connect を選択します。
Contoso Microsoft Entra ID などの名前を指定します。
Metadata エントリで、Document URL に次の URL を入力し、{tenantId}をMicrosoft Entraテナント ID に置き換えます。
```
https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration
```
App registration で、手順 2 で作成したAzure Functions認証イベント API アプリ登録のアプリケーション ID (クライアント ID) を入力します。
Microsoft Entra 管理センターで、Azure Functions 認証イベント API アプリ登録の証明書 & シークレットクライアントシークレットに移動し、新しいクライアントシークレットを作成します。シークレット値をコピーします。
Azure関数に戻り、Client シークレットを入力します。
[トークンストア] オプションの選択を解除します。
OpenID Connect ID プロバイダーを追加するには、[ 追加] を選択します。

手順 6: エンドツーエンドの復旧フローをテストする

Microsoft Entra 管理センターにサインインし、カスタム認証拡張機能がアクティブであり、ID 検証プロファイルに割り当てられているかどうかを確認します (手順 3)。
プライベートブラウザーウィンドウで、 https://myaccount.microsoft.com に移動し、アカウントの回復を開始します。
ID 証明の手順 (顔チェック、検証済み ID プレゼンテーション) を完了します。
OnVerifiedIdClaimValidation イベントが発生し、Azure関数が呼び出されます。この関数は、データソースに対する要求を検証し、成功または失敗を返します。
Application Insights で>関数が呼び出され、要求が検証されたことを確認します。
```
traces
| where message has "claims" or message has "validation"
| order by timestamp desc
| take 20
```

運用環境に切り替える: HR API プロバイダーを使用する

運用環境では、Excel プロバイダーから、組織の HR REST エンドポイントを呼び出す HR API プロバイダーに切り替えます。

関数アプリの 環境変数で、次を更新します。

名前	価値
`ClaimsValidator__Provider`	`hrapi`
`HrApi__BaseUrl`	HR API のベース URL (たとえば、 `https://hr.contoso.com/api`)。
`HrApi__AuthMode`	`apikey` または `oauth`。
`HrApi__ApiKey`	API キー (認証モード `apikey` 使用している場合)。
`HrApi__OAuthScope`	OAuth スコープ (認証モード `oauth` 使用している場合、たとえば、 `api://hr-api-app-id/.default`)。

oauth認証モードを使用する場合、関数は Function App のシステム割り当てマネージド ID を使用します。マネージド ID に、HR API のアプリ登録に対する適切なアプリロールを付与します。

HR API では、次のコントラクトを実装する必要があります。

要求：POST {BaseUrl}/validate

{
    "upn": "user@contoso.com",
    "employeeId": "E001",
    "claims": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-01-15"
    }
}

応答 (パス):

{
    "result": "pass"
}

応答 (失敗):

{
    "result": "fail",
    "failedClaims": ["dateOfBirth"]
}

Troubleshoot

症状	原因	Resolution
関数が返す `401`	ベアラートークンの検証に失敗したか、ID プロバイダーが構成されていません。	Function App Authentication (手順 5) で ID プロバイダーが追加され、クライアント ID がアプリの登録と一致するかどうかを確認します。
関数は `200` を返しますが、復旧フローは失敗します	応答スキーマの不一致。	関数が応答で正しい `@odata.type` 値を返すかどうかを確認します。
要求は常に検証に失敗する	データソースが一致しません。	Excel列ヘッダーまたは HR API 応答が要求キーと正確に一致するかどうかを確認します (大文字と小文字は区別されません)。
復旧中に呼び出されない関数	イベントリスナーが構成されていません。	カスタム認証拡張機能がアカウント回復ポリシーに割り当てられているかどうかを確認します (手順 3)。
Excelでデータが読み込まれない	共有 URL が無効または期限切れです。	Excel ファイルを再共有し、環境変数で `Excel__ShareUrl` を更新します。
管理者の同意が付与されていません	拡張機能呼び出しのアクセス許可エラー。	カスタム認証拡張機能 >Overview>アクセス権を付与>承認に移動します。

トラブルシューティングのガイダンスの詳細については、「カスタム認証拡張機能 API のトラブルシューティング」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-08

アカウント回復要求の検証用のカスタム認証拡張機能を作成する

前提条件

どのように機能するのか

手順 1: カスタム認証拡張機能 REST API を作成する (Azure関数アプリ)

1.1 Azure関数をデプロイする

1.2 関数の URL を取得する

1.3 テスト データ ソースを構成する

手順 2: カスタム認証拡張機能を作成して登録する

2.1 管理者の同意を付与する

手順 3: カスタム認証拡張機能をアカウント回復ポリシーに追加する

手順 4: 関数をテストする (認証を追加する前に)

4.1 関数を直接テストする

手順 5: Azure関数を保護する

5.1 Azure関数に ID プロバイダーを追加する

5.2 OpenID Connect ID プロバイダーを使用する

手順 6: エンドツーエンドの復旧フローをテストする

運用環境に切り替える: HR API プロバイダーを使用する

Troubleshoot

関連するコンテンツ

フィードバック

その他のリソース

1.3 テストデータソースを構成する