Устранение неполадок с API поставщика пользовательских утверждений

Статья
04/13/2024

События проверки подлинности и пользовательские поставщики утверждений позволяют настроить интерфейс проверки подлинности Microsoft Entra, интегрируя с внешними системами. Например, можно создать API пользовательского поставщика утверждений и настроить приложение OpenID Подключение или приложение SAML для получения маркеров с утверждениями из внешнего хранилища.

Действия при ошибке

При сбое вызова API поведение ошибки выглядит следующим образом:

Для приложений OpenId Подключение — идентификатор Microsoft Entra перенаправляет пользователя обратно в клиентское приложение с ошибкой. Маркер не помят.
Для приложений SAML — идентификатор Microsoft Entra отображает экран ошибки пользователя в интерфейсе проверки подлинности. Пользователь не перенаправляется обратно в клиентское приложение.

Код ошибки, отправляемый приложению или пользователю, является универсальным. Чтобы устранить неполадки, проверка журналы входа для кодов ошибок.

Ведение журнала

Чтобы устранить неполадки с конечной точкой REST API пользовательского поставщика утверждений, REST API должен обрабатывать ведение журнала. Функции Azure и другие платформы разработки API предоставляют подробные решения для ведения журнала. Используйте эти решения для получения подробных сведений о поведении API и устранении неполадок логики API.

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

Кроме того, вы можете использовать журналы входа Microsoft Entra в дополнение к журналам REST API и среда размещения диагностика решениям. С помощью журналов входа в Microsoft Entra можно найти ошибки, которые могут повлиять на вход пользователей. Журналы входа Microsoft Entra содержат сведения о состоянии HTTP, коде ошибки, длительности выполнения и количестве повторных попыток, которые произошли с помощью идентификатора Microsoft Entra.

Журналы входа Microsoft Entra также интегрируются с Azure Monitor. Вы можете настроить оповещения и мониторинг, визуализировать данные и интегрировать с средствами управления сведениями о безопасности и событиями (SIEM). Например, можно настроить уведомления, если количество ошибок превышает определенное пороговое значение.

Чтобы получить доступ к журналам входа Microsoft Entra, выполните следующие действия.

Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.
Перейдите к приложениям Identity>Applications>Enterprise.
Выберите журналы входа и выберите последний журнал входа.
Дополнительные сведения см. на вкладке "События проверки подлинности". Отображаются сведения, связанные с вызовом 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://{полное доменное имя}/{appid}.
1003015	CustomExtensionDomainNameDoesNotMatch	TargetUrl и resourceId пользовательского расширения должны иметь то же полное доменное имя.
1003016	CustomExtensionResourceServicePrincipalNotFound	Идентификатор приложения пользовательского ресурса расширения должен соответствовать реальному субъекту-службе в клиенте.
1003017	CustomExtensionClientServicePrincipalNotFound	Субъект-служба ресурсов пользовательского расширения не найдена в клиенте.
1003018	CustomExtensionClientServiceDisabled	Субъект-служба ресурсов пользовательского расширения отключена в этом клиенте.
1003019	CustomExtensionResourceServicePrincipalDisabled	Субъект-служба ресурсов пользовательского расширения отключена в этом клиенте.
1003020	CustomExtensionIncorrectTargetUrlFormat	Целевой URL-адрес находится в неправильном формате. Он должен быть допустимым URL-адресом, начинающимся с https.
1003021	CustomExtensionPermissionNotGrantedToServicePrincipal	Субъект-служба не имеет согласия администратора для роли приложения CustomAuthenticationExtensions.Receive.Payload (также известного как разрешение на приложение), которое требуется для получения http-запросов пользовательского расширения проверки подлинности.
1003022	CustomExtensionMsGraphServicePrincipalDisabledOrNotFound	Субъект-служба MS Graph отключен или не найден в этом клиенте.
1003023	CustomExtensionBlocked	Конечная точка, используемая для настраиваемого расширения, блокируется службой.
1003024	CustomExtensionResponseSizeExceeded	Размер пользовательского ответа расширения превысил максимальное ограничение.
1003025	CustomExtensionResponseClaimsSizeExceed	Общий размер утверждений в ответе пользовательского расширения превысил максимальное ограничение.
1003026	CustomExtensionNullOrEmptyClaimKeyNotSupported	API пользовательского расширения ответил с утверждениями, содержащими значение NULL или пустой ключ'
1003027	CustomExtension Подключение ionError	Ошибка при подключении к пользовательскому 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
  }
}
```
Примечание.

Если вы использовали пакет NuGet Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents , обязательно установите "AuthenticationEvents__BypassTokenValidation" : true для локальных целей тестирования.
Используя предпочитаемое средство тестирования API, создайте новый HTTP-запрос и задайте для метода HTTP значение POST.

Используйте следующий текст JSON, который имитирует запрос идентификатора Microsoft Entra, отправляется в 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, выберите "Авторизация", а затем выберите маркер носителя, а затем вставьте маркер доступа, полученный от идентификатора Microsoft Entra.

Выберите "Отправить", и вы должны получить ответ JSON, аналогичный следующему:

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

        ]
    }
}

После получения маркера доступа передайте его заголовок HTTP Authorization . Чтобы получить маркер доступа, выполните следующие действия.

Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.
Перейдите к регистрации приложений>удостоверений>.
Выберите регистрацию приложения API событий проверки подлинности Функции Azure, настроенную ранее в настройке пользовательского поставщика утверждений для события выдачи маркера.
Скопируйте идентификатор приложения.
Если вы не создали секрет приложения, выполните следующие действия.
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_token в https://jwt.ms веб-приложение.
iss Сравните имя издателя, настроенного в API.
Сравните идентификатор клиента, настроенный aud в API.

Распространенные улучшения производительности

Одним из наиболее распространенных проблем является то, что API пользовательского поставщика утверждений не отвечает в течение двух секунд времени ожидания. Если REST API не отвечает на последующие повторные попытки, проверка подлинности завершается ошибкой. Чтобы повысить производительность REST API, следуйте приведенным ниже рекомендациям.

Если API обращается к любым нижестоящим API, кэшируйте маркер доступа, используемый для вызова этих API, поэтому новый маркер не должен быть получен при каждом выполнении.
Проблемы с производительностью часто связаны с подчиненными службами. Добавьте ведение журнала, которое записывает время процесса для вызова любых подчиненных служб.
Если вы используете поставщик облачных служб для размещения API, используйте план размещения, который всегда "теплый". Для Функции Azure это может быть план "Премиум" или "Выделенный".
Запустите автоматические тесты интеграции для проверки подлинности. Вы также можете использовать средства тестирования API для тестирования производительности API.

См. также

Создание REST API с событием запуска выдачи маркеров
Настройка приложения SAML для получения маркеров с утверждениями из внешнего хранилища
Справочная статья о поставщике пользовательских утверждений.

Share via

Устранение неполадок с API поставщика пользовательских утверждений

Действия при ошибке

Ведение журнала

Справочник по кодам ошибок

Вызов REST API напрямую

Распространенные улучшения производительности

См. также

Дополнительные ресурсы

Share via

Устранение неполадок с API поставщика пользовательских утверждений

Действия при ошибке

Ведение журнала

Журналы входов Microsoft Entra

Справочник по кодам ошибок

Вызов REST API напрямую

Распространенные улучшения производительности

См. также

Дополнительные ресурсы