Устраните неполадки с вашим пользовательским расширением проверки подлинности

Статья
03/06/2025

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

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

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

Для приложений OpenId Connect — Microsoft Entra ID перенаправляет пользователя обратно в клиентское приложение с ошибкой. Токен не выпущен.
Для приложений SAML идентификатор Microsoft Entra показывает пользователю экран ошибки в процессе аутентификации. Пользователь не перенаправляется обратно в клиентское приложение.

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

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

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

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

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

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

Войдите в Центр администрирования Microsoft Entra в роли Администратора облачных приложений или выше.
Перейдите к Identity>Applications>Enterprise applications.
Выберите журналы входа и выберите последний журнал входа.
Дополнительные сведения см. на вкладке "События проверки подлинности". Отображаются сведения, связанные с вызовом REST API пользовательского расширения проверки подлинности, включая коды ошибок.

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

Используйте следующую таблицу для диагностики кода ошибки.

Код ошибки	Название ошибки	Описание
1003000	НеожиданнаяОшибкаОбработчикаСобытий	При обработке обработчика событий произошла непредвиденная ошибка.
1003001	Неожиданная ошибка пользовательского расширения	При вызове пользовательского API расширения произошла непредвиденная ошибка.
1003002	Неверный HTTP-статус пользовательского расширения	API пользовательского расширения вернул недопустимый код состояния HTTP. Убедитесь, что API возвращает принятый код состояния, определенный для этого пользовательского типа расширения.
1003003	Неверное тело ответа пользовательского расширения	Возникла проблема с анализом текста ответа настраиваемого расширения. Убедитесь, что текст ответа API находится в приемлемой схеме для этого пользовательского типа расширения.
1003004	CustomExtensionThrottlingError	Слишком много запросов на пользовательское расширение. Это исключение возникает для вызовов API пользовательских расширений при достижении ограничений регулирования.
1003005	Пользовательское расширение: время ожидания истекло	Пользовательское расширение не ответило в течение допустимого времени ожидания. Убедитесь, что API отвечает в течение настроенного времени ожидания для настраиваемого расширения. Он также может означать, что токен доступа недействителен. Выполните действия, чтобы напрямую вызвать REST API.
1003006	НедопустимыйТипКонтентаОтветаПользовательскогоРасширения	Тип содержимого ответа пользовательского расширения не "application/json".
1003007	CustomExtensionNullClaimsResponse	API пользовательского расширения ответил с помощью пакета утверждений NULL.
1003008	CustomExtensionInvalidResponseApiSchemaVersion	API пользовательского расширения не ответил на тот же apiSchemaVersion, для который он был вызван.
1003009	CustomExtensionEmptyResponse	Тело ответа API пользовательского расширения было нулевым, что не было ожидаемым.
1003010	НедопустимоеКоличествоДействийПользовательскогоРасширения	Ответ API пользовательского расширения включал несколько действий, отличных от тех, которые поддерживаются для этого пользовательского типа расширения.
1003011	Пользовательское расширение не найдено	Не удалось найти пользовательское расширение, связанное с прослушивателем событий.
1003012	НеверныйТипДействияДополненияПользователя	Пользовательское расширение вернуло недопустимый тип действия, определенный для этого типа пользовательского расширения.
1003014	Ошибка формата идентификатора ресурса CustomExtension	Свойство identifierUris в манифесте регистрации приложения для пользовательского расширения должно быть в формате "api://{полное доменное имя}/{appid}.
1003015	НазваниеДоменaПользовательскогоРасширенияНеСовпадает	targetUrl и resourceId пользовательского расширения должны иметь одинаковое полное доменное имя.
1003016	Основной объект службы CustomExtensionResource не найден	Идентификатор приложения (appId) ресурса пользовательского расширения (resourceId) должен соответствовать реальной учётной записи службы в клиенте (tenant).
1003017	Служебный объект клиента пользовательского расширения не найден	Основной объект службы для пользовательского расширения ресурсов не найден в арендаторе.
1003018	СлужбаКлиентаПользовательскогоРасширенияОтключена	Главный объект службы ресурса пользовательского расширения отключен в этом клиенте.
1003019	CustomExtensionResourceСервисПринципалОтключен	Субъект-служба ресурсов пользовательского расширения отключена в этом клиенте.
1003020	Неверный формат целевого URL-адреса в пользовательском расширении	Целевой URL-адрес находится в неправильном формате. Он должен быть допустимым URL-адресом, начинающимся с https.
1003021	Разрешение на пользовательское расширение не предоставлено для объекта службы	Субъект-служба не имеет согласия администратора для роли приложения CustomAuthenticationExtensions.Receive.Payload (также известного как разрешение на приложение), которое требуется для получения http-запросов пользовательского расширения проверки подлинности.
1003022	Пользовательское расширение или основной объект службы MS Graph отключен или не найден	Субъект-служба MS Graph отключен или не найден в этом клиенте.
1003023	Пользовательское расширение заблокировано	Конечная точка, используемая для настраиваемого расширения, блокируется службой.
1003024	РазмерНастраиваемогоРасширенияПревышен	Размер ответа на пользовательское расширение превысил максимальный предел.
1003025	Превышен размер утверждений пользовательского расширения	Общий размер утверждений в ответе пользовательского расширения превысил максимальное ограничение.
1003026	СпециальнаяРасширениеПустойИлиОтсутствующийКлючДляТребованияНеПоддерживается	API пользовательского расширения ответил утверждениями с NULL-значением или пустым ключом.
1003027	Ошибка соединения с настраиваемым расширением	Ошибка при подключении к пользовательскому 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 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, выберите "Авторизация", а затем выберите маркер носителя, а затем вставьте маркер доступа, полученный от идентификатора 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 как минимум Администратор облачных приложений.
Перейдите в раздел Идентификация>Приложения>Регистрация приложений.
Выберите регистрацию приложения 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, используйте план хостинга, который поддерживает API в непрерывной готовности. Для Функции Azure это может быть план "Премиум" или "Выделенный".
Запустите автоматические тесты интеграции для проверки подлинности. Вы также можете использовать средства тестирования API для тестирования производительности API.

См. также

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

Поделиться через

Устраните неполадки с вашим пользовательским расширением проверки подлинности

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

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

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

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

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

См. также

Обратная связь

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

Поделиться через

Устраните неполадки с вашим пользовательским расширением проверки подлинности

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

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

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

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

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

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

См. также

Обратная связь

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