Справочник по API собственной проверки подлинности
Область применения: 
клиенты рабочей силы внешние
клиенты (дополнительные сведения)
Собственная проверка подлинности Microsoft Entra позволяет размещать пользовательский интерфейс приложения в клиентском приложении вместо делегирования проверки подлинности в браузерах, что приводит к встроенной интегрированной проверке подлинности. У разработчика есть полный контроль над внешним видом и интерфейсом входа.
В этой справочной статье API описаны сведения, необходимые только при выполнении потока вручную необработанным HTTP-запросам. Однако мы не рекомендуем этот подход. Поэтому, когда это возможно, используйте встроенный и поддерживаемый корпорацией Майкрософт пакет SDK для проверки подлинности. Дополнительные сведения об использовании пакета SDK см. в руководстве по подготовке мобильного приложения Android для собственной проверки подлинности и учебника. Подготовка мобильного приложения iOS и macOS для собственной проверки подлинности.
При успешном вызове конечных точек API вы получаете как маркер идентификатора для идентификации пользователя, так и маркер доступа для вызова защищенных API. Все ответы API находятся в формате JSON.
API собственной проверки подлинности Microsoft Entra поддерживает регистрацию и вход для двух методов проверки подлинности:
Электронная почта с паролем, которая поддерживает регистрацию и вход с помощью электронной почты и пароля, а также самостоятельного сброса пароля (SSPR).
Одноразовый секретный код электронной почты, который поддерживает регистрацию и вход с помощью одноразового секретного кода электронной почты.
Примечание.
В настоящее время конечные точки API собственной проверки подлинности не поддерживают общий доступ к ресурсам между источниками (CORS).
Необходимые компоненты
Внешний клиент Microsoft Entra. Если у вас еще нет одного, создайте внешний клиент.
Если вы еще этого не сделали, зарегистрируйте приложение в Центре администрирования Microsoft Entra. Убедитесь, что вы предоставляете делегированные разрешения и включаете общедоступный клиент и собственные потоки проверки подлинности.
Если вы еще этого не сделали, создайте поток пользователя в Центре администрирования Microsoft Entra. При создании потока пользователя обратите внимание на атрибуты пользователя, которые вы настраиваете по мере необходимости, так как эти атрибуты являются теми, которые Microsoft Entra ожидает отправки приложения.
Свяжите регистрацию приложения с потоком пользователя.
Для потока входа зарегистрируйте пользователя клиента, который используется для тестирования API входа. Кроме того, этот тестовый пользователь можно получить после запуска потока регистрации.
Для потока SSPR включите самостоятельный сброс пароля для пользователей клиента во внешнем клиенте. SSPR доступен для пользователей клиентов, использующих электронную почту с методом проверки подлинности паролем.
Метка продолжения
Каждый раз при вызове конечной точки в любом потоке, входе, регистрации или SSPR конечная точка включает маркер продолжения в ответ. Маркер продолжения — это уникальный идентификатор Microsoft Entra ID, который используется для поддержания состояния между вызовами разных конечных точек в одном потоке. Этот маркер необходимо включить в последующие запросы в том же потоке.
Каждый маркер продолжения действителен в течение определенного периода и может использоваться только для последующих запросов в одном потоке.
Справочник по API регистрации
Чтобы завершить поток регистрации пользователя для любого метода проверки подлинности, приложение взаимодействует с четырьмя конечными точками, , /signup/v1.0/startи /signup/v1.0/challenge/signup/v1.0/continue./token
Конечные точки API регистрации
| Конечная точка | Description |
|---|---|
/signup/v1.0/start |
Эта конечная точка запускает поток регистрации. Вы передаете действительный идентификатор приложения, новое имя пользователя и тип вызова, а затем возвращаете новый маркер продолжения. Конечная точка может вернуть ответ, указывающий приложению на использование потока веб-проверки подлинности, если выбранные методы проверки подлинности приложения не поддерживаются Microsoft Entra. |
/signup/v1.0/challenge |
Приложение вызывает эту конечную точку со списком типов проблем, поддерживаемых Microsoft Entra. Затем Microsoft Entra выбирает один из поддерживаемых методов проверки подлинности для пользователя для проверки подлинности. |
/signup/v1.0/continue |
Эта конечная точка помогает продолжить поток для создания учетной записи пользователя или прерывания потока из-за отсутствующих требований, таких как требования политики паролей или неправильные форматы атрибутов. Эта конечная точка создает маркер продолжения, а затем возвращает его в приложение. Конечная точка может вернуть ответ, указывающий приложению на использование потока проверки подлинности на основе веб-сайтов, если приложение не использует метод проверки подлинности, выбранный Microsoft Entra. |
/token |
Приложение вызывает эту конечную точку, чтобы, наконец, запросить маркеры безопасности. Приложение должно включить маркер продолжения, полученный из последнего успешного вызова конечной /signup/v1.0/continue точки. |
Типы проблем регистрации
API позволяет клиентскому приложению объявлять поддерживаемые методы проверки подлинности при вызове Microsoft Entra. Для этого приложение использует challenge_type параметр в запросе приложения. Этот параметр содержит предопределенные значения, представляющие различные методы проверки подлинности.
Дополнительные сведения о типах вызовов в собственных типах вызовов проверки подлинности. В этой статье описываются значения типов вызовов, которые следует учитывать для метода проверки подлинности.
Сведения о протоколе потока регистрации
Схема последовательности демонстрирует поток процесса регистрации.
На этой схеме указано, что приложение собирает имя пользователя (электронную почту), пароль (для электронной почты с методами проверки подлинности паролей) и атрибуты пользователя в разное время (и, возможно, на отдельных экранах). Однако вы можете создать приложение для сбора имени пользователя (электронной почты), пароля и всех необходимых и необязательных значений атрибутов на одном экране, а затем отправить все их через конечную точку /signup/v1.0/start . В этом случае приложению не нужно выполнять вызовы и обрабатывать ответы на необязательные действия.
Шаг 1. Запрос на запуск потока регистрации
Поток регистрации начинается с приложения, выполняющего запрос POST к /signup/v1.0/start конечной точке, чтобы запустить поток регистрации.
Ниже приведены примеры запроса(мы представляем пример запроса в нескольких строках для удобства чтения):
Пример 1:
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com
Пример 2 (включить атрибуты пользователя и пароль в запрос):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
username |
Да | Электронная почта пользователя клиента, с которым они хотят зарегистрироваться, например contoso-consumer@contoso.com. |
challenge_type |
Да | Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Ожидается, что значение будет отправлено oob redirect по электронной почте с oob password redirect помощью метода проверки подлинности паролей. |
password |
No | Значение пароля, которое приложение собирает от пользователя клиента. Пароль пользователя можно отправить через конечную /signup/v1.0/start точку или позже /signup/v1.0/continue . Замените {secure_password} значением пароля, которое приложение собирает от пользователя клиента. Вы несете ответственность за подтверждение того, что пользователь знает пароль, который он хочет использовать, предоставив поле подтверждения пароля в пользовательском интерфейсе приложения. Кроме того, необходимо убедиться, что пользователь знает о том, что представляет собой надежный пароль для политики вашей организации. Дополнительные сведения о политиках паролей Microsoft Entra. Этот параметр применим только для электронной почты с помощью метода проверки подлинности паролей. |
attributes |
No | Значения атрибутов пользователя, собираемые приложением от пользователя клиента. Это значение представляет собой строку, но отформатированную как объект JSON, ключевые значения которого являются программируемыми именами атрибутов пользователя. Эти атрибуты могут быть встроенными или настраиваемыми, а также обязательными или необязательными. Имена ключей объекта зависят от атрибутов, настроенных администратором в Центре администрирования Microsoft Entra. Вы можете отправить некоторые или все атрибуты пользователя через конечную точку /signup/v1.0/start или более позднюю версию в конечной точке /signup/v1.0/continue . Если вы отправляете все необходимые атрибуты через /signup/v1.0/start конечную точку, вам не нужно отправлять какие-либо атрибуты в конечной точке /signup/v1.0/continue . Однако при отправке некоторых обязательных атрибутов через /signup/v1.0/start конечную точку можно отправить оставшиеся необходимые атрибуты позже в конечной точке /signup/v1.0/continue . Замените {given_name}значения {postal_code} {user_age} имени, возраста и почтового кода соответственно, что приложение собирает от пользователя клиента. Microsoft Entra игнорирует все атрибуты, которые вы отправляете, которые не существуют. |
Ответ успешного выполнения
Ниже приведен пример успешного ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| Параметр | Описание |
|---|---|
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "user_already_exists",
"error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
1003037
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
invalid_attributes |
Список (массив объектов) атрибутов, которые не прошли проверку. Этот ответ возможен, если приложение отправляет атрибуты пользователя, а suberror значение параметра attribute_validation_failed. |
suberror |
Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например, если значение параметра challenge_type содержит неподдерживаемый метод проверки подлинности или запрос не включал client_id параметр, значение идентификатора клиента является пустым или недопустимым. error_description Используйте параметр, чтобы узнать о точной причине ошибки. |
invalid_client |
Идентификатор клиента, который приложение включает в запрос, предназначен для приложения, которое не имеет собственной конфигурации проверки подлинности, например не является общедоступным клиентом или не включено для собственной проверки подлинности. suberror Используйте параметр, чтобы узнать о точной причине ошибки. |
unauthorized_client |
Идентификатор клиента, используемый в запросе, имеет допустимый формат идентификатора клиента, но не существует во внешнем клиенте или является неверным. |
unsupported_challenge_type |
Значение challenge_type параметра не включает redirect тип вызова. |
user_already_exists |
Пользователь уже существует. |
invalid_grant |
Пароль, который приложение отправляет, не соответствует всем требованиям сложности, например пароль слишком коротким. suberror Используйте параметр, чтобы узнать о точной причине ошибки. Этот параметр применим только для электронной почты с помощью метода проверки подлинности паролей. |
Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_grant :
| Значение подсервера | Description |
|---|---|
password_too_weak |
Пароль слишком слаб, так как он не соответствует требованиям сложности. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
password_too_short |
Новый пароль меньше 8 символов. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
password_too_long |
Новый пароль превышает 256 символов. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
password_recently_used |
Новый пароль не должен совпадать с недавно использованным паролем. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
password_banned |
Новый пароль содержит слово, фразу или шаблон, который запрещен. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
password_is_invalid |
Пароль недопустим, например, так как он использует запрещенные символы. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
Если параметр ошибки имеет значение invalid_client, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_client :
| Значение подсервера | Description |
|---|---|
nativeauthapi_disabled |
Идентификатор клиента для приложения, которое не включается для собственной проверки подлинности. |
Примечание.
Если вы отправляете все необходимые атрибуты через /signup/v1.0/start конечную точку, но не все необязательные атрибуты, вы не сможете отправлять дополнительные необязательные атрибуты позже через конечную точку /signup/v1.0/continue . Microsoft Entra не явно запрашивает необязательные атрибуты, так как они не являются обязательными для завершения процесса регистрации. См. таблицу в разделе "Отправка атрибутов пользователя в конечные точки" , чтобы узнать атрибуты пользователя, которые можно отправить в /signup/v1.0/start конечные точки и /signup/v1.0/continue конечные точки.
Шаг 2. Выбор метода проверки подлинности
Приложение запрашивает Microsoft Entra, чтобы выбрать один из поддерживаемых типов проблем, с которыми пользователь может пройти проверку подлинности. Для этого приложение вызывает конечную точку /signup/v1.0/challenge . Приложение должно включить маркер продолжения, который он получает из конечной /signup/v1.0/start точки в запросе.
Ниже приведен пример запроса(мы представляем пример запроса в нескольких строках для удобочитаемости).
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
challenge_type |
No | Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Ожидается, что значение для oob redirect однократного секретного кода электронной почты и oob password redirect для электронной почты с помощью метода проверки подлинности паролей. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
Ответ успешного выполнения
Microsoft Entra отправляет одноразовый секретный код в адрес электронной почты пользователя, а затем отвечает с типом вызова со значением oob и дополнительными сведениями об однократном секретном коде:
HTTP/1.1 200 OK
Content-Type: application/json
{
"interval": 300,
"continuation_token": "AQABAAEAAAYn...",
"challenge_type": "oob",
"binding_method": "prompt",
"challenge_channel": "email",
"challenge_target_label": "c***r@co**o**o.com",
"code_length": 8
}
| Параметр | Описание |
|---|---|
interval |
Время в секундах приложение должно ждать, прежде чем пытаться повторно отправить OTP. |
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
challenge_type |
Тип вызова, выбранный для проверки подлинности пользователя. |
binding_method |
Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления пользователю дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob |
challenge_channel |
Тип канала, через который был отправлен одноразовый секретный код. На данный момент поддерживается только канал электронной почты. |
challenge_target_label |
Замаскированное сообщение электронной почты, в котором был отправлен одноразовый секретный код. |
code_length |
Длина однократного секретного кода, который создает Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например идентификатор клиента, пуст или недопустим. |
expired_token |
Срок действия маркера продолжения истек. |
unsupported_challenge_type |
Значение challenge_type параметра не включает redirect тип вызова. |
invalid_grant |
Недопустимый маркер продолжения. |
Шаг 3. Отправка однократного секретного кода
Приложение отправляет одноразовый секретный код, отправленный пользователю по электронной почте. Так как мы отправим одноразовый секретный код, oob требуется параметр, а grant_type параметр должен иметь значение oob.
Ниже приведен пример запроса(мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
grant_type |
Да | Запрос к конечной точке /signup/v1.0/continue можно использовать для отправки однократного секретного кода, пароля или атрибутов пользователя. В этом случае grant_type значение используется для различения этих трех вариантов использования. Возможные значения для grant_type : oob, password, attributes. В этом вызове, так как мы отправляем одноразовый секретный код, значение должно быть oob. |
oob |
Да | Одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Замените {otp_code} значения одноразового секретного кода, полученные пользователем в сообщении электронной почты. Чтобы повторно отправить одноразовый секретный код, приложение должно снова запросить /signup/v1.0/challenge конечную точку. |
После успешного отправки однократного секретного кода приложение поток регистрации зависит от сценариев, как показано в таблице:
| Сценарий | Как продолжить |
|---|---|
Приложение успешно отправляет пароль пользователя (для электронной почты с методом проверки подлинности паролей) через /signup/v1.0/start конечную точку, а атрибуты в Центре администрирования Microsoft Entra или все необходимые атрибуты пользователя отправляются через конечную точку /signup/v1.0/start . |
Microsoft Entra выдает маркер продолжения. Приложение может использовать маркер продолжения для запроса маркеров безопасности, как показано на шаге 5. |
Приложение успешно отправляет пароль пользователя (для электронной почты с методом проверки подлинности паролей), /signup/v1.0/startно не все необходимые атрибуты пользователя, Microsoft Entra указывает атрибуты, которые приложение должно отправить, как показано в обязательных атрибутах пользователя. |
Приложение должно отправлять необходимые атрибуты пользователя через конечную точку /signup/v1.0/continue . Ответ аналогичен одному из обязательных атрибутов пользователя. Отправьте атрибуты пользователя, показанные в отправке атрибутов пользователя. |
Приложение не отправляет пароль пользователя (для электронной почты с методом проверки подлинности паролей) через /signup/v1.0/start конечную точку. |
Ответ Microsoft Entra указывает, что необходимы учетные данные. См . ответ. Этот ответ возможен для электронной почты с помощью метода проверки подлинности паролей. |
Response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "credential_required",
"error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
"error_codes": [
55103
],
"timestamp": "yy-mm-dd 02:37:33Z",
"trace_id": "d6966055-...-80500",
"correlation_id": "3944-...-60d6",
"continuation_token": "AQABEQEAAAA..."
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
suberror |
Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
credential_required |
Для создания учетной записи требуется проверка подлинности, поэтому необходимо выполнить вызов к конечной /signup/v1.0/challenge точке, чтобы определить учетные данные, необходимые пользователю. |
invalid_request |
Сбой проверки параметров запроса, например проверка маркера продолжения или запрос не включал client_id параметр, значение идентификатора клиента является пустым или недопустимым, или внешний администратор клиента не включил сообщение OTP для всех пользователей клиента. |
invalid_grant |
Тип предоставления, включенный в запрос, не является допустимым или поддерживаемым, или значение OTP неверно. |
expired_token |
Срок действия маркера продолжения, включенного в запрос, истекает. |
Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_grant :
| Значение подсервера | Description |
|---|---|
invalid_oob_value |
Недопустимое значение однократного секретного кода. |
Для сбора учетных данных паролей от пользователя приложение должно вызвать /signup/v1.0/challenge конечную точку, чтобы определить учетные данные, необходимые пользователю.
Ниже приведен пример запроса(мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
challenge_type |
No | Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Для сообщения электронной почты с потоком регистрации паролей ожидается, что значение будет содержаться password redirect. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
Ответ успешного выполнения
Если пароль — это метод проверки подлинности, настроенный для пользователя в Центре администрирования Microsoft Entra, ответ успешного выполнения с маркером продолжения возвращается в приложение.
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "password",
"continuation_token": " AQABAAEAAAAty..."
}
| Параметр | Описание |
|---|---|
challenge_type |
пароль возвращается в ответе на необходимые учетные данные. |
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Шаг 4. Проверка подлинности и получение маркера для регистрации
Приложение должно отправить учетные данные пользователя, в данном случае пароль, запрошенный Microsoft Entra на предыдущем шаге. Приложение должно отправить учетные данные пароля, если это не делается через конечную точку /signup/v1.0/start . Приложение отправляет запрос к конечной точке /signup/v1.0/continue для отправки пароля. Так как мы отправим пароль, password требуется параметр, а grant_type параметр должен иметь пароль значения.
Ниже приведен пример запроса(мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra на предыдущем шаге. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
grant_type |
Да | Запрос к конечной точке /signup/v1.0/continue можно использовать для отправки однократного секретного кода, пароля или атрибутов пользователя. В этом случае grant_type значение используется для различения этих трех вариантов использования. Возможные значения для grant_type : oob, password, attributes. В этом вызове, так как мы отправляем пароль пользователя, значение, как ожидается, будет паролем. |
password |
Да | Значение пароля, которое приложение собирает от пользователя клиента. Замените {secure_password} значением пароля, которое приложение собирает от пользователя клиента. Вы несете ответственность за подтверждение того, что пользователь знает пароль, который он хочет использовать, предоставив поле подтверждения пароля в пользовательском интерфейсе приложения. Кроме того, необходимо убедиться, что пользователь знает о том, что представляет собой надежный пароль для политики вашей организации. Дополнительные сведения о политиках паролей Microsoft Entra. |
Ответ успешного выполнения
Если запрос выполнен успешно, но атрибуты не были настроены в Центре администрирования Microsoft Entra или все необходимые атрибуты были отправлены через /signup/v1.0/start конечную точку, приложение получает маркер продолжения без отправки каких-либо атрибутов. Приложение может использовать маркер продолжения для запроса маркеров безопасности, как показано на шаге 5. В противном случае ответ Microsoft Entra указывает, что приложению необходимо отправить необходимые атрибуты. Эти атрибуты, встроенные или настраиваемые, были настроены в Центре администрирования Microsoft Entra администратором клиента.
Обязательные атрибуты пользователя
Этот ответ запрашивает приложение отправлять значения для атрибутов имени, *age и телефона .
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "attributes_required",
"error_description": "User attributes required",
"error_codes": [
55106
],
"timestamp": "yy-mm-dd 02:37:33Z",
"trace_id": "d6966055-...-80500",
"correlation_id": "3944-...-60d6",
"continuation_token": "AQABAAEAAAAtn...",
"required_attributes": [
{
"name": "displayName",
"type": "string",
"required": true,
"options": {
"regex": ".*@.**$"
}
},
{
"name": "extension_2588abcdwhtfeehjjeeqwertc_age",
"type": "string",
"required": true
},
{
"name": "postalCode",
"type": "string",
"required": true,
"options": {
"regex":"^[1-9][0-9]*$"
}
}
],
}
Примечание.
Пользовательские атрибуты (также известные как расширения каталогов) называются с помощью соглашения extension_{appId-without-hyphens}_{attribute-name} , в котором {appId-without-hyphens} используется отрезаная версия идентификатора клиента для приложения расширений. Например, если идентификатор клиента приложения 2588a-bcdwh-tfeehj-jeeqw-ertc расширений и имя атрибута является хобби, то настраиваемый атрибут называется какextension_2588abcdwhtfeehjjeeqwertc_hobbies. Дополнительные сведения о пользовательских атрибутах и приложении расширения.
| Параметр | Описание |
|---|---|
error |
Этот атрибут задается, если Microsoft Entra не может создать учетную запись пользователя, так как атрибут должен быть проверен или отправлен. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
required_attributes |
Список (массив объектов) атрибутов, которые приложение должно отправить следующий вызов, чтобы продолжить. Эти атрибуты являются дополнительными атрибутами, которые приложение должно отправлять отдельно от имени пользователя. Microsoft Entra включает этот параметр в ответ, если значение error параметра attributes_required. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например проверка маркера продолжения или запрос не включал client_id параметр, значение идентификатора клиента является пустым или недопустимым. |
invalid_grant |
Тип предоставления, включенный в запрос, не является допустимым или поддерживаемым. Возможные значения для объектаgrant_type: oob, password, attributes |
expired_token |
Срок действия маркера продолжения, включенного в запрос, истекает. |
attributes_required |
Требуется один или несколько атрибутов пользователя. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "New password is too weak",
"error_codes": [
399246
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"suberror": "password_too_weak"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
suberror |
Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например, если challenge_type параметр содержит недопустимый тип вызова. |
invalid_grant |
Предоставленный грант недопустим, например пароль, отправленный слишком коротким. suberror Используйте параметр, чтобы узнать о точной причине ошибки. |
expired_token |
Срок действия маркера продолжения истек. |
attributes_required |
Требуется один или несколько атрибутов пользователя. |
Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра:
| Значение подсервера | Description |
|---|---|
password_too_weak |
Пароль слишком слаб, так как он не соответствует требованиям сложности. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_too_short |
Новый пароль меньше 8 символов. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_too_long |
Новый пароль превышает 256 символов. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_recently_used |
Новый пароль не должен совпадать с недавно использованным паролем. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_banned |
Новый пароль содержит слово, фразу или шаблон, который запрещен. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_is_invalid |
Пароль недопустим, например, так как он использует запрещенные символы. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
Отправка атрибутов пользователя
Чтобы продолжить поток, приложение должно вызвать конечную /signup/v1.0/continue точку, чтобы отправить необходимые атрибуты пользователя. Так как мы отправим атрибуты, attributes требуется параметр, а grant_type параметр должен иметь значение, равное атрибутам.
Ниже приведен пример запроса(мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
grant_type |
Да | Запрос к конечной точке /signup/v1.0/continue можно использовать для отправки однократного секретного кода, пароля или атрибутов пользователя. В этом случае grant_type значение используется для различения этих трех вариантов использования. Возможные значения для grant_type : oob, password, attributes. В этом вызове, так как мы отправляем атрибуты пользователя, значение, как ожидается, будет атрибутами. |
attributes |
Да | Значения атрибутов пользователя, собираемые приложением от пользователя клиента. Это значение является строкой, но форматируется как объект JSON, ключевые значения которого — имена атрибутов пользователя, встроенные или настраиваемые. Имена ключей объекта зависят от атрибутов, настроенных администратором в Центре администрирования Microsoft Entra. Замените {given_name}значения {postal_code} {user_age} имени, возраста и почтового кода соответственно, что приложение собирает от пользователя клиента. Microsoft Entra игнорирует все атрибуты, которые вы отправляете, которые не существуют. |
Ответ успешного выполнения
Если запрос выполнен успешно, Microsoft Entra выдает маркер продолжения, который приложение может использовать для запроса маркеров безопасности.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| Параметр | Описание |
|---|---|
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired. .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
unverified_attributes |
Список (массив объектов) имен ключей атрибутов, которые необходимо проверить. Этот параметр включается в ответ, если error значение параметра verification_required. |
required_attributes |
Список (массив объектов) атрибутов, которые приложение должно отправить. Microsoft Entra включает этот параметр в ответ, если error значение параметра attributes_required. |
invalid_attributes |
Список (массив объектов) атрибутов, которые не прошли проверку. Этот параметр включается в ответ, если suberror значение параметра attribute_validation_failed. |
suberror |
Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например проверка маркера продолжения или запрос не включал client_id параметр, значение идентификатора клиента является пустым или недопустимым. |
invalid_grant |
Указанный тип предоставления не является допустимым или не поддерживается или неудачной проверкой, например сбоем проверки атрибутов. suberror Используйте параметр, чтобы узнать о точной причине ошибки. |
expired_token |
Срок действия маркера продолжения, включенного в запрос, истекает. |
attributes_required |
Требуется один или несколько атрибутов пользователя. |
Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_grant :
| Значение подсервера | Description |
|---|---|
attribute_validation_failed |
Сбой проверки атрибута пользователя. invalid_attributes параметр содержит список (массив объектов) атрибутов, которые не прошли проверку. |
Шаг 5. Запрос маркеров безопасности
Приложение отправляет запрос POST к конечной /token точке и предоставляет маркер продолжения, полученный на предыдущем шаге для получения маркеров безопасности.
Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
continuation_token=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
grant_type |
Да | Значение параметра должно быть маркером продолжения. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra на предыдущем шаге. |
scope |
Да | Разделенный пробелами список областей, для которым допустимы маркер доступа. Замените {scopes} допустимыми областями, для которые возвращается маркер доступа Microsoft Entra. |
username |
Да | Электронная почта пользователя клиента, с которым они хотят зарегистрироваться, например contoso-consumer@contoso.com. |
Успешный ответ
Ниже приведен пример успешного ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"scope": "openid profile",
"expires_in": 4141,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"refresh_token": "AwABAAAA...",
"id_token": "eyJ0eXAiOiJKV1Q..."
}
| Параметр | Описание |
|---|---|
access_token |
Маркер доступа, запрошенный приложением из конечной /token точки. Приложение может использовать этот маркер доступа для запроса доступа к защищенным ресурсам, таким как веб-API. |
token_type |
Указывает значение типа маркера. Единственным типом, поддерживаемым Microsoft Entra, является носитель. |
expires_in |
Продолжительность времени в секундах маркера доступа остается допустимым. |
scopes |
Разделенный пробелами список областей, для которым допустимы маркер доступа. |
refresh_token |
Маркер обновления OAuth 2.0. Приложение может использовать этот маркер, чтобы получать другие маркеры доступа после истечения срока действия текущего маркера. Маркеры обновления имеют большой срок действия. Они могут поддерживать доступ к ресурсам для расширенных периодов. Дополнительные сведения об обновлении маркера доступа см . в статье об обновлении маркера доступа. Примечание. Только при запросе offline_access области. |
id_token |
Веб-токен JSON (Jwt), используемый для идентификации пользователя клиента. Приложение может декодировать маркер для чтения сведений о пользователе, выполнившем вход. Приложение может кэшировать значения и отображать их, а конфиденциальные клиенты могут использовать этот маркер для авторизации. Дополнительные сведения о маркерах идентификаторов см. в разделе "Маркеры идентификаторов". Примечание. Выдается только в том случае, если запрашивается область openid . |
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например клиент или приложение, не имеет согласия на запрошенные области. |
invalid_grant |
Маркер продолжения, включенный в запрос, недопустим. |
unauthorized_client |
Идентификатор клиента, включенный в запрос, является недопустимым или не существует. |
unsupported_grant_type |
Тип предоставления, включенный в запрос, не поддерживается или является неверным. |
Отправка атрибутов пользователя в конечные точки
В Центре администрирования Microsoft Entra можно настроить атрибуты пользователей как обязательные или необязательные. Эта конфигурация определяет, как Microsoft Entra реагирует при вызове к конечным точкам. Необязательные атрибуты не являются обязательными для завершения потока регистрации. Таким образом, если все атрибуты являются необязательными, они должны быть отправлены перед проверкой имени пользователя. В противном случае регистрация завершается без необязательных атрибутов.
В следующей таблице приведены сведения о том, когда можно отправить атрибуты пользователя в конечные точки Microsoft Entra.
| Конечная точка | Требуемые атрибуты | Необязательные атрибуты | Обязательные и необязательные атрибуты |
|---|---|---|---|
/signup/v1.0/start конечная точка |
Да | Да | Да |
/signup/v1.0/continue конечная точка перед проверкой имени пользователя |
Да | Да | Да |
/signup/v1.0/continue конечная точка после проверки имени пользователя |
Да | No | Да |
Формат значений атрибутов пользователя
Укажите сведения, которые нужно собрать от пользователя, настроив параметры потока пользователя в Центре администрирования Microsoft Entra. Используйте настраиваемые атрибуты пользователя во время регистрации, чтобы узнать, как собирать значения для встроенных и пользовательских атрибутов.
Можно также указать тип ввода пользователя для настроенных атрибутов. В следующей таблице перечислены поддерживаемые типы входных данных пользователей и отправка значений, собранных элементами управления пользовательского интерфейса в Microsoft Entra.
| Тип ввода пользователя | Формат отправленных значений |
|---|---|
| TextBox | Одно значение, например название задания, инженер программного обеспечения. |
| SingleRadioSelect | Одно значение, например язык, норвежский. |
| CheckboxMultiSelect | Одно или несколько значений, таких как хобби или хобби, танцы или танцы, плавание, путешествия. |
Ниже приведен пример запроса, демонстрирующего отправку значений атрибутов:
POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
continuation_token=ABAAEAAAAtfyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...
Дополнительные сведения о типах входных данных атрибутов пользователей см. в статье о типах входных данных пользовательских атрибутов .
Как ссылаться на атрибуты пользователя
При создании потока пользователя регистрации вы настраиваете атрибуты пользователей, которые требуется собирать от пользователя во время регистрации. Имена атрибутов пользователей в Центре администрирования Microsoft Entra отличаются от того, как вы ссылаетесь на них в собственном API проверки подлинности.
Например, отображаемое имя в Центре администрирования Microsoft Entra ссылается как displayName в API.
Используйте статью "Атрибуты профиля пользователя", чтобы узнать, как ссылаться на встроенные и пользовательские атрибуты пользователя в собственном API проверки подлинности.
Справочник по API входа
Пользователям необходимо войти с помощью метода проверки подлинности, который они используют для регистрации. Например, пользователи, которые регистрывают электронную почту с помощью метода проверки подлинности паролей, должны входить в электронную почту и пароль.
Чтобы запросить маркеры безопасности, приложение взаимодействует с тремя конечными точками, /initiate/challenge а также /token.
Конечные точки API входа
| Конечная точка | Description |
|---|---|
/initiate |
Эта конечная точка инициирует поток входа. Если приложение вызывает его с именем пользователя учетной записи пользователя, которая уже существует, он возвращает ответ успешно с маркером продолжения. Если приложение запрашивает использование методов проверки подлинности, которые не поддерживаются Microsoft Entra, этот ответ конечной точки может указать приложению, что он должен использовать поток проверки подлинности на основе браузера. |
/challenge |
приложение вызывает эту конечную точку со списком типов вызовов, поддерживаемых службой удостоверений. Наша служба удостоверений создает, а затем отправляет одноразовый секретный код выбранному каналу вызовов, например электронной почте. Если приложение неоднократно вызывает эту конечную точку, при каждом вызове отправляется новый OTP. |
/token |
Эта конечная точка проверяет одноразовый секретный код, полученный из приложения, а затем выдает маркеры безопасности приложению. |
Типы проблем входа
API позволяет приложению объявлять поддерживаемые методы проверки подлинности при вызове Microsoft Entra. Для этого приложение использует challenge_type параметр в своих запросах. Этот параметр содержит предопределенные значения, представляющие различные методы проверки подлинности.
Для данного метода проверки подлинности значение типа вызова, которое приложение отправляет в Microsoft Entra во время регистрации, совпадает с тем, когда приложение войдет в систему. Например, электронная почта с методом проверки подлинности паролей использует значения типа oob, password и redirect challenge для потоков регистрации и входа.
Дополнительные сведения о типах вызовов в собственных типах вызовов проверки подлинности см. в статье.
Сведения о протоколе потока входа
Схема последовательности демонстрирует поток процесса входа.
После проверки электронной почты пользователя с помощью OTP приложение получает маркеры безопасности. Если доставка однократного секретного кода или никогда не доставляется по электронной почте пользователя, пользователь может запросить отправку другого секретного кода. Microsoft Entra повторно отправляет другой одноразовый секретный код, если предыдущий не был проверен. Когда Microsoft Entra повторно отправляет одноразовый секретный код, он отменяет ранее отправленный код.
В следующих разделах мы обобщаем поток схемы последовательности на три основных шага.
Шаг 1. Запрос на запуск потока входа
Поток проверки подлинности начинается с приложения, выполняющего запрос POST к /initiate конечной точке, чтобы запустить поток входа.
Ниже приведен пример запроса(мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
username |
Да | Электронная почта пользователя клиента, например contoso-consumer@contoso.com. |
challenge_type |
Да | Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Ожидается, что значение будет oob redirect отправлено для однократного секретного кода электронной почты и password redirect для электронной почты с паролем. |
Ответ успешного выполнения
Ниже приведен пример успешного ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Параметр | Описание |
|---|---|
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например, если challenge_type параметр содержит недопустимый тип вызова. или запрос не включал client_id параметр, значение идентификатора клиента является пустым или недопустимым. error_description Используйте параметр, чтобы узнать о точной причине ошибки. |
unauthorized_client |
Идентификатор клиента, используемый в запросе, имеет допустимый формат идентификатора клиента, но не существует во внешнем клиенте или является неверным. |
invalid_client |
Идентификатор клиента, который приложение включает в запрос, предназначен для приложения, которое не имеет собственной конфигурации проверки подлинности, например не является общедоступным клиентом или не включено для собственной проверки подлинности. suberror Используйте параметр, чтобы узнать о точной причине ошибки. |
user_not_found |
имя пользователя не существует; |
unsupported_challenge_type |
Значение challenge_type параметра не включает redirect тип вызова. |
Если параметр ошибки имеет значение invalid_client, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_client :
| Значение подсервера | Description |
|---|---|
nativeauthapi_disabled |
Идентификатор клиента для приложения, которое не включается для собственной проверки подлинности. |
Шаг 2. Выбор метода проверки подлинности
Чтобы продолжить работу с потоком, приложение использует маркер продолжения, полученный на предыдущем шаге, чтобы запросить Microsoft Entra выбрать один из поддерживаемых типов вызовов для пользователя для проверки подлинности. Приложение отправляет запрос POST к конечной точке /challenge .
Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
challenge_type |
No | Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Ожидается, что значение будет oob redirect отправлено для однократного секретного кода электронной почты и password redirect для электронной почты с паролем. |
Ответ успешного выполнения
Если администратор клиента настроит одноразовый секретный код электронной почты в Центре администрирования Microsoft Entra в качестве метода проверки подлинности пользователя, Microsoft Entra отправляет одноразовый секретный код на электронную почту пользователя, а затем отвечает с типом вызова oob и предоставляет дополнительные сведения об однократном секретном коде.
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "oob",
"binding_method": "prompt ",
"challenge_channel": "email",
"challenge_target_label ": "c***r@co**o**o.com ",
"code_length": 8
}
| Параметр | Описание |
|---|---|
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
challenge_type |
Тип вызова, выбранный для проверки подлинности пользователя. |
binding_method |
Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob |
challenge_channel |
Тип канала, через который был отправлен одноразовый секретный код. На данный момент мы поддерживаем электронную почту. |
challenge_target_label |
Замаскированное сообщение электронной почты, в котором был отправлен одноразовый секретный код. |
code_length |
Длина однократного секретного кода, который создает Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например, если challenge_type параметр содержит недопустимый тип вызова. |
invalid_grant |
Маркер продолжения, включенный в запрос, недействителен. |
expired_token |
Срок действия маркера продолжения, включенного в запрос, истекает. |
unsupported_challenge_type |
Значение challenge_type параметра не включает redirect тип вызова. |
Шаг 3. Запрос маркеров безопасности
Приложение отправляет запрос POST к /token конечной точке и предоставляет учетные данные пользователя, выбранные на предыдущем шаге, в этом случае пароль для получения маркеров безопасности.
Ниже приведен пример запроса(мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
&scope=openid offline_access
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
grant_type |
Да | Значение должно быть паролем для электронной почты с помощью метода проверки подлинности паролей и oob для метода одноразовой проверки подлинности секретного кода электронной почты. |
scope |
Да | Список областей с разделителями-пробелами. Все области должны быть из одного ресурса, а также областей OpenID Connect (OIDC), таких как профиль, *openid и электронная почта. Приложение должно включить область openid для Microsoft Entra для выдачи маркера идентификатора. Приложению необходимо включить область offline_access для Microsoft Entra, чтобы выдать маркер обновления. Дополнительные сведения о разрешениях и согласиях см. в платформа удостоверений Майкрософт. |
password |
Да (для электронной почты с паролем) |
Значение пароля, которое приложение собирает от пользователя клиента. Замените {secure_password} значением пароля, которое приложение собирает от пользователя клиента. |
oob |
Да (для однократного секретного кода электронной почты) |
Одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Замените {otp_code} одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Чтобы повторно отправить одноразовый секретный код, приложение должно снова запросить /challenge конечную точку. |
Успешный ответ
Ниже приведен пример успешного ответа:
HTTP/1.1 200 OK
Content-Type: application/json
{
"token_type": "Bearer",
"scope": "openid profile",
"expires_in": 4141,
"access_token": "eyJ0eXAiOiJKV1Qi...",
"refresh_token": "AwABAAAA...",
"id_token": "eyJ0eXAiOiJKV1Q..."
}
| Параметр | Описание |
|---|---|
token_type |
Указывает значение типа маркера. Единственным типом, поддерживаемым Microsoft Entra, является носитель. |
scopes |
Разделенный пробелами список областей, для которым допустимы маркер доступа. |
expires_in |
Продолжительность времени в секундах маркера доступа остается допустимым. |
access_token |
Маркер доступа, запрошенный приложением из конечной /token точки. Приложение может использовать этот маркер доступа для запроса доступа к защищенным ресурсам, таким как веб-API. |
refresh_token |
Маркер обновления OAuth 2.0. Приложение может использовать этот маркер, чтобы получать другие маркеры доступа после истечения срока действия текущего маркера. Маркеры обновления имеют большой срок действия. Они могут поддерживать доступ к ресурсам для расширенных периодов. Дополнительные сведения об обновлении маркера доступа см . в статье об обновлении маркера доступа. Примечание. Только при запросе offline_access области. |
id_token |
Веб-токен JSON (Jwt), используемый для идентификации пользователя клиента. Приложение может декодировать маркер, чтобы запросить сведения о пользователе, вошедшем в систему. Приложение может кэшировать значения и отображать их, а конфиденциальные клиенты могут использовать этот маркер для авторизации. Дополнительные сведения о маркерах идентификаторов см. в разделе "Маркеры идентификаторов". Примечание. Только при запросе области openid . |
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_grant",
"error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
50126
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса. Чтобы понять, что произошло, используйте сообщение в описании ошибки. |
invalid_grant |
Маркер продолжения, включенный в запрос, не является допустимым, или учетные данные для входа пользователя клиента, включенные в запрос, недопустимы или тип предоставления, включенный в запрос, неизвестен. |
invalid_client |
Идентификатор клиента, включенный в запрос, не является общедоступным клиентом. |
expired_token |
Срок действия маркера продолжения, включенного в запрос, истекает. |
invalid_scope |
Одна или несколько областей, включенных в запрос, недопустимы. |
Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_grant :
| Значение подсервера | Description |
|---|---|
invalid_oob_value |
Недопустимое значение однократного секретного кода. Эта вложенная ошибка применяет только одноразовый секретный код электронной почты |
Самостоятельный сброс пароля (SSPR)
Если вы используете электронную почту и пароль в качестве метода проверки подлинности в приложении, используйте API самостоятельного сброса пароля (SSPR), чтобы разрешить пользователям клиента сбрасывать пароль. Используйте этот API для забыли пароль или изменяйте сценарии паролей.
Конечные точки API самостоятельного сброса пароля
Чтобы использовать этот API, приложение взаимодействует с конечной точкой, показанной в следующей таблице:
| Конечная точка | Description |
|---|---|
/start |
Ваше приложение вызывает эту конечную точку, когда пользователь выбирает пароль или кнопку "Изменить пароль" в приложении. Эта конечная точка проверяет имя пользователя (электронная почта), а затем возвращает маркер продолжения для использования в потоке сброса пароля. Если приложение запрашивает использование методов проверки подлинности, которые не поддерживаются Microsoft Entra, этот ответ конечной точки может указать приложению, что он должен использовать поток проверки подлинности на основе браузера. |
/challenge |
Принимает список типов вызовов, поддерживаемых клиентом и маркером продолжения. Вызов выдается одному из предпочтительных учетных данных восстановления. Например, вызов oob выдает одноразовый секретный код для электронной почты, связанной с учетной записью пользователя клиента. Если приложение запрашивает использование методов проверки подлинности, которые не поддерживаются Microsoft Entra, этот ответ конечной точки может указать приложению, что он должен использовать поток проверки подлинности на основе браузера. |
/continue |
Проверяет проблему, выданную конечной /challenge точкой, а затем возвращает маркер продолжения для /submit конечной точки или выдает другой вызов пользователю. |
/submit |
Принимает новый ввод пароля пользователем вместе с маркером продолжения для завершения потока сброса пароля. Эта конечная точка выдает еще один маркер продолжения. |
/poll_completion |
Наконец, приложение может использовать маркер продолжения, выданный /submit конечной точкой, чтобы проверить состояние запроса сброса пароля. |
Типы вызовов самостоятельного сброса пароля
API позволяет приложению объявлять поддерживаемые методы проверки подлинности при вызове Microsoft Entra. Для этого приложение использует challenge_type параметр в своих запросах. Этот параметр содержит предопределенные значения, представляющие различные методы проверки подлинности.
Для потока SSPR значения типов вызовов — oob и перенаправление.
Дополнительные сведения о типах вызовов в собственных типах вызовов проверки подлинности.
Сведения о протоколе потока самостоятельного сброса пароля
Схема последовательности демонстрирует поток для процесса сброса пароля.
На этой схеме указано, что приложение собирает имя пользователя (электронную почту) и пароль от пользователя в разное время (и, возможно, на отдельных экранах). Однако вы можете создать приложение для сбора имени пользователя (электронной почты) и нового пароля на одном экране. В этом случае приложение содержит пароль, а затем отправляет его через /submit конечную точку, где это необходимо.
Шаг 1. Запрос на запуск потока самостоятельного сброса пароля
Поток сброса пароля начинается с приложения, выполняющего запрос POST к /start конечной точке, чтобы запустить поток самостоятельного сброса пароля.
Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&username=contoso-consumer@contoso.com
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
username |
Да | Электронная почта пользователя клиента, например contoso-consumer@contoso.com. |
challenge_type |
Да | Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Для этого запроса ожидается, что значение будет содержаться oob redirect. |
Ответ успешного выполнения
Пример:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| Параметр | Описание |
|---|---|
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например, если challenge_type параметр включает недопустимый тип вызова или запрос не включал client_id параметр, значение идентификатора клиента является пустым или недопустимым. error_description Используйте параметр, чтобы узнать о точной причине ошибки. |
user_not_found |
имя пользователя не существует; |
unsupported_challenge_type |
Значение challenge_type параметра не включает redirect тип вызова. |
invalid_client |
Идентификатор клиента, который приложение включает в запрос, предназначен для приложения, которое не имеет собственной конфигурации проверки подлинности, например не является общедоступным клиентом или не включено для собственной проверки подлинности. suberror Используйте параметр, чтобы узнать о точной причине ошибки. |
unauthorized_client |
Идентификатор клиента, используемый в запросе, имеет допустимый формат идентификатора клиента, но не существует во внешнем клиенте или является неверным. |
Если параметр ошибки имеет значение invalid_client, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_client :
| Значение подсервера | Description |
|---|---|
nativeauthapi_disabled |
Идентификатор клиента для приложения, которое не включается для собственной проверки подлинности. |
Шаг 2. Выбор метода проверки подлинности
Чтобы продолжить работу с потоком, приложение использует маркер продолжения, полученный на предыдущем шаге, чтобы запросить Microsoft Entra выбрать один из поддерживаемых типов вызовов для пользователя для проверки подлинности. Приложение отправляет запрос POST к конечной точке /challenge . Если этот запрос выполнен успешно, Microsoft Entra отправляет одноразовый секретный код в адрес электронной почты учетной записи пользователя. На данный момент мы поддерживаем только электронную почту OTP.
Ниже приведен пример (мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
challenge_type |
No | Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob redirectнапример. Список должен всегда включать redirect тип вызова. Для этого запроса ожидается, что значение будет содержаться oob redirect. |
Ответ успешного выполнения
Пример:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"challenge_type": "oob",
"binding_method": "prompt ",
"challenge_channel": "email",
"challenge_target_label ": "c***r@co**o**o.com ",
"code_length": 8
}
| Параметр | Описание |
|---|---|
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
challenge_type |
Тип вызова, выбранный для проверки подлинности пользователя. |
binding_method |
Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления пользователю дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob |
challenge_channel |
Тип канала, через который был отправлен одноразовый секретный код. На данный момент мы поддерживаем электронную почту. |
challenge_target_label |
Замаскированное сообщение электронной почты, в котором был отправлен одноразовый секретный код. |
code_length |
Длина однократного секретного кода, который создает Microsoft Entra. |
Если приложение не может поддерживать необходимый метод проверки подлинности microsoft Entra, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип запроса перенаправления в ответе:
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| Параметр | Описание |
|---|---|
challenge_type |
Microsoft Entra возвращает ответ с типом вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта. |
Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например, если challenge_type параметр включает недопустимый тип вызова или проверку маркера продолжения не удалось. |
expired_token |
Срок действия маркера продолжения истек. |
unsupported_challenge_type |
Значение challenge_type параметра не включает redirect тип вызова. |
Шаг 3. Отправка однократного секретного кода
Затем приложение отправляет запрос POST к конечной точке /continue . В запросе приложение должно включить учетные данные пользователя, выбранные на предыдущем шаге, и маркер продолжения, выданный конечной /challenge точкой.
Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
grant_type |
Да | Единственное допустимое значение — oob. |
oob |
Да | Одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Замените {otp_code} одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Чтобы повторно отправить одноразовый секретный код, приложение должно снова запросить /challenge конечную точку. |
Ответ успешного выполнения
Пример:
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| Параметр | Описание |
|---|---|
expires_in |
Время в секундах до истечения срока действия continuation_token . Максимальное значение expires_in составляет 600 секунд. |
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
55200
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
suberror |
Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например проверка маркера продолжения, или запрос не включал client_id параметр, значение идентификатора клиента является пустым или недопустимым, или внешний администратор клиента не включил SSPR и электронную почту OTP для всех пользователей клиента. error_description Используйте параметр, чтобы узнать о точной причине ошибки. |
invalid_grant |
Тип гранта неизвестен или не соответствует ожидаемому значению типа гранта. suberror Используйте параметр, чтобы узнать о точной причине ошибки. |
expired_token |
Срок действия маркера продолжения истек. |
Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра для ошибки invalid_grant :
| Значение подсервера | Description |
|---|---|
invalid_oob_value |
Одноразовый секретный код, предоставленный пользователем, является недопустимым. |
Шаг 4. Отправка нового пароля
Приложение собирает новый пароль от пользователя, а затем использует маркер продолжения, выданный /continue конечной точкой, чтобы отправить пароль, выполнив запрос POST к конечной точке /submit .
Ниже приведен пример (мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
new_password |
Да | Новый пароль пользователя. Замените {new_password} новым паролем пользователя. Вы несете ответственность за подтверждение того, что пользователь знает пароль, который он хочет использовать, предоставив поле подтверждения пароля в пользовательском интерфейсе приложения. Кроме того, необходимо убедиться, что пользователь знает о том, что представляет собой надежный пароль для политики вашей организации. Дополнительные сведения о политиках паролей Microsoft Entra. |
Ответ успешного выполнения
Пример:
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY...",
"poll_interval": 2
}
| Параметр | Описание |
|---|---|
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. |
poll_interval |
Минимальное время в секундах, которое приложение должно ожидать между запросами опроса, чтобы проверить состояние запроса сброса пароля через /poll_completion конечную точку, см . шаг 5. |
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
901007
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
suberror |
Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например проверка маркера продолжения завершилась ошибкой. |
expired_token |
Срок действия маркера продолжения истек. |
invalid_grant |
Предоставленный грант недопустим, например пароль, отправленный слишком коротким. suberror Используйте параметр, чтобы узнать о точной причине ошибки. |
Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает suberror параметр в ответ. Ниже приведены возможные значения suberror параметра:
| Значение подсервера | Description |
|---|---|
password_too_weak |
Пароль слишком слаб, так как он не соответствует требованиям сложности. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_too_short |
Новый пароль меньше 8 символов. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_too_long |
Новый пароль превышает 256 символов. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_recently_used |
Новый пароль не должен совпадать с недавно использованным паролем. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_banned |
Новый пароль содержит слово, фразу или шаблон, который запрещен. Дополнительные сведения о политиках паролей Microsoft Entra. |
password_is_invalid |
Пароль недопустим, например, так как он использует запрещенные символы. Дополнительные сведения о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя. |
Шаг 5. Опрос состояния сброса пароля
Наконец, так как обновление конфигурации пользователя с новым паролем вызывает некоторую задержку, приложение может использовать /poll_completion конечную точку для опроса Microsoft Entra для состояния сброса пароля. Минимальное время в секундах, которое приложение должно ожидать между запросами опроса, возвращается из конечной /submit точки в параметре poll_interval .
Ниже приведен пример (мы представляем пример запроса в нескольких строках для удобства чтения):
POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...
| Параметр | Обязательное поле | Описание: |
|---|---|---|
tenant_subdomain |
Да | Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте. |
continuation_token |
Да | Маркер продолжения, возвращаемый Microsoft Entra в предыдущем запросе. |
client_id |
Да | Идентификатор приложения (клиента), зарегистрированного в Центре администрирования Microsoft Entra. |
Ответ успешного выполнения
Пример:
HTTP/1.1 200 OK
Content-Type: application/json
{
"status": "succeeded",
"continuation_token":"czZCaGRSa3F0..."
}
| Параметр | Описание |
|---|---|
status |
Состояние запроса на сброс пароля. Если Microsoft Entra возвращает состояние сбоя, приложение может повторно отправить новый пароль, выполнив другой запрос к /submit конечной точке и включив новый маркер продолжения. |
continuation_token |
Маркер продолжения, возвращающий Microsoft Entra. Если состояние выполнено успешно, приложение может использовать маркер продолжения, который Microsoft Entra возвращает для запроса маркеров безопасности через /token конечную точку, как описано на шаге 5 потока регистрации. Это означает, что после успешного сброса пароля пользователь может напрямую войти в приложение, не инициируя новый поток входа. |
Ниже приведены возможные состояния, возвращаемые Microsoft Entra (возможные значения status параметра):
| Значение ошибки | Description |
|---|---|
succeeded |
Сброс пароля успешно завершен. |
failed |
Сбой сброса пароля. Приложение может повторно отправить новый пароль, выполнив другой запрос к конечной точке /submit . |
not_started |
Сброс пароля не начался. Приложение может снова проверить состояние позже. |
in_progress |
Выполняется сброс пароля. Приложение может снова проверить состояние позже. |
Отклик в случае ошибки
Пример:
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "expired_token",
"error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
"error_codes": [
552003
],
"timestamp": "yyyy-mm-dd 10:15:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Параметр | Описание |
|---|---|
error |
Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок и реагирования на ошибки. |
error_description |
Определенное сообщение об ошибке, которое поможет определить причину ошибки проверки подлинности. |
error_codes |
Список кодов ошибок, относящихся к Microsoft Entra, которые помогут вам диагностировать ошибки. |
timestamp |
Время, когда произошла ошибка. |
trace_id |
Уникальный идентификатор запроса, который помогает диагностировать ошибки. |
correlation_id |
Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error параметра):
| Значение ошибки | Description |
|---|---|
invalid_request |
Сбой проверки параметров запроса, например проверка маркера продолжения. |
expired_token |
Срок действия маркера продолжения истек. |
Связанный контент
- Настройте настраиваемый поставщик утверждений.