カスタムクレームプロバイダー API のトラブルシューティング

[アーティクル]
04/10/2024

認証イベントとカスタムクレームプロバイダーを使用すると、外部システムと統合することで、Microsoft Entra 認証エクスペリエンスをカスタマイズできます。たとえば、カスタムクレームプロバイダー API を作成し、外部ストアからクレームを含むトークンを受信するように OpenID Connect アプリまたは SAML アプリを構成できます。

エラー動作

API 呼び出しが失敗すると、エラーの動作は次のようになります。

OpenId Connect アプリの場合 - Microsoft Entra ID は、ユーザーをエラーとともにクライアントアプリケーションにリダイレクトします。トークンは作成されません。
SAML アプリの場合 - Microsoft Entra ID は、認証エクスペリエンスでユーザーにエラー画面を表示します。ユーザーはクライアントアプリケーションにリダイレクトされません。

アプリケーションまたはユーザーに送り返されるエラーコードは汎用的です。トラブルシューティングを行うには、サインインログでエラーコードを確認します。

ログ記録

カスタムクレームプロバイダー REST API エンドポイントに関する問題をトラブルシューティングするには、REST API でログ記録を処理する必要があります。 Azure Functions やその他の API 開発プラットフォームには、詳細なログ記録ソリューションが用意されています。それらのソリューションを使用して、API の動作に関する詳細情報を取得し、API ロジックのトラブルシューティングを行います。

ヒント

この記事の手順は、開始するポータルに応じて若干異なる場合があります。

REST API ログに加えて、Microsoft Entra サインインログやホスティング環境診断ソリューションも使用できます。 Microsoft Entra サインインログを使用すると、ユーザーのサインインに影響する可能性があるエラーを見つけることができます。Microsoft Entra サインインログには、API が Microsoft Entra ID によって呼び出されたときに発生した HTTP 状態、エラーコード、実行時間、再試行回数に関する情報が表示されます。

Microsoft Entra サインインログも Azure Monitor と統合されます。アラートと監視を設定し、データを視覚化し、セキュリティ情報イベント管理 (SIEM) ツールと統合できます。たとえば、エラーの数が選択した特定のしきい値を超えた場合の通知を設定できます。

Microsoft Entraサインインログにアクセスするには:

少なくともクラウドアプリケーション管理者として Microsoft Entra 管理センターにサインインします。
ID>アプリケーション>エンタープライズアプリケーション を参照します。
サインインログ を選択し、最新のサインインログを選択します。
詳細については、[認証イベント] タブを選択します。カスタム拡張機能 REST API 呼び出しに関連する情報が、エラーコードを含めて表示されます。

エラーコードのリファレンス

次の表を使用して、エラーコードを診断します。

エラーコード	エラー名	Description
1003000	EventHandlerUnexpectedError	イベントハンドラーの処理時に予期しないエラーが発生しました。
1003001	CustomExtenstionUnexpectedError	カスタム拡張機能 API の呼び出し中に予期しないエラーが発生しました。
1003002	CustomExtensionInvalidHTTPStatus	カスタム拡張 API から無効な HTTP 状態コードが返されました。 API から、そのカスタム拡張機能の種類に対して定義されている「受理されました」ステータスコードが返されることを確認します。
1003003	CustomExtensionInvalidResponseBody	カスタム拡張機能の応答本文の解析で問題が発生しました。 API 応答本文のスキーマが、そのカスタム拡張機能の種類に対して受け入れ可能であることを確認します。
1003004	CustomExtensionThrottlingError	カスタム拡張機能の要求が多すぎます。この例外は、スロットリングの制限に達したときにカスタム拡張 API 呼び出しに対してスローされます。
1003005	CustomExtensionTimedOut	カスタム拡張機能が、許可されたタイムアウト内に応答しませんでした。カスタム拡張機能の構成済みタイムアウト内に API が応答していることを確認します。アクセストークンが無効であることを示している可能性もあります。 REST API を直接呼び出す手順に従います。
1003006	CustomExtensionInvalidResponseContentType	カスタム拡張機能の応答コンテンツタイプが 'application/json' ではありません。
1003007	CustomExtensionNullClaimsResponse	カスタム拡張 API が null の要求バッグで応答しました。
1003008	CustomExtensionInvalidResponseApiSchemaVersion	カスタム拡張 API が、呼び出されたのと同じ apiSchemaVersion で応答しませんでした。
1003009	CustomExtensionEmptyResponse	カスタム拡張 API の応答本文が予期していない null でした。
1003010	CustomExtensionInvalidNumberOfActions	カスタム拡張 API 応答に、そのカスタム拡張機能の種類でサポートされているものとは異なる数のアクションが含まれていました。
1003011	CustomExtensionNotFound	イベントリスナーに関連付けられているカスタム拡張機能が見つかりませんでした。
1003012	CustomExtensionInvalidActionType	カスタム拡張機能が、そのカスタム拡張機能の種類に対して定義されている無効なアクションの種類を返しました。
1003014	CustomExtensionIncorrectResourceIdFormat	カスタム拡張機能のアプリケーション登録のマニフェストの "identifierUris" プロパティは、"api://{ully qualified domain name}/{appid} の形式にする必要があります。
1003015	CustomExtensionDomainNameDoesNotMatch	カスタム拡張機能の targetUrl と resourceId には、同じ完全修飾ドメイン名が必要です。
1003016	CustomExtensionResourceServicePrincipalNotFound	カスタム拡張機能の resourceId の appId は、テナント内の実際のサービスプリンシパルに対応している必要があります。
1003017	CustomExtensionClientServicePrincipalNotFound	カスタム拡張機能のリソースサービスプリンシパルがテナントに見つかりません。
1003018	CustomExtensionClientServiceDisabled	カスタム拡張機能のリソースサービスプリンシパルがテナントで無効になっています。
1003019	CustomExtensionResourceServicePrincipalDisabled	カスタム拡張機能のリソースサービスプリンシパルがテナントで無効になっています。
1003020	CustomExtensionIncorrectTargetUrlFormat	ターゲット URL の形式が正しくありません。 https で始まる有効な URL である必要があります。
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	サービスプリンシパルには、Microsoft Graph の CustomAuthenticationExtensions.Receive.Payload アプリロール (アプリケーションのアクセス許可とも呼ばれます) に関する管理者の同意がありません。これは、アプリがカスタム認証拡張機能の HTTP 要求を受信するために必須です。
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	MS Graph サービスプリンシパルが無効になっているか、このテナントで見つかりません。
1003023	CustomExtensionBlocked	カスタム拡張機能に使用されるエンドポイントは、サービスによってブロックされています。
1003024	CustomExtensionResponseSizeExceeded	カスタム拡張機能の応答サイズが上限を超えました。
1003025	CustomExtensionResponseClaimsSizeExceeded	カスタム拡張機能応答の要求の合計サイズが上限を超えました。
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	カスタム拡張 API が、null または空のキーを含む要求で応答しました。
1003027	CustomExtensionConnectionError	カスタム拡張 API への接続中にエラーが発生しました。

REST API を直接呼び出してください

REST API は Microsoft Entra アクセストークンによって保護されています。次の方法で API をテストできます:

カスタム認証拡張機能に関連付けられているアプリケーション登録でアクセストークンを取得する
API テストツールを使用して API をローカルでテストします。

アクセストークンを取得する
API テストツール

アクセストークンを取得したら、それを HTTP Authorization ヘッダーを渡します。アクセストークンを取得するには、次の手順に従います。

少なくともクラウドアプリケーション管理者として Microsoft Entra 管理センターにサインインします。
[ID]>[アプリケーション]>[Application registrations] (アプリケーションの登録) を参照します。
トークン発行イベント用にカスタムクレームプロバイダーを構成するで以前に構成した、Azure Functions 認証イベント API アプリの登録を選択します。
アプリケーション ID をコピーします。
アプリシークレットを作成していない場合は、次の手順に従います。
1. [証明書とシークレット]>[Client secrets]\(クライアントシークレット\)>[新しいクライアントシークレット] の順に選択します。
2. クライアントシークレットの説明を追加します。
3. シークレットの有効期限を選択するか、カスタムの有効期間を指定します。
4. [追加] を選択します。
5. クライアントアプリケーションのコードで使用できるように、シークレットの値を記録しておきます。このページからの移動後は、このシークレットの値は "二度と表示されません"。
メニューから [API の公開] を選択し、[アプリケーション ID の URI] の値をコピーします。たとえば、api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444 のようにします。
任意の API テストツールを開き、新しい HTTP クエリを作成します。
[HTTP メソッド] を POST に変更します。
次の URL を入力します。 {tenantID} をご使用のテナント ID に置き換えます。
```
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
```

[本文] で [フォームデータ] を選択し、次のキーを追加します。

キー	値
`grant_type`	`client_credentials`
`client_id`	アプリケーションのクライアント ID。
`client_secret`	アプリケーションのクライアントシークレット。
`scope`	アプリケーションの [アプリケーション ID の URI] を、次に `.default` を追加します。たとえば、`api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default` のように指定します。

HTTP クエリを実行し、access_token を https://jwt.ms Web アプリにコピーします。
iss を API で構成した発行者名と比較します。
aud を API で構成したクライアント ID と比較します。

任意の API テストツールを使用して API を直接テストするには、次の手順に従います。

Note

NuGet パッケージ Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents を使用した場合は、テスト目的でトークン検証をオフにします。 local.settings.json を開き、次のパラメーターを追加します

"AuthenticationEvents__BypassTokenValidation": true

テストが完了したら、必ず削除してください。

REST API で、appid または azp の要求の検証を無効にします。先ほど作成した関数 API を編集する方法を確認してください。
新しい HTTP 要求を作成し、HTTP メソッドを POST に設定します。
[本文] で [未加工] を選択し、[JSON] を選択します。

Microsoft Entra ID から REST API に送信される要求を模倣する次の JSON を貼り付けます。

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/<Your tenant GUID>/applications/<Your Test Application App Id>",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "<Your tenant GUID>",
        "authenticationEventListenerId": "<GUID>",
        "customAuthenticationExtensionId": "<Your custom authentication extension ID>",
        "authenticationContext": {
            "correlationId": "<Enter correlation ID here>",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "<Your Test Applications servicePrincipal objectId>",
                "appId": "<Your Test Application App Id>",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2023-08-16T00:00:00Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "90847c2a-e29d-4d2f-9f54-c5b4d3f26471", // Client ID representing the Microsoft Entra authentication events service
                "mail": "casey@contoso.com",
                "onPremisesSamAccountName": "Casey Jensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "casey@contoso.com",
                "userType": "Member"
            }
        }
    }
}

ヒント

Microsoft Entra ID から取得したアクセストークンを使用している場合は、[認可] を選択し、[ベアラートークン]を選択し、Microsoft Entra ID から受け取ったアクセストークンを貼り付けます。

[送信] を選択すると、次のような JSON 応答が表示されます。

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }

        ]
    }
}

一般的なパフォーマンスの大幅な向上

最も一般的な問題の 1 つは、カスタムクレームプロバイダー API が 2 秒以内に応答しないでタイムアウトになることです。 REST API が後続の再試行で応答しない場合、認証は失敗します。 REST API のパフォーマンスを向上させるには、以下の推奨事項に従います。

API がダウンストリーム API にアクセスする場合は、すべての実行で新しいトークンを取得する必要はなくなるように、これらの API の呼び出しに使用されるアクセストークンをキャッシュします。
パフォーマンスの問題は、多くの場合、ダウンストリームサービスに関連しています。ログ記録を追加します。これにより、ダウンストリームサービスへの呼び出しの処理時間が記録されます。
クラウドプロバイダーを使用して API をホストしている場合は、API を常に "ウォーム" に保つホスティングプランを使用します。 Azure Functions の場合、これは Premium プランまたは専用プランです。
認証の自動統合テストを実行します。 API テストツールを使用して、API のパフォーマンスのみをテストすることもできます。

カスタムクレームプロバイダー API のトラブルシューティング

エラー動作

ログ記録

エラーコードのリファレンス

REST API を直接呼び出してください

一般的なパフォーマンスの大幅な向上

関連項目

その他のリソース

カスタム クレーム プロバイダー API のトラブルシューティング

エラー動作

ログ記録

Microsoft Entra サインイン ログ

エラー コードのリファレンス

REST API を直接呼び出してください

一般的なパフォーマンスの大幅な向上

関連項目

その他のリソース

カスタムクレームプロバイダー API のトラブルシューティング

Microsoft Entra サインインログ

エラーコードのリファレンス