Справочник по API собственной проверки подлинности

Применяется: Внешние клиенты (дополнительные сведения)

Microsoft Entra native authentication позволяет размещать пользовательский интерфейс приложения в клиентском приложении вместо делегирования проверки подлинности в браузерах, что приводит к встроенной интеграции проверки подлинности. У разработчика есть полный контроль над внешним видом и интерфейсом входа.

В этой справочной статье API описаны сведения, необходимые только при выполнении потока вручную необработанным HTTP-запросам. Однако мы не рекомендуем этот подход. Поэтому, когда это возможно, используйте встроенный и поддерживаемый корпорацией Майкрософт пакет SDK для проверки подлинности. Дополнительные сведения о пакетах SDK для собственной проверки подлинности. При успешном вызове конечных точек API вы получаете как маркер идентификатора для идентификации пользователя, так и маркер доступа для вызова защищенных API. Все ответы API находятся в формате JSON.

API собственной проверки подлинности Microsoft Entra поддерживает регистрацию и вход для двух потоков проверки подлинности:

• Электронная почта с паролем, которая поддерживает регистрацию и вход с помощью электронной почты и пароля, а также самостоятельного сброса пароля (SSPR).

  • Пользователи, которые входят с адресом электронной почты и паролем, также могут войти с именем пользователя и паролем.

• Одноразовый секретный код электронной почты, который поддерживает регистрацию и вход с помощью одноразового секретного кода электронной почты.

Примечание.

В настоящее время конечные точки API собственной проверки подлинности не поддерживают общий доступ к ресурсам между источниками (CORS).

Необходимые компоненты

1. Внешний клиент Microsoft Entra. Если у вас еще нет одного, создайте внешний клиент.

2. Если вы еще этого не сделали, Register приложение в центре администрирования Microsoft Entra. Обязательно сделайте следующее:

   • Запишите идентификатор приложения (клиента) и идентификатор каталога (клиента) для последующего использования.
   • Предоставьте приложению согласие администратора .
   • Включите общедоступный клиент и собственные потоки проверки подлинности.

3. Если вы еще этого не сделали, Create поток пользователя в центре администрирования Microsoft Entra. При создании потока пользователя обратите внимание на атрибуты пользователя, которые вы настраиваете по мере необходимости, так как эти атрибуты являются теми, которые Microsoft Entra ожидает отправки приложения.

4. Свяжите регистрацию приложения с потоком пользователя.

5. Для процесса входа зарегистрируйте пользователя клиента, который используется для тестирования потока. Кроме того, этот тестовый пользователь можно получить после запуска потока регистрации.

6. Для потока SSPR включите самостоятельный сброс пароля для пользователей клиента во внешнем клиенте. SSPR доступен для пользователей клиентов, использующих электронную почту с методом проверки подлинности паролем.

7. Если вы хотите позволить пользователям, которые входят с адресом электронной почты и паролем, также входить с именем пользователя и паролем, используйте шаги в разделе «Войти с псевдонимом или статьей с именем пользователя »:

   1. Включите имя пользователя в входе.
   2. Создайте пользователей с именем пользователя в Центре администрирования или обновите существующих пользователей, добавив имя пользователя. Кроме того, вы также можете automate пользователя и обновление в приложении с помощью Microsoft Graph API.

8. Чтобы применить многофакторную проверку подлинности (MFA) для клиентов, выполните действия, описанные в разделе "Добавление многофакторной проверки подлинности (MFA) в приложение , чтобы добавить MFA в поток входа. Встроенная проверка подлинности поддерживает одноразовый секретный код электронной почты и SMS в качестве второго фактора для MFA.

Метка продолжения

Каждый раз, когда вы вызываете вход, регистрацию или конечную точку SSPR, ответ включает маркер продолжения. Этот маркер однозначно идентифицирует текущий поток и позволяет Microsoft Entra ID поддерживать состояние в конечных точках. Включите маркер в каждый последующий запрос в этом потоке. Он действителен только в течение ограниченного времени и может использоваться только для последующих запросов в том же потоке.

Ссылка API для регистрации

Чтобы завершить поток регистрации пользователя для любого метода проверки подлинности, приложение взаимодействует с четырьмя конечными точками, , /signup/v1.0/startи /signup/v1.0/challenge/signup/v1.0/continue./token

Конечные точки API для регистрации

Конечная точка	Описание
/signup/v1.0/start	Эта конечная точка запускает поток регистрации. Вы передаете действительный идентификатор приложения, новое имя пользователя и тип вызова, а затем возвращаете новый маркер продолжения. Конечная точка может вернуть ответ, указывающий приложению на использование потока веб-проверки подлинности, если выбранные методы проверки подлинности приложения не поддерживаются Microsoft Entra.
/signup/v1.0/challenge	Приложение вызывает эту конечную точку со списком типов challenge поддерживаемых Microsoft Entra. Microsoft Entra затем выбирает один из поддерживаемых методов проверки подлинности для пользователя для проверки подлинности.
/signup/v1.0/continue	Эта конечная точка помогает продолжить поток для создания учетной записи пользователя или прерывания потока из-за отсутствующих требований, таких как требования политики паролей или неправильные форматы атрибутов. Эта конечная точка создает маркер продолжения, а затем возвращает его в приложение. Конечная точка может вернуть ответ, указывающий приложению, чтобы использовать поток проверки подлинности на основе веб-сайтов, если приложение не использует метод проверки подлинности, выбранный Microsoft Entra.
oauth/v2.0/token	Приложение вызывает эту конечную точку, чтобы, наконец, запросить маркеры безопасности. Приложение должно использовать маркер продолжения, полученный из последнего успешного вызова конечной /signup/v1.0/continue точки.

Типы проблем регистрации

API позволяет клиентскому приложению объявлять поддерживаемые методы проверки подлинности при вызове Microsoft Entra. Для этого приложение использует challenge_type параметр в запросе приложения. Этот параметр содержит предопределенные значения, представляющие различные методы проверки подлинности.

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

Сведения о протоколе потока регистрации

Схема последовательности демонстрирует поток процесса регистрации.

На этой схеме указано, что приложение собирает имя пользователя (электронную почту), пароль (для электронной почты с потоком проверки подлинности паролей) и атрибуты пользователя в разное время (и, возможно, на отдельных экранах). Однако вы можете создать приложение для сбора имени пользователя (электронной почты), пароля и всех необходимых и необязательных значений атрибутов на одном экране, а затем отправить все их в конечную точку /signup/v1.0/start . Если приложение отправляет все необходимые сведения /signup/v1.0/start в конечную точку, приложение не должно выполнять вызовы и обрабатывать ответы в необязательных шагах.

На шаге 21 пользователь уже зарегистрирован. Однако если приложению требуется автоматический вход пользователя после регистрации, приложение вызывает oauth/v2.0/token конечную точку для запроса маркеров безопасности.

Шаг 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	нет	Значение пароля, которое приложение собирает от пользователя клиента. Пароль пользователя можно отправить через конечную /signup/v1.0/start точку или позже /signup/v1.0/continue . Замените {secure_password} значением пароля, которое приложение собирает от пользователя клиента. Вы несете ответственность за подтверждение того, что пользователь знает пароль, который он хочет использовать, предоставив поле подтверждения пароля в пользовательском интерфейсе приложения. Кроме того, необходимо убедиться, что пользователь знает о том, что представляет собой надежный пароль для политики вашей организации. Learn больше о политиках паролей Microsoft Entra. Этот параметр применим только для электронной почты с помощью метода проверки подлинности паролей.
attributes	нет	Значения атрибутов пользователя, собираемые приложением от пользователя клиента. Это значение представляет собой строку, но отформатированную как объект 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}значения {user_age}{postal_code} имени, возраста и почтового кода соответственно, что приложение собирает от пользователя клиента. Microsoft Entra игнорирует все атрибуты, которые вы отправляете, которые не существуют.
capabilities	нет	Разделенные пробелами флаги, описывающие возможности клиентского приложения. Хотя challenge_type определяет, какие методы можно оспаривать, сообщите собственному API проверки подлинности, capabilities какие дополнительные потоки клиентское приложение может обрабатывать и какие пользовательские интерфейсы могут отображаться пользователю. Например, означает другой mfa_required и /challenge цикл; /token означает, registration_required что клиентское приложение вызывает API регистрации и отображает пользовательский интерфейс регистрации. Если требуемая возможность не объявляется клиентским приложением, API возвращает перенаправление. Поддерживаемые значения: mfa_required и registration_required. Дополнительные сведения о возможностях.

Ответ успешного выполнения

Ниже приведен пример успешного ответа:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "AQABAAEAAA…",
} 

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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 свойства):

Значение ошибки	Описание
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 :

Значение подсервера	Описание
password_too_weak	Пароль слишком слаб, так как он не соответствует требованиям сложности. Learn больше о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя.
password_too_short	Новый пароль меньше 8 символов. Learn больше о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя.
password_too_long	Новый пароль превышает 256 символов. Learn больше о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя.
password_recently_used	Новый пароль не должен совпадать с недавно использованным паролем. Learn больше о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя.
password_banned	Новый пароль содержит слово, фразу или шаблон, который запрещен. Learn больше о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя.
password_is_invalid	Пароль недопустим, например, так как он использует запрещенные символы. Learn больше о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя.

Если параметр ошибки имеет значение invalid_client, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства для ошибки invalid_client :

Значение подсервера	Описание
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	нет	Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Ожидается, что значение для oob redirect однократного секретного кода электронной почты и oob password redirect для электронной почты с помощью метода проверки подлинности паролей.
continuation_token	Да	токен Continuation, который 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	токен Continuation, который возвращает Microsoft Entra.
challenge_type	Тип вызова, выбранный для проверки подлинности пользователя.
binding_method	Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления пользователю дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob
challenge_channel	Тип канала, через который был отправлен одноразовый секретный код. На данный момент поддерживается только канал электронной почты.
challenge_target_label	Замаскированное сообщение электронной почты, в котором был отправлен одноразовый секретный код.
code_length	Длина однократного секретного кода, который Microsoft Entra генерируется.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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 свойства):

Значение ошибки	Описание
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	Да	токен Continuation, который 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 выдает маркер продолжения. Приложение может использовать маркер продолжения для запроса маркеров безопасности, как показано в запросе маркеров безопасности.
Приложение успешно отправляет пароль пользователя (для электронной почты с методом проверки подлинности паролей) через /signup/v1.0/start, но не все необходимые атрибуты пользователя, Microsoft Entra указывает атрибуты, которые приложение должно отправить, как показано в атрибутах user обязательные.	Приложение должно отправлять необходимые атрибуты пользователя через конечную точку /signup/v1.0/continue . Ответ аналогичен одному из обязательных атрибутов пользователя. Отправьте атрибуты пользователя, показанные в отправке атрибутов пользователя.
Приложение не отправляет пароль пользователя (для электронной почты с методом проверки подлинности паролей) через /signup/v1.0/start конечную точку.	ответ Microsoft Entra указывает, что необходимы учетные данные. См . ответ. Этот ответ возможен для электронной почты с помощью метода проверки подлинности паролей.

Ответ

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	токен Continuation, который возвращает Microsoft Entra.
suberror	Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок.

Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error свойства):

Значение ошибки	Описание
credential_required	Для создания учетной записи требуется проверка подлинности, поэтому необходимо выполнить вызов к конечной /signup/v1.0/challenge точке, чтобы определить учетные данные, необходимые пользователю.
invalid_request	Сбой проверки параметров запроса, например проверка маркераклиента является пустым или недопустимым, или внешний администратор клиента не включил сообщение OTP для всех пользователей клиента.
invalid_grant	Тип предоставления, включенный в запрос, не является допустимым или поддерживаемым, или значение OTP неверно.
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.

Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства для ошибки invalid_grant :

Значение подсервера	Описание
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	нет	Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Для сообщения электронной почты с потоком регистрации паролей ожидается, что значение будет содержаться password redirect.
continuation_token	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.

Ответ успешного выполнения

Если пароль — это метод проверки подлинности, настроенный для пользователя в центре администрирования Microsoft Entra, то в приложение возвращается ответ успешного выполнения с маркером продолжения.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

Недвижимость	Описание
challenge_type	пароль возвращается в ответе на необходимые учетные данные.
continuation_token	токен Continuation, который возвращает Microsoft Entra.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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	Да	токен Continuation, который Microsoft Entra возвращен на предыдущем шаге.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.
grant_type	Да	Запрос к конечной точке /signup/v1.0/continue можно использовать для отправки однократного секретного кода, пароля или атрибутов пользователя. В этом случае grant_type значение используется для различения этих трех вариантов использования. Возможные значения для grant_type : oob, password, attributes. В этом вызове, так как мы отправляем пароль пользователя, значение, как ожидается, будет паролем.
password	Да	Значение пароля, которое приложение собирает от пользователя клиента. Замените {secure_password} значением пароля, которое приложение собирает от пользователя клиента. Вы несете ответственность за подтверждение того, что пользователь знает пароль, который он хочет использовать, предоставив поле подтверждения пароля в пользовательском интерфейсе приложения. Кроме того, необходимо убедиться, что пользователь знает о том, что представляет собой надежный пароль для политики вашей организации. Learn больше о политиках паролей Microsoft Entra.

Ответ успешного выполнения

Если запрос выполнен успешно, но атрибуты не были настроены в центре администрирования Microsoft Entra или все необходимые атрибуты были отправлены через конечную точку /signup/v1.0/start, приложение получает маркер продолжения без отправки каких-либо атрибутов. Приложение может использовать маркер продолжения для запроса маркеров безопасности, как показано в запросе маркеров безопасности. В противном случае ответ Microsoft Entra указывает, что приложению необходимо отправить необходимые атрибуты. Эти атрибуты, встроенные или настраиваемые, были настроены в центре администрирования Microsoft Entra администратором клиента.

Обязательные атрибуты пользователя

Этот ответ запрашивает приложение отправлять значения для атрибутов имени, возраста и телефона .

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	токен Continuation, который возвращает Microsoft Entra.
required_attributes	Список (массив объектов) атрибутов, которые приложение должно отправить следующий вызов, чтобы продолжить. Эти атрибуты являются дополнительными атрибутами, которые приложение должно отправлять отдельно от имени пользователя. Microsoft Entra включает этот параметр в ответ, если значение параметра error равно attributes_required.

Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например проверка маркераклиента является пустым или недопустимым.
invalid_grant	Тип предоставления, включенный в запрос, не является допустимым или поддерживаемым. Возможные значения для объектаgrant_type: oob, password, attributes
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.
attributes_required	Требуется один или несколько атрибутов пользователя.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например, если challenge_type параметр содержит недопустимый тип вызова.
invalid_grant	Предоставленный грант недопустим, например пароль, отправленный слишком коротким. suberror Используйте свойство, чтобы узнать о точной причине ошибки.
expired_token	Срок действия маркера продолжения истек.
attributes_required	Требуется один или несколько атрибутов пользователя.

Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства:

Значение подсервера	Описание
password_too_weak	Пароль слишком слаб, так как он не соответствует требованиям сложности. Learn больше о политиках паролей Microsoft Entra.
password_too_short	Новый пароль меньше 8 символов. Learn больше о политиках паролей Microsoft Entra.
password_too_long	Новый пароль превышает 256 символов. Learn больше о политиках паролей Microsoft Entra.
password_recently_used	Новый пароль не должен совпадать с недавно использованным паролем. Learn больше о политиках паролей Microsoft Entra.
password_banned	Новый пароль содержит слово, фразу или шаблон, который запрещен. Learn больше о политиках паролей Microsoft Entra.
password_is_invalid	Пароль недопустим, например, так как он использует запрещенные символы. Learn больше о политиках паролей 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}", "postalCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...

Параметр	Обязательное поле	Описание
tenant_subdomain	Да	Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте.
continuation_token	Да	токен Continuation, который 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}значения {user_age}{postal_code} имени, возраста и почтового кода соответственно, что приложение собирает от пользователя клиента. Microsoft Entra игнорирует все атрибуты, которые вы отправляете, которые не существуют.

Ответ успешного выполнения

Если запрос выполнен успешно, Microsoft Entra зарегистрироваться пользователем, а затем выдает маркер продолжения. Приложение может использовать маркер продолжения для запроса маркеров безопасности из конечной oauth/v2.0/token точки.

HTTP/1.1 200 OK
Content-Type: application/json

{  
    "continuation_token": "AQABAAEAAAYn..."
} 

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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	токен Continuation, который возвращает Microsoft Entra.
unverified_attributes	Список (массив объектов) имен ключей атрибутов, которые необходимо проверить. Этот параметр включается в ответ, если error значение параметра verification_required.
required_attributes	Список (массив объектов) атрибутов, которые приложение должно отправить. Microsoft Entra включает этот параметр в ответ, если значение параметра error равно attributes_required.
invalid_attributes	Список (массив объектов) атрибутов, которые не прошли проверку. Этот параметр включается в ответ, если suberror значение свойства attribute_validation_failed.
suberror	Строка кода ошибки, которую можно использовать для дальнейшего классификации типов ошибок.

Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например проверка маркераклиента является пустым или недопустимым.
invalid_grant	Указанный тип предоставления не является допустимым или не поддерживается или неудачной проверкой, например сбоем проверки атрибутов. suberror Используйте свойство, чтобы узнать о точной причине ошибки.
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.
attributes_required	Требуется один или несколько атрибутов пользователя.

Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства для ошибки invalid_grant :

Значение подсервера	Описание
attribute_validation_failed	Сбой проверки атрибута пользователя. invalid_attributes параметр содержит список (массив объектов) атрибутов, которые не прошли проверку.

Шаг 5. Автоматический вход после регистрации

Если пользователь должен автоматически войти после регистрации, приложение отправляет запрос POST к oauth/v2.0/token конечной точке и предоставляет маркер продолжения, полученный на предыдущем шаге для получения маркеров безопасности. Узнайте , как вызвать конечную точку токена.

Отправка атрибутов пользователя в конечные точки

В центре администрирования Microsoft Entra можно настроить атрибуты пользователей как обязательные или необязательные. Эта конфигурация определяет, как Microsoft Entra реагирует при вызове к конечным точкам. Необязательные атрибуты не являются обязательными для завершения потока регистрации. Таким образом, если все атрибуты являются необязательными, они должны быть отправлены перед проверкой имени пользователя. В противном случае регистрация завершается без необязательных атрибутов.

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

Конечная точка	Требуемые атрибуты	Необязательные атрибуты	Обязательные и необязательные атрибуты
/signup/v1.0/start конечная точка	Да	Да	Да
/signup/v1.0/continue конечная точка перед проверкой имени пользователя	Да	Да	Да
/signup/v1.0/continue конечная точка после проверки имени пользователя	Да	нет	Да

Формат значений атрибутов пользователя

Укажите сведения, которые нужно собрать от пользователя, настроив параметры потока пользователя в центре администрирования Microsoft Entra. Используйте настраиваемые атрибуты пользователя во время регистрации, чтобы узнать, как собирать значения для встроенных и пользовательских атрибутов.

Можно также указать тип ввода пользователя для настроенных атрибутов. В следующей таблице приведены сведения о поддерживаемых типах входных данных пользователей и способах отправки значений, собранных элементами управления пользовательского интерфейса в Microsoft Entra.

Тип ввода пользователя	Формат отправленных значений
Текстовое поле	Одно значение, например название задания, инженер программного обеспечения.
SingleRadioSelect	Одно значение, например язык, норвежский.
ФлажокMultiSelect	Одно или несколько значений, таких как хобби или хобби, танцы или танцы, плавание, путешествия.

Ниже приведен пример запроса, демонстрирующего отправку значений атрибутов:

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 проверки подлинности.

Например, Display Name в центре администрирования Microsoft Entra ссылается как displayName в API.

Используйте статью "Атрибуты профиля пользователя", чтобы узнать, как ссылаться на встроенные и пользовательские атрибуты пользователя в собственном API проверки подлинности.

Ссылка API для потока входа

Пользователям необходимо войти с помощью метода проверки подлинности, который они используют для регистрации. Например, пользователи, которые регистрывают электронную почту с помощью метода проверки подлинности паролей, должны входить в электронную почту и пароль.

Чтобы запросить маркеры безопасности, приложение взаимодействует с тремя конечными точками, oauth/v2.0/initiate, а oauth/v2.0/challengeoauth/v2.0/tokenтакже при необходимостиoauth/v2.0/introspect.

Конечные точки API для входа

Конечная точка	Описание
oauth/v2.0/initiate	Эта конечная точка инициирует поток входа. Если приложение вызывает его с именем пользователя учетной записи пользователя, которая уже существует, он возвращает ответ успешно с маркером продолжения. Если приложение запрашивает использование методов проверки подлинности, которые не поддерживаются Microsoft Entra, этот ответ конечной точки может указать приложению, что он должен использовать поток проверки подлинности на основе браузера.
oauth/v2.0/challenge	Приложение вызывает эту конечную точку, чтобы запросить Microsoft Entra выбрать один из поддерживаемых типов вызовов sign-in для проверки подлинности пользователя. Когда администратор клиента применяет MFA для пользователей клиента, приложение вызывает эту конечную точку для вызова пользователя для второго метода проверки подлинности.
oauth/v2.0/token	Эта конечная точка проверяет учетные данные пользователя, получаемые из приложения, а затем выдает маркеры безопасности приложению. Ответ от этой конечной точки также может указать, требуется ли пользователю выполнить вызов MFA или зарегистрировать надежный метод проверки подлинности.
oauth/v2.0/introspect	Приложение вызывает его, чтобы запросить список зарегистрированных методов строгой проверки подлинности для многофакторной проверки подлинности (MFA). Узнайте , как использовать конечную точку интроспекта

Типы проблем входа

API позволяет приложению объявлять поддерживаемые методы проверки подлинности при вызове Microsoft Entra. Для этого приложение использует challenge_type параметр в своих запросах. Этот параметр содержит предопределенные значения, представляющие различные методы проверки подлинности.

Для данного метода проверки подлинности значение типа вызова, которое приложение отправляет в Microsoft Entra во время регистрации, совпадает с тем, когда приложение войдет в систему. Например, электронная почта с методом проверки подлинности паролей использует значения типа oob, password и redirect challenge для потоков регистрации и входа.

Дополнительные сведения о типах вызовов в собственных типах вызовов проверки подлинности см. в статье.

Сведения о протоколе потока входа

Схема последовательности демонстрирует поток процесса входа. Поток входа зависит от метода проверки подлинности пользователя.

Отправка одноразового секретного кода по электронной почте

После проверки электронной почты пользователя с помощью OTP приложение получает маркеры безопасности. Если доставка однократного секретного кода или никогда не доставляется по электронной почте пользователя, пользователь может запросить отправку другого секретного кода. Microsoft Entra повторно отправляет другой одноразовый секретный код, если предыдущий не был проверен. Когда Microsoft Entra повторно отправляет одноразовый секретный код, он отменяет ранее отправленный код.

Электронная почта с

• На этой схеме указано, что приложение собирает имя пользователя (электронную почту) и пароль от пользователя в разное время (и, возможно, на отдельных экранах). Однако вы можете создать приложение для сбора двух значений на одном экране.
• Если вы собираете имя пользователя (электронная почта) и пароль на одном экране, шаги 2 и три объединяются с шагами восемь и девять. В этом случае приложение содержит пароль, а затем отправляет его на шаге десять , где это необходимо.

Если администратор клиента включает MFA для пользователей клиента, ответ от /oauth2/v2.0/token конечной точки зависит от того, имеет ли пользователь зарегистрированный метод строгой проверки подлинности:

• Если у пользователя зарегистрирован метод строгой проверки подлинности, он завершает поток вызовов MFA.
• Если у пользователя нет зарегистрированного метода строгой проверки подлинности, он завершает регистрацию для потока метода строгой проверки подлинности .

На этой схеме последовательности показан путь MFA. В нем рассматриваются оба случая: (1) пользователь уже имеет зарегистрированный метод строгой проверки подлинности или (2) у пользователя нет и должен зарегистрировать один JIT-код. Поток начинается после того, как приложение собрало правильный пароль от пользователя и вызывает /oauth2/v2.0/token, который затем отвечает, должен ли пользователь завершить MFA или зарегистрировать надежный метод проверки подлинности.

В следующих разделах мы сводим поток входа в три основных шага.

Шаг 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
&capabilities=registration_required mfa_required

Параметр	Обязательное поле	Описание
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 для электронной почты с паролем.
capabilities	нет	Разделенные пробелами флаги, описывающие готовность клиентского приложения. Хотя challenge_type определяет, какие методы можно оспаривать, сообщите собственному API проверки подлинности, capabilities какие дополнительные потоки клиентское приложение может обрабатывать и какие пользовательские интерфейсы он может отображать. Например, означает , что и цикл; mfa_required означает/introspect/challenge/token, registration_required что клиентское приложение вызывает API регистрации и отображает пользовательский интерфейс регистрации. Если необходимая возможность не включена клиентским приложением, API возвращает перенаправление. Поддерживаемые значения: mfa_required и registration_required. Дополнительные сведения о возможностях.

Ответ успешного выполнения

Ниже приведен пример успешного ответа:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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 свойства):

Значение ошибки	Описание
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 :

Значение подсервера	Описание
nativeauthapi_disabled	Идентификатор клиента для приложения, которое не включается для собственной проверки подлинности.

Шаг 2. Выбор метода проверки подлинности

Чтобы продолжить поток, приложение использует маркер продолжения, полученный на предыдущем шаге, чтобы запросить Microsoft Entra выбрать один из поддерживаемых типов вызовов для пользователя для проверки подлинности или выполнения задачи MFA. Приложение отправляет запрос POST к конечной точке /oauth2/v2.0/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	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе. Предыдущий запрос вызывает /oauth2/v2.0/initiate конечную точку или /oauth2/v2.0/introspect конечную точку, если пользователь завершает вызов MFA.
challenge_type	нет	Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, oob password redirectнапример. Список должен всегда включать redirect тип вызова. Ожидается, что значение будет oob redirect отправлено для однократного секретного кода электронной почты и password redirect для электронной почты с паролем.
id	нет	Строковый идентификатор метода строгой проверки подлинности, возвращаемого из конечной /oauth2/v2.0/introspect точки. Этот параметр требуется, если клиентское приложение вызовет пользователю второй фактор проверки подлинности. Узнайте , как использовать конечную точку интроспекта.

Ответ успешного выполнения

Ответ успешного выполнения зависит от метода проверки подлинности пользователя.

Отправка одноразового секретного кода по электронной почте

Если администратор клиента настроит одноразовый секретный код электронной почты в центре администрирования 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	токен Continuation, который возвращает Microsoft Entra.
challenge_type	Тип вызова, выбранный для проверки подлинности пользователя.
binding_method	Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob
challenge_channel	Тип канала, через который был отправлен одноразовый секретный код. На данный момент мы поддерживаем электронную почту.
challenge_target_label	Замаскированное сообщение электронной почты, в котором был отправлен одноразовый секретный код.
code_length	Длина однократного секретного кода, который Microsoft Entra генерируется.

Электронная почта с

Если администратор клиента настроит сообщение электронной почты с паролем в центре администрирования Microsoft Entra в качестве метода проверки подлинности пользователя, ответ зависит от того, будет ли запрос на конечную точку /oauth2/v2.0/challenge выбрать метод проверки подлинности пользователя или выполнить задачу MFA.

Ответ, если запрос — выбрать метод проверки подлинности

Если запрос к конечной точке /oauth2/v2.0/challenge заключается в выборе метода проверки подлинности пользователя с помощью (первой проверки подлинности), Microsoft Entra возвращает ответ успешного выполнения, который включает тип вызова password.

Пример:

HTTP/1.1 200 OK
Content-Type: application/json

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.
challenge_type	Microsoft Entra возвращает поддерживаемый тип вызова, настроенный для пользователя в центре администрирования Microsoft Entra. В этом случае значения, как ожидается, будут паролем.

Ответ, если запрос требуется выполнить задачу MFA

Если запрос к конечной точке /oauth2/v2.0/challenge требуется выполнить задачу MFA (вторая проверка подлинности), Microsoft Entra отправляет одноразовый секретный код в выбранный канал вызовов MFA пользователя и предоставляет дополнительные сведения об однократном секретном коде.

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	токен Continuation, который возвращает Microsoft Entra.
challenge_type	Тип проблемы, выбранный для завершения MFA пользователя.
binding_method	Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob
challenge_channel	Тип канала вызовов MFA, через который был отправлен одноразовый секретный код. Поддерживаемые значения: электронная почта, sms.
challenge_target_label	Замаскированное сообщение электронной почты, в котором был отправлен одноразовый секретный код.
code_length	Длина однократного секретного кода, который Microsoft Entra генерируется.

Ответ перенаправления

В следующих сценариях может потребоваться возврат к потоку веб-проверки подлинности.

• Клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуются.
• Пользователь пытается использовать SMS в качестве строгого метода проверки подлинности, но защита от мошенничества блокирует запрос, если он считает его высоким риском (только в электронной почте с проверкой подлинности паролем).

В этих сценариях Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например, если challenge_type параметр содержит недопустимый тип вызова.
invalid_grant	Маркер продолжения, включенный в запрос, недействителен.
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.
unsupported_challenge_type	Значение challenge_type параметра не включает redirect тип вызова.

Шаг 3. Запрос маркеров безопасности

Приложение отправляет запрос POST к конечной oauth2/v2.0/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	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.
grant_type	Да	Тип гранта. При вызове конечной точки маркера это значение должно быть: - пароль для электронной почты с помощью метода проверки подлинности паролей в потоке входа, чтобы проверить первую проверку подлинности пользователя. - OOB для метода проверки подлинности однократного секретного кода электронной почты в потоке входа. - continuation_token для автоматического входа после потока регистрации. - continuation_token для автоматического входа после самостоятельного сброса пароля. - continuation_token после потока регистрации метода строгой проверки подлинности. - mfa_oob при проверке второй проверки подлинности пользователя.
scope	Да	Список областей с разделителями-пробелами. Все области должны быть из одного ресурса, а также областей OpenID Connect (OIDC), таких как профиль, openid и электронная почта. Приложению необходимо включить область openid для Microsoft Entra выдачи маркера идентификатора. Приложение должно включать область offline_access для Microsoft Entra выдачи маркера обновления. Дополнительные сведения о разрешениях и согласиях см. в платформа удостоверений Майкрософт.
password	нет	Значение пароля, которое приложение собирает от пользователя. Замените {secure_password} значением пароля, которое приложение собирает от пользователя. Этот параметр требуется, если метод проверки подлинности является адресом электронной почты с паролем.
oob	нет	Одноразовый секретный код, который пользователь получает по электронной почте. Требуется, если: — основной метод проверки подлинности — это одноразовый секретный код электронной почты. — Приложение отправляет одноразовый секретный код электронной почты для удовлетворения проблемы MFA, когда основной метод проверки подлинности является адресом электронной почты с паролем. Чтобы повторно отправить одноразовый секретный код, снова вызовите конечную точку /challenge .
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..."
}

Недвижимость	Описание
token_type	Указывает значение типа маркера. Единственным типом, поддерживаемым Microsoft Entra, является Bearer.
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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса. Чтобы понять, что произошло, используйте сообщение в описании ошибки.
invalid_grant	Маркер продолжения, включенный в запрос, недействителен, учетные данные входа пользователя, включенные в запрос, недопустимы, дальнейшие действия, необходимые для пользователя, или тип предоставления, включенный в запрос, неизвестен.
invalid_client	Идентификатор клиента, включенный в запрос, не является общедоступным клиентом.
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.
invalid_scope	Одна или несколько областей, включенных в запрос, недопустимы.
unauthorized_client	Идентификатор клиента, включенный в запрос, является недопустимым или не существует.
unsupported_grant_type	Тип предоставления, включенный в запрос, не поддерживается или является неверным.

Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства для ошибки invalid_grant :

Значение подсервера	Описание
invalid_oob_value	Значение однократного секретного кода, которое отправляет приложение, является недопустимым.
mfa_required	Требуется MFA. Ответ включает маркер продолжения. Вызовите конечную точку oauth2/v2.0/introspect , чтобы получить зарегистрированные методы строгой проверки подлинности пользователя. Этот вложенный объект возникает только в том случае, если основной метод проверки подлинности пользователя является адресом электронной почты с паролем. Узнайте, как получить зарегистрированные методы строгой проверки подлинности пользователя. Примечание. В некоторых случаях требуется многофакторная проверка подлинности, но встроенная проверка подлинности не возвращается mfa_required. или пример, если поток регистрации метода строгой проверки подлинности предшествует вызову /oauth2/v2.0/token и уже был проверен единственный доступный метод (электронная почта) во время этого потока.
registration_required	Пользователь должен выполнить задачу многофакторной проверки подлинности, но не имеет зарегистрированного метода строгой проверки подлинности. Предложите пользователю зарегистрировать его. Эта ошибка возникает, когда основной метод проверки подлинности пользователя является адресом электронной почты с паролем. Узнайте, как зарегистрировать надежный метод проверки подлинности.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможность, которая Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

HTTP/1.1 200 OK
Content-Type: application/json

{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
} 

Недвижимость	Описание
challenge_type	Microsoft Entra возвращает ответ, имеющий тип вызова. Значение этого типа вызова — перенаправление, которое позволяет приложению использовать поток проверки подлинности на основе веб-сайта.
redirect_reason	Причина, по которой требуется перенаправление. Например, Microsoft Entra обнаруживает, что требуется MFA или регистрация для метода строгой проверки подлинности, но приложение не включало эти возможности в запрос.

Этот ответ считается успешным, но приложение необходимо переключиться на поток проверки подлинности на основе веб-сайта. В этом случае рекомендуется использовать встроенную и поддерживаемую корпорацией Майкрософт библиотеку проверки подлинности.

Получение зарегистрированных пользователем методов строгой проверки подлинности

Используйте конечную точку oauth2/v2.0/introspect для запроса списка зарегистрированных методов строгой проверки подлинности пользователя.

Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444

Параметр	Обязательное поле	Описание
tenant_subdomain	Да	Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.
continuation_token	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.

Ответ успешного выполнения

Пример:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {   
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",   
          "challenge_type": "oob",   
          "challenge_channel": "sms",   
          "login_hint": "+1********6"
        }
    ]
}

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.
methods	Список (объектов) зарегистрированных пользователем методов строгой проверки подлинности.

Объект метода MFA имеет следующие свойства:

Недвижимость	Описание
id	Автоматически созданный уникальный идентификатор строки для метода MFA. Приложение использует эту строку, как id при вызове конечной /oauth2/v2.0/challenge точки.
challenge_type	Тип вызова, выбранный для пользователя, который используется в качестве метода MFA. Текущий поддерживаемый тип вызова — oob.
challenge_channel	Тип канала, в который отправляется метод MFA. Текущий поддерживаемый канал вызовов — это электронная почта.
login_hint	Указание для метода строгой проверки подлинности, например запутаемого сообщения электронной почты.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

HTTP/1.1 200 OK
Content-Type: application/json

{     
   "challenge_type": "redirect" 
} 

Отклик в случае ошибки

Пример:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса. Чтобы понять, что произошло, используйте сообщение в описании ошибки.
invalid_client	Идентификатор клиента, включенный в запрос, не является общедоступным клиентом.
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.
server_error	Что-то пошло не так с запросом.

После успешного получения клиентского приложения списка надежных методов проверки подлинности, зарегистрированных для пользователя, пользователь выбирает метод, который он хочет использовать для выполнения задачи MFA. Затем поток продолжается следующим образом:

1. Клиентское приложение вызывает и /oauth2/v2.0/challenge включает маркер продолжения, полученный из /oauth2/v2.0/introspectid выбранного метода MFA:

   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
   &id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c 
   &continuation_token=uY29tL2F1dGhlbnRpY... 
   

2. Microsoft Entra отправляет код запроса в канал вызовов пользователя, например электронную почту, а затем отвечает на клиентское приложение с маркером продолжения и сведениями о вызове MFA:

   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
   } 
   

3. Теперь приложение может отправить запрос POST к /oauth2/v2.0/token конечной точке и включить маркер продолжения, правильный тип предоставления и соответствующие значения типов предоставления для получения маркеров безопасности. См. ожидаемый ответ в запросе маркеров безопасности:

   POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
   Content-Type: application/x-www-form-urlencoded    
   client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
   &continuation_token=uY29tL2F1dGhlbnRpY...   
   &grant_type=mfa_oob  
   &oob={otp_code}
   &scope=openid offline_access
   

Регистрация справочника по API метода строгой проверки подлинности

Встроенная проверка подлинности поддерживает регистрацию метода строгой проверки подлинности. Когда приложение вызывает конечную точку /oauth2/v2.0/token и MFA, но у пользователя нет зарегистрированного строгого метода, ответ registeration_required сообщает приложению, что пользователь регистрирует его перед выдачой маркеров.

После завершения потока клиентского приложения для регистрации метода строгой проверки подлинности он вызывает /oauth2/v2.0/token конечную точку для запроса маркеров безопасности.

Конечные точки регистрации методов строгой проверки подлинности

Чтобы использовать API регистрации метода строгой проверки подлинности, приложение использует конечную точку, показанную в следующей таблице:

Конечная точка	Описание
/register/v1.0/introspect	Вызовите эту конечную точку, чтобы получить список методов строгой проверки подлинности, которые пользователь может зарегистрировать.
/register/v1.0/challenge	Вызовите эту конечную точку, чтобы отправить пользователю запрос, например одноразовый секретный код электронной почты.
/register/v1.0/continue	Вызовите эту конечную точку, чтобы отправить запрос, который приложение собирает от пользователя, например одноразовый секретный код, чтобы завершить поток для регистрации надежного метода проверки подлинности. После успешного вызова и получения маркера продолжения вызовите /oauth2/v2.0/token конечную точку конечной точки, чтобы запросить маркеры безопасности. Узнайте, как вызвать конечную точку токена.

Шаг 1. Получение списка надежных методов проверки подлинности

Поток регистрации начинается, когда приложение запрашивает список надежных методов проверки подлинности, пользователь может зарегистрировать.

Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  

Параметр	Обязательное поле	Описание
tenant_subdomain	Да	Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.

Ответ успешного выполнения

Ниже приведен пример успешного ответа:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {   
          "id": "sms",   
          "challenge_type": "oob",   
          "challenge_channel": "sms"
        }
    ]
}

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.
methods	Список (объектов) надежных методов проверки подлинности, доступных пользователю для регистрации.

Объект надежных методов проверки подлинности имеет следующие свойства:

Недвижимость	Описание
id	Строковый ключ метода. Поддерживаемые значения электронной почты, sms.
challenge_type	Тип вызова, выбранный для пользователя, который используется в качестве метода MFA. Текущий поддерживаемый тип вызова — oob.
challenge_channel	Тип канала, в который отправляется метод MFA. Поддерживаемые значения электронной почты, sms.
login_hint	Указание для метода строгой проверки подлинности, например электронной почты. Это значение используется клиентским приложением для предварительного заполнения текстового поля электронной почты.

Отклик в случае ошибки

Пример:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{ 
    "error": "invalid_request", 
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например проверка маркераклиента является пустым или недопустимым, или внешний администратор клиента не включил сообщение OTP для всех пользователей клиента.
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.

Шаг 2. Выбор метода строгой проверки подлинности

На этом шаге отправьте метод строгой проверки подлинности, который пользователь хочет зарегистрировать. Microsoft Entra затем отправляет пользователю запрос, например одноразовый секретный код электронной почты.

Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge 

?continuation_token=uY29tL2F1dGhlbnRpY... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444  
&challenge_type=oob  
&challenge_channel=email 
&challenge_target=contoso-consumer@contoso.com 

Параметр	Обязательное поле	Описание
tenant_subdomain	Да	Поддомен созданного внешнего клиента. В URL-адресе замените {tenant_subdomain} поддомен каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет поддомена клиента, узнайте, как считывать сведения о клиенте.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.
continuation_token	Да	Маркер Continuation, который Microsoft Entra возвращается из конечной точки /register/v1.0/introspect
challenge_type	Да	Тип вызова метода проверки подлинности. Текущий тип — oob.
challenge_target	Да	Адрес электронной почты или номер телефона, который пользователь хочет зарегистрировать.
challenge_channel	нет	Канал для отправки задачи. Поддерживаемые значения канала вызовов: электронная почта, sms.

Ответ успешного выполнения

Ниже приведен пример успешного ответа.

Пример 1:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...", 
  "challenge_type": "oob", 
  "binding_method": "prompt", 
  "challenge_target": "contoso-consumer@contoso.com", 
  "challenge_channel": "email", 
  "code_length": 8 
} 

Пример 2:

Если поток регистрации предшествует потоку регистрации надежных методов проверки подлинности, а сообщение электронной почты, отправленное /register/v1.0/challenge в конечную точку, соответствует одному из проверенных в потоке регистрации, собственный API проверки подлинности регистрирует метод без отправки запроса пользователю. В этом случае ответ будет выглядеть следующим фрагментом кода:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified" 
}

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.
challenge_type	Тип вызова, выбранный для проверки подлинности пользователя, например oob, или предварительно оповещен , если надежный метод проверки подлинности будет предварительно проверен.
binding_method	Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления пользователю дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob и метод строгой проверки подлинности не является предварительной.
challenge_channel	Тип канала, через который был отправлен одноразовый секретный код. Поддерживаемые значения электронной почты, sms. Возвращается, если надежный метод проверки подлинности не является предварительно подготовленным.
code_length	Длина однократного секретного кода при binding_method появлении запроса. Возвращается, если надежный метод проверки подлинности не является предварительно подготовленным.
challenge_target	Цель, в который была отправлена задача. Это то же самое, что и входные данные, предоставленные в запросе. Возвращается, если надежный метод проверки подлинности не является предварительно подготовленным.
interval	Интервал (в секундах) клиент должен ожидать опроса /register/continue. Возвращается только в том случае, если prompt=none и метод строгой проверки подлинности не является предварительной. Клиенты должны удвоить интервал каждый раз, когда они получают HTTP 429 от собственного API проверки подлинности.

Отклик в случае ошибки

Ниже приведены ошибки, аналогичные тем, которые могут возникнуть при вызове конечной /register/v1.0/introspect точки. Однако при регистрации номера телефона, если номер телефона считается высоким риском, запрос может быть заблокирован.

Ниже приведены возможные ошибки, которые можно столкнуться, если запрос заблокирован:

Значение ошибки	Описание
access_denied	SMS заблокирован.

Если параметр ошибки имеет значение access_denied, Microsoft Entra включает в ответ свойство подсервера. Ниже приведены возможные значения свойства подсервера для ошибки invalid_grant:

Значение подсервера	Описание
provider_blocked_by_admin	Администратор клиента заблокировал телефонный регион.
provider_blocked_by_rep	Метод многофакторной проверки подлинности заблокирован (номер телефона был заблокирован RepMap).

Шаг 3. Отправка запроса

На этом шаге выполните вызов конечной /register/v1.0/continue точки для завершения регистрации метода строгой проверки подлинности.

Ниже приведен пример запроса (мы представляем пример запроса в нескольких строках для удобства чтения):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue 

?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	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.
grant_type	Да	Тип гранта. Текущее поддерживаемое значение — oob или continuation_token , если метод строгой проверки подлинности будет предварительно оповещен в конечной точке /register/v1.0/challenge .
oob	нет	Одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Замените {otp_code} значения одноразового секретного кода, полученные пользователем в сообщении электронной почты. Чтобы повторно отправить одноразовый секретный код, приложение должно снова запросить /register/v1.0/challenge конечную точку. Требуется, если метод строгой проверки подлинности не предварительно указан в конечной точке /register/v1.0/challenge .

Ответ успешного выполнения

Ниже приведен пример успешного ответа:

HTTP/1.1 200 OK
Content-Type: application/json

{ 
  "continuation_token": "uY29tL2F1dGhlbnRpY..."
} 

Недвижимость	Описание
continuation_token	Маркер continuation, который возвращает Microsoft Entra. Используйте этот маркер продолжения для вызова конечной /oauth2/v2.0/token точки для запроса маркеров безопасности. Узнайте , как вызвать конечную точку токена.

Отклик в случае ошибки

Пример:

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	Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов.

Ниже приведены возможные ошибки, которые можно столкнуться (возможные значения error свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например проверка маркераклиента является пустым или недопустимым, или внешний администратор клиента не включил сообщение OTP для всех пользователей клиента.
invalid_grant	Тип предоставления, включенный в запрос, не является допустимым или поддерживаемым, или значение OTP неверно.
expired_token	Срок действия маркера продолжения, включенного в запрос, истекает.

Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства для ошибки invalid_grant :

Значение подсервера	Описание
invalid_oob_value	Недопустимое значение однократного секретного кода.

Самостоятельный сброс пароля (SSPR)

Для пользователей, основной метод проверки подлинности которых — это электронная почта с паролем, используйте API самостоятельного сброса пароля (SSPR), чтобы пользователи клиентов могли сбросить свой пароль. Этот API можно использовать для забыли пароль или изменить сценарии паролей.

Конечные точки API для самообслуживания сброса пароля

Чтобы использовать этот API, приложение использует конечную точку, показанную в следующей таблице:

Конечная точка	Описание
/resetpassword/v1.0/start	Ваше приложение вызывает эту конечную точку, когда пользователь выбирает пароль или кнопку "Изменить пароль" в приложении. Эта конечная точка проверяет имя пользователя (электронная почта), а затем возвращает маркер продолжения для использования в потоке сброса пароля. Если приложение запрашивает использование методов проверки подлинности, которые не поддерживаются Microsoft Entra, этот ответ конечной точки может указать приложению, что он должен использовать поток проверки подлинности на основе браузера.
/resetpassword/v1.0/challenge	Принимает список типов вызовов, поддерживаемых клиентом и маркером продолжения. Вызов выдается одному из предпочтительных учетных данных восстановления. Например, вызов oob выдает одноразовый секретный код для электронной почты, связанной с учетной записью пользователя клиента. Если приложение запрашивает использование методов проверки подлинности, которые не поддерживаются Microsoft Entra, этот ответ конечной точки может указать приложению, что он должен использовать поток проверки подлинности на основе браузера.
/resetpassword/v1.0/continue	Проверяет проблему, выданную конечной /resetpassword/v1.0/challenge точкой, а затем возвращает маркер продолжения для /resetpassword/v1.0/submit конечной точки или выдает другой вызов пользователю.
/resetpassword/v1.0/submit	Принимает новый ввод пароля пользователем вместе с маркером продолжения для завершения потока сброса пароля. Эта конечная точка выдает еще один маркер продолжения.
/resetpassword/v1.0/poll_completion	Приложение может использовать маркер продолжения , выданный /resetpassword/v1.0/submit конечной точкой, чтобы проверить состояние запроса сброса пароля.
oauth2/v2.0/token	Если сброс пароля выполнен успешно, приложение может использовать маркер продолжения, полученный из конечной /resetpassword/v1.0/poll_completion точки, чтобы получить маркеры безопасности из конечной oauth2/v2.0/token точки.

Типы вызовов самостоятельного сброса пароля

API позволяет приложению объявлять поддерживаемые методы проверки подлинности при вызове Microsoft Entra. Для этого приложение использует challenge_type параметр в своих запросах. Этот параметр содержит предопределенные значения, представляющие различные методы проверки подлинности.

Для потока SSPR значения типов вызовов — oob и перенаправление.

Дополнительные сведения о типах вызовов в собственных типах вызовов проверки подлинности.

Сведения о протоколе потока самостоятельного сброса пароля

Схема последовательности демонстрирует поток для процесса сброса пароля.

На этой схеме указано, что приложение собирает имя пользователя (электронную почту) и пароль от пользователя в разное время (и, возможно, на отдельных экранах). Однако вы можете создать приложение для сбора имени пользователя (электронной почты) и нового пароля на одном экране. В этом случае приложение содержит пароль, а затем отправляет его через /resetpassword/v1.0/submit конечную точку, где это необходимо.

Шаг 1. Запрос на запуск потока самостоятельного сброса пароля

Поток сброса пароля начинается с приложения, выполняющего запрос POST к /resetpassword/v1.0/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.
capabilities	нет	Разделенные пробелами флаги, описывающие готовность клиентского приложения. Хотя challenge_type определяет, какие методы можно оспаривать, сообщите собственному API проверки подлинности, capabilities какие дополнительные потоки клиентское приложение может обрабатывать и какие пользовательские интерфейсы он может отображать. Например, означает другой mfa_required и /challenge цикл; /token означает, registration_required что клиентское приложение вызывает API регистрации и отображает пользовательский интерфейс регистрации. Если требуемая возможность не объявляется клиентским приложением, API возвращает перенаправление. Поддерживаемые значения: mfa_required и registration_required. Дополнительные сведения о возможностях.

Ответ успешного выполнения

Пример:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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 свойства):

Значение ошибки	Описание
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 :

Значение подсервера	Описание
nativeauthapi_disabled	Идентификатор клиента для приложения, которое не включено для собственной проверки подлинности.

Шаг 2. Выбор метода проверки подлинности

Чтобы продолжить работу с потоком, приложение использует маркер продолжения, полученный на предыдущем шаге, чтобы запросить Microsoft Entra выбрать один из поддерживаемых типов вызовов для пользователя для проверки подлинности. Приложение отправляет запрос POST к конечной точке /resetpassword/v1.0/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=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	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.
challenge_type	нет	Разделенный пробелами список строк типа вызова авторизации, поддерживаемых приложением, 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	токен Continuation, который возвращает Microsoft Entra.
challenge_type	Тип вызова, выбранный для проверки подлинности пользователя.
binding_method	Единственное допустимое значение — запрос. Этот параметр можно использовать в будущем для предоставления пользователю дополнительных способов ввода однократного секретного кода. Выдано, если challenge_type является oob
challenge_channel	Тип канала, через который был отправлен одноразовый секретный код. На данный момент мы поддерживаем электронную почту.
challenge_target_label	Замаскированное сообщение электронной почты, в котором был отправлен одноразовый секретный код. Если для пользователя включена многофакторная проверка подлинности, сообщение электронной почты, содержащее одноразовый секретный код, отправляется в следующее: — адрес электронной почты, используемый в качестве метода строгой проверки подлинности, если адрес электронной почты отличается от адреса электронной почты учетной записи. — адрес электронной почты учетной записи, если метод строгой проверки подлинности — SMS.
code_length	Длина однократного секретного кода, который Microsoft Entra генерируется.

Ответ перенаправления

Если клиентское приложение не поддерживает метод проверки подлинности или возможности, которые Microsoft Entra требуется, необходимо вернуться к потоку проверки подлинности на основе веб-сайта. В этом сценарии Microsoft Entra сообщает приложению, возвращая тип вызова redirect в ответе:

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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например, если challenge_type параметр включает недопустимый тип вызова или проверку маркера продолжения не удалось.
expired_token	Срок действия маркера продолжения истек.
unsupported_challenge_type	Значение challenge_type параметра не включает redirect тип вызова.

Шаг 3. Отправка однократного секретного кода

Затем приложение отправляет запрос POST к конечной точке /resetpassword/v1.0/continue . В запросе приложение должно включить учетные данные пользователя, выбранные на предыдущем шаге, и маркер продолжения, выданный конечной /resetpassword/v1.0/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	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.
grant_type	Да	Единственное допустимое значение — oob.
oob	Да	Одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Замените {otp_code} одноразовый секретный код, полученный пользователем клиента в сообщении электронной почты. Чтобы повторно отправить одноразовый секретный код, приложение должно снова запросить /resetpassword/v1.0/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	токен Continuation, который возвращает 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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например проверка маркераклиента является пустым или недопустимым, или внешний администратор клиента не включил SSPR и электронную почту OTP для всех пользователей клиента. error_description Используйте параметр, чтобы узнать о точной причине ошибки.
invalid_grant	Тип гранта неизвестен или не соответствует ожидаемому значению типа гранта. suberror Используйте свойство, чтобы узнать о точной причине ошибки.
expired_token	Срок действия маркера продолжения истек.

Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства для ошибки invalid_grant :

Значение подсервера	Описание
invalid_oob_value	Недопустимое значение однократного секретного кода.

Шаг 4. Отправка нового пароля

Приложение собирает новый пароль от пользователя, а затем использует маркер продолжения, выданный /resetpassword/v1.0/continue конечной точкой, чтобы отправить пароль, выполнив запрос POST к конечной точке /resetpassword/v1.0/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	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.
new_password	Да	Новый пароль пользователя. Замените {new_password} новым паролем пользователя. Вы несете ответственность за подтверждение того, что пользователь знает пароль, который он хочет использовать, предоставив поле подтверждения пароля в пользовательском интерфейсе приложения. Кроме того, необходимо убедиться, что пользователь знает о том, что представляет собой надежный пароль для политики вашей организации. Learn больше о политиках паролей Microsoft Entra.

Ответ успешного выполнения

Пример:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

Недвижимость	Описание
continuation_token	токен Continuation, который возвращает Microsoft Entra.
poll_interval	Минимальное время в секундах, которое приложение должно ожидать между запросами опроса, чтобы проверить состояние запроса сброса пароля через /resetpassword/v1.0/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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например проверка маркера продолжения завершилась ошибкой.
expired_token	Срок действия маркера продолжения истек.
invalid_grant	Предоставленный грант недопустим, например пароль, отправленный слишком коротким. suberror Используйте свойство, чтобы узнать о точной причине ошибки.

Если параметр ошибки имеет значение invalid_grant, Microsoft Entra включает свойство suberror в ответ. Ниже приведены возможные значения suberror свойства:

Значение подсервера	Описание
password_too_weak	Пароль слишком слаб, так как он не соответствует требованиям сложности. Learn больше о политиках паролей Microsoft Entra.
password_too_short	Новый пароль меньше 8 символов. Learn больше о политиках паролей Microsoft Entra.
password_too_long	Новый пароль превышает 256 символов. Learn больше о политиках паролей Microsoft Entra.
password_recently_used	Новый пароль не должен совпадать с недавно использованным паролем. Learn больше о политиках паролей Microsoft Entra.
password_banned	Новый пароль содержит слово, фразу или шаблон, который запрещен. Learn больше о политиках паролей Microsoft Entra.
password_is_invalid	Пароль недопустим, например, так как он использует запрещенные символы. Learn больше о политиках паролей Microsoft Entra. Этот ответ возможен, если приложение отправляет пароль пользователя.

Шаг 5. Опрос состояния сброса пароля

Наконец, так как обновление конфигурации пользователя с новым паролем вызывает некоторую задержку, приложение может использовать конечную точку /resetpassword/v1.0/poll_completion для опроса Microsoft Entra для состояния сброса пароля. Минимальное время в секундах, которое приложение должно ожидать между запросами опроса, возвращается из конечной /resetpassword/v1.0/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	Да	токен Continuation, который Microsoft Entra возвращен в предыдущем запросе.
client_id	Да	Идентификатор приложения (клиента), зарегистрированного в центре администрирования Microsoft Entra.

Ответ успешного выполнения

Пример:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

Недвижимость	Описание
status	Состояние запроса на сброс пароля. Если Microsoft Entra возвращает состояние failed, приложение может повторно отправить новый пароль, выполнив другой запрос к конечной точке /resetpassword/v1.0/submit и включить новый маркер продолжения.
continuation_token	токен Continuation, который возвращает Microsoft Entra. Если состояние сучилось, приложение может использовать маркер продолжения, который Microsoft Entra возвращается для запроса маркеров безопасности через конечную точку oauth2/v2.0/token, как описано в Request для маркеров безопасности. Это означает, что после успешного сброса пароля пользователь может напрямую войти в приложение, не инициируя новый поток входа.

Ниже приведены возможные состояния, которые возвращаются Microsoft Entra (возможные значения параметра status):

Значение ошибки	Описание
succeeded	Сброс пароля успешно завершен.
failed	Сбой сброса пароля. Приложение может повторно отправить новый пароль, выполнив другой запрос к конечной точке /resetpassword/v1.0/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 свойства):

Значение ошибки	Описание
invalid_request	Сбой проверки параметров запроса, например проверка маркера продолжения.
expired_token	Срок действия маркера продолжения истек.

Автоматический вход после сброса пароля

Если пользователь должен войти после успешного сброса пароля. Приложение должно вызвать конечную точку /oauth2/v2.0/token . Узнайте , как вызвать конечную точку токена.

Связанный контент

• Настройка пользовательского поставщика утверждений.