針對自定義宣告提供者 API 進行疑難解答

發行項
04/10/2024

驗證事件和自定義宣告提供者可讓您藉由與外部系統整合來自定義 Microsoft Entra 驗證體驗。例如，您可以建立自定義宣告提供者 API，並設定 OpenID 連線應用程式或 SAML 應用程式，以接收來自外部存放區的宣告令牌。

錯誤行為

當 API 呼叫失敗時，錯誤行為如下所示：

針對 OpenId 連線應用程式 - Microsoft Entra ID 會將使用者重新導向回用戶端應用程式，併發生錯誤。令牌不會縮排。
針對 SAML 應用程式 - Microsoft Entra ID 會在驗證體驗中向使用者顯示錯誤畫面。使用者不會重新導向回用戶端應用程式。

傳回給應用程式或使用者的錯誤碼是一般。若要進行疑難解答，請檢查登入記錄中是否有錯誤碼。

記錄

若要針對自定義宣告提供者 REST API 端點的問題進行疑難解答，REST API 必須處理記錄。 Azure Functions 和其他 API 開發平臺提供深入的記錄解決方案。使用這些解決方案來取得 API 行為的詳細資訊，並針對 API 邏輯進行疑難解答。

提示

本文中的步驟可能會根據您從開始的入口網站稍有不同。

除了 REST API 記錄，以及裝載環境診斷解決方案之外，您也可以使用 Microsoft Entra 登入記錄。使用 Microsoft Entra 登入記錄，您可以找到可能會影響使用者登入的錯誤。Microsoft Entra 登入記錄提供有關 MICROSOFT Entra ID 呼叫 API 的 HTTP 狀態、錯誤碼、執行持續時間和重試次數的相關信息。

Microsoft Entra 登入記錄也會與 Azure 監視器整合。您可以設定警示和監視、將數據可視化，並與安全性資訊和事件管理（SIEM）工具整合。例如，如果錯誤數目超過您選擇的特定閾值，您可以設定通知。

若要存取 Microsoft Entra 登入記錄：

以至少雲端應用程式管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式企業應用程式]。>
選取 [登入記錄]，然後選取最新的登入記錄。
如需詳細資訊，請選取 [驗證事件 ] 索引標籤。顯示與自定義驗證延伸模組 REST API 呼叫相關的資訊，包括任何錯誤碼。

錯誤碼參考

使用下表來診斷錯誤碼。

錯誤碼	錯誤名稱	描述
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://{完整功能變數名稱}/{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	CustomExtension 連線 ionError	線上到自定義擴充功能 API 時發生錯誤。

直接呼叫 REST API

您的 REST API 受到 Microsoft Entra 存取令牌的保護。您可以藉由測試 API;

使用與自定義驗證延伸模組相關聯的應用程式註冊取得存取令牌
使用 API 測試工具在本機測試 API。

取得存取令牌
API 測試工具

取得存取令牌之後，請將 HTTP Authorization 標頭傳遞。若要取得存取令牌，請遵循下列步驟：

以至少雲端應用程式管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式應用程式>註冊]。
選取先前在設定令牌發行事件的自定義宣告提供者中設定的 Azure Functions 驗證事件 API 應用程式註冊。
複製應用程式識別碼。
如果您尚未建立應用程式秘密，請遵循下列步驟：
1. 選取 [憑證與秘密>] [客戶端密碼>] [新增客戶端密碼]。
2. 新增用戶端祕密的描述。
3. 選取祕密的到期日，或指定自訂存留期。
4. 選取 [新增]。
5. 記錄秘密的值，以用於用戶端應用程式程式碼。離開此頁面後，就「不會再次顯示」此祕密值。
從功能表中，選取 [公開 API]，並複製應用程式識別碼 URI 的值。例如： api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444 。
開啟您慣用的 API 測試工具，並建立新的 HTTP 查詢。
將 HTTP 方法 變更為 POST。
輸入下列 URL。 {tenantID}將取代為您的租用戶標識碼。
```
https://login.microsoftonline.com/{tenantID}/oauth2/v2.0/token
```

在 [ 本文] 底下，選取 窗體數據 並新增下列索引鍵：

機碼	值
`grant_type`	`client_credentials`
`client_id`	應用程式的用戶端識別碼。
`client_secret`	應用程式的客戶端密碼。
`scope`	應用程式的應用程式識別碼 URI，然後新增 `.default`。例如，`api://contoso.azurewebsites.net/00001111-aaaa-2222-bbbb-3333cccc4444/.default`

執行 HTTP 查詢，並將複製到 access_tokenhttps://jwt.ms Web 應用程式。
iss將與您在 API 中設定的簽發者名稱進行比較。
aud將與您在 API 中設定的用戶端識別碼進行比較。

若要使用慣用的 API 測試工具直接測試 API，請遵循下列步驟：

注意

如果您使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 套件，請關閉令牌驗證以供測試之用。開啟 local.settings.json 並新增下列參數

"AuthenticationEvents__BypassTokenValidation": true

完成測試之後，請確定將其移除。

在您的 REST API 中，停用 appid 或 azp宣告驗證。瞭解如何編輯您稍早建立的函式 API 。
建立新的 HTTP 要求，並將 HTTP 方法設定為 POST。
在 [本文] 中，選取 [原始]，然後選取 [JSON]。

貼上下列 JSON，以模擬 Microsoft Entra ID 傳送至 REST API 的要求。

{
    "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" 
                    ]
                }
            }

        ]
    }
}

一般效能改善

其中一個最常見的問題是，您的自定義宣告提供者 API 不會在兩秒的逾時內回應。如果您的 REST API 未在後續重試中回應，則驗證會失敗。若要改善 REST API 的效能，請遵循下列建議：

如果您的 API 存取任何下游 API，請快取用來呼叫這些 API 的存取令牌，因此不需要在每次執行時取得新的令牌。
效能問題通常與下游服務相關。新增記錄，記錄呼叫任何下游服務的程序時間。
如果您使用雲端提供者來裝載 API，請使用讓 API 保持「暖」的裝載方案。針對 Azure Functions，它可以是進階版方案或專用方案。
執行驗證的自動化整合測試。您也可以使用 API 測試工具來只測試 API 效能。

針對自定義宣告提供者 API 進行疑難解答

錯誤行為

記錄

錯誤碼參考

直接呼叫 REST API

一般效能改善

另請參閱

其他資源