對自訂宣告提供者 API 進行疑難排解

發行項
06/24/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 登入記錄提供下列相關資訊：HTTP 狀態、錯誤碼、執行持續時間，以及 Microsoft Entra ID 呼叫 API 的重試次數。

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

若要存取 Microsoft Entra 登入記錄：

以至少雲端應用程式系統管理員的身分登入 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	CustomExtensionConnectionError	連線至自訂延伸模組 API 時發生錯誤。

直接呼叫 REST API

您的 REST API 受到 Microsoft Entra 存取權杖的保護。您可以用下列方式測試 API;

透過與自訂驗證延伸模組相關聯的應用程式註冊取得存取權杖
使用 API 測試工具在本機測試 API。

API 測試工具
取得存取權杖

基於本機開發和測試目的，開啟 local.settings.json，並將程式碼取代為下列 JSON：
```
{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsSecretStorageType": "files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation" : false
  }
}
```
注意

如果您使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 套件，請務必設定 "AuthenticationEvents__BypassTokenValidation" : true 以供本機測試之用。
使用您慣用的 API 測試工具建立新的 HTTP 要求，並將 HTTP 方法設定為 POST。

使用下列 JSON 本文，模擬 Microsoft Entra ID 傳送至 REST API 的要求。

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
        "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
        "authenticationContext": {
            "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2023-08-16T00:00:00Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                "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" 
                    ]
                }
            }

        ]
    }
}

在您取得存取權杖後，將其傳遞至 HTTP Authorization 標頭。若要取得存取權杖，請遵循下列步驟：

以至少雲端應用程式系統管理員的身分登入 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
```

在 [本文] 底下選取 [form-data]，並新增下列索引鍵：

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

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

一般效能提升

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

如果您的 API 存取了任何下游 API，請快取用來呼叫這些 API 的存取權杖，如此即無須在每次執行時取得新權杖。
效能問題往往與下游服務有關。新增記錄，並在其中記錄呼叫任何下游服務的處理時間。
如果您使用雲端提供者來裝載 API，請使用讓 API 持續保持活動狀態的主控方案。對於 Azure Functions，這可以是進階方案或專用方案。
為您的驗證執行自動化整合測試。您也可以使用 API 測試工具，僅就 API 效能進行測試。

共用方式為

對自訂宣告提供者 API 進行疑難排解

錯誤行為

記錄

錯誤碼參考

直接呼叫 REST API

一般效能提升

另請參閱

意見反應

其他資源