Потоки OpenID Connect или OAuth в AD FS и сценарии использования приложений

Применимо к AD FS 2019 и более поздним версиям

Сценарий	Пошаговое руководство по использованию сценария с примерами	Поток/предоставление разрешения OAuth 2.0	Тип клиента
Одностраничное приложение	Пример использования MSAL	Неявный	Общедоступный
Веб-приложение, которое обрабатывает вход пользователей в систему	Пример использования OWIN	Код авторизации	Общедоступный, конфиденциальный
Вызов веб-API в нативном приложении	Пример использования MSAL	Код авторизации	Общедоступный
Вызов веб-API в веб-приложении	Пример использования MSAL	Код авторизации	Конфиденциальная
Вызов веб-API в другом веб-API от имени пользователя	Пример использования MSAL	On-behalf-of	Веб-приложение в режиме "конфиденциально"
Вызов веб-API в управляющей программе		Учетные данные клиента	Конфиденциальная
Веб-приложение вызывает веб-API с помощью учетных данных пользователя		Учетные данные владельца ресурса с паролем	Общедоступный, конфиденциальный
Вызов веб-API в приложении без использования браузера		Код устройства	Общедоступный, конфиденциальный

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

Примечание.

Корпорация Майкрософт настоятельно рекомендует переход на идентификатор Microsoft Entra, а не обновление до более новой версии AD FS. Дополнительные сведения о неявном потоке предоставления в идентификаторе Microsoft Entra см. в разделе "Неявный поток предоставления" в платформа удостоверений Майкрософт.

Для одностраничных приложений (AngularJS, Ember.js, React.js и т. п.), AD FS поддерживает поток неявного предоставления OAuth 2.0. Подробное описание неявного потока данных см. в спецификации OAuth 2.0. Основное его преимущество заключается в том, что приложения могут получать маркеры от AD FS без обмена учетными данными с внутренним сервером. Этот поток позволяет приложению входить в систему пользователя, поддерживать сеанс и получать маркеры другим веб-API в клиентском коде JavaScript. При использовании неявного потока конкретно вокруг клиента следует учитывать несколько важных соображений безопасности.

Если вы хотите использовать неявный поток и AD FS для добавления проверки подлинности в приложение JavaScript, выполните общие действия, описанные в следующем разделе.

Схема протокола

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

Маркер идентификатора запроса и маркер доступа

Для первоначального входа пользователя в приложение можно отправить запрос на проверку подлинности OpenID Подключение и получить id_token и маркер доступа из конечной точки AD FS.

// Line breaks for legibility only

https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345

Параметр	Обязательно/Необязательно	Description
client_id	обязательно	Идентификатор приложения (клиента), назначенный приложению AD FS.
response_type	обязательно	Должен включать id_token для входа в OpenID Connect. Он также может включать response_typetoken. Использование маркера здесь позволяет приложению немедленно получать маркер доступа из конечной точки авторизации, не выполняя второй запрос к конечной точке маркера.
redirect_uri	обязательно	URI перенаправления приложения, на который можно отправлять ответы проверки подлинности для их получения приложением. Он должен точно соответствовать одному из URI перенаправления, настроенных в AD FS.
nonce	обязательно	Значение, включенное в запрос, созданное приложением, которое должно быть включено в итоговое id_token в качестве утверждения. Приложение может проверить это значение во избежание атак с использованием воспроизведения токена. Это значение обычно представляет собой случайную уникальную строку, которую можно использовать для определения источника запроса. Требуется только при запросе id_token.
область	необязательно	Список областей с разделителями-пробелами. Для входа через OpenID Connect этот параметр должен содержать областьopenid.
resource	необязательно	URL-адрес веб-API. Примечание. Если используется клиентская библиотека MSAL, параметр ресурса не отправляется. Вместо этого URL-адрес ресурса отправляется как часть параметра область: scope = [resource url]//[scope values e.g., openid] если ресурс не передается здесь или в область, AD FS использует urn:microsoft:userinfo по умолчанию. Политики ресурсов userinfo, такие как MFA, политика выдачи или авторизации, не могут быть настроены.
response_mode	необязательно	Указывает метод, с помощью которого результирующий маркер будет отправлен приложению. По умолчанию — fragment.
state	необязательно	Значение, включенное в запрос, который также должен быть возвращен в ответе маркера. Это может быть строка любого контента. Как правило, для предотвращения подделки межсайтовых запросовиспользуется генерируемое случайным образом уникальное значение. Параметр "state" также используется для кодирования информации о состоянии пользователя в приложении перед созданием запроса на проверку подлинности, например информации об открытой на тот момент странице или представлении.
prompt	необязательно	Указывает требуемый тип взаимодействия с пользователем. Единственными допустимыми значениями в настоящее время являются вход и нет. - prompt=login заставляет пользователя вводить свои учетные данные в этом запросе, отрицая единый вход. - prompt=none является противоположностью — это гарантирует, что пользователь не представлен интерактивным запросом в любом случае. Если запрос не может быть выполнен автоматически с помощью единого входа, AD FS возвращает ошибку interaction_required.
login_hint	необязательно	Можно применять для предварительного заполнения поля имени пользователя или адреса электронной почты на странице входа пользователя (если имя пользователя известно заранее). Часто приложения используют этот параметр во время повторной проверки подлинности, уже извлекая имя пользователя из предыдущего входа с помощью upn утверждения id_token.
domain_hint	необязательно	Если он включен, он пропускает процесс обнаружения на основе домена, который пользователь проходит на странице входа, что приводит к немного более упрощенной пользовательской среде.

На текущем этапе пользователю предлагается ввести учетные данные и завершить аутентификацию. После проверки подлинности пользователя конечная точка авторизации AD FS возвращает ответ приложению по указанному redirect_uri, используя метод, указанный в параметре response_mode.

Успешный ответ

Успешный ответ, который выглядит response_mode=fragment and response_type=id_token+token следующим образом.

// Line breaks for legibility only

GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345

Параметр	Описание
access_token;	Включен, если response_type включает token.
token_type	Включен, если response_type включает token. всегда имеет значение "Носитель".
expires_in	Включен, если response_type включает token. Указывает количество секунд, в течение которых маркер остается допустимым (для кэширования).
область	Указывает область, для которых действительна access_token.
id_token	Включен, если response_type включает id_token. Подписанный JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или обеспечения безопасности.
state	Если запрос содержит параметр "state", в ответе должно отображаться то же значение. Приложение должно убедиться, что значения параметра state в запросе и отклике идентичны.

маркеры обновления.

Неявное предоставление не предоставляет маркеры обновления. access_tokens Срок id_tokens действия и срок действия истекает через короткий период времени, поэтому приложение должно периодически обновлять эти маркеры. Чтобы обновить любой тип маркера, можно выполнить тот же скрытый запрос iframe в предыдущем разделе с помощью prompt=none параметра для управления поведением платформы удостоверений. Если вы хотите получить new id_token, обязательно используйтеresponse_type=id_token.

Поток предоставления кода авторизации

Примечание.

Корпорация Майкрософт настоятельно рекомендует переход на идентификатор Microsoft Entra, а не обновление до более новой версии AD FS. Дополнительные сведения о потоке предоставления кода авторизации в идентификаторе Microsoft Entra см. в платформа удостоверений Майкрософт потоке предоставления кода авторизации.

Предоставление кода авторизации в OAuth 2.0 можно использовать в веб-приложениях для получения доступа к защищенным ресурсам, таким как веб-API. Описание потока кода авторизации OAuth 2.0 см. в разделе 4.1 спецификации OAuth 2.0. Он используется для выполнения проверки подлинности и авторизации в большинстве типов приложений, включая веб-приложения и собственные установленные приложения. Поток позволяет приложениям безопасно получать access_tokens, которые можно использовать для доступа к ресурсам, которым доверяет AD FS.

Схема протокола

На обобщенном уровне поток проверки подлинности для нативного приложения выглядит примерно так:

Запрос кода авторизации

Поток кода авторизации начинается с клиента, направляющего пользователя в конечную точку /authorization. В этом запросе клиент указывает разрешения, которые ему требуется получить от пользователя:

// Line breaks for legibility only

https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345

Параметр	Обязательно/Необязательно	Description
client_id	обязательно	Идентификатор приложения (клиента), назначенный приложению AD FS.
response_type	обязательно	Должен включать код для потока кода авторизации.
redirect_uri	обязательно	redirect_uri для приложения, по которому оно может отправлять и получать ответы на запросы проверки подлинности. Он должен точно соответствовать одному из URI перенаправления, зарегистрированных для соответствующего клиента в AD FS.
resource	необязательно	URL-адрес веб-API. Примечание. Если используется клиентская библиотека MSAL, параметр ресурса не отправляется. Вместо этого URL-адрес ресурса отправляется как часть параметра область: scope = [resource url]//[scope values e.g., openid] если ресурс не передается здесь или в область, AD FS использует urn:microsoft:userinfo по умолчанию. Политики ресурсов userinfo, такие как MFA, политика выдачи или авторизации, не могут быть настроены.
область	необязательно	Список областей с разделителями-пробелами.
response_mode	необязательно	Указывает метод, с помощью которого результирующий маркер будет отправлен приложению. Может быть одним из следующих методов: запрос - фрагмент - form_postquery предоставляет код в качестве параметра строки запроса в URI перенаправления. Если вы запрашиваете код, можно использовать запрос, фрагмент или form_post. form_post выполняет запрос POST, который содержит код для URI перенаправления.
state	необязательно	Значение, включенное в запрос, который также должен быть возвращен в ответе маркера. Это может быть строка любого контента. Как правило, для предотвращения подделки межсайтовых запросовиспользуется генерируемое случайным образом уникальное значение. Также в этом значении кодируются сведения о состоянии пользователя в приложении перед выполнением запроса на аутентификацию. Например, это могут быть сведения об открытой на тот момент странице или представлении.
prompt	необязательно	Указывает требуемый тип взаимодействия с пользователем. Единственными допустимыми значениями в настоящее время являются вход и нет. - prompt=login заставляет пользователя вводить свои учетные данные в этом запросе, отрицая единый вход. - prompt=none является противоположностью — это гарантирует, что пользователь не представлен интерактивным запросом в любом случае. Если запрос не может быть выполнен автоматически с помощью единого входа, AD FS возвращает ошибку interaction_required.
login_hint	необязательно	Можно применять для предварительного заполнения поля имени пользователя или адреса электронной почты на странице входа пользователя (если имя пользователя известно заранее). Часто приложения используют этот параметр во время повторной проверки подлинности, уже извлекая имя пользователя из предыдущего входа с помощью upnутверждения id_token.
domain_hint	необязательно	Если он включен, он пропускает процесс обнаружения на основе домена, который пользователь проходит на странице входа, что приводит к немного более упрощенной пользовательской среде.
code_challenge_method	необязательно	Метод, используемый для кодирования code_verifier для параметра code_challenge. Может быть одним из следующих значений: — обычный — S256 При исключении, code_challenge предполагается, что он является открытым, если code_challenge включен. AD FS поддерживает как обычные, так и S256. Дополнительные сведения см. в описании PKCE RFC.
code_challenge	необязательно	Используется, чтобы защитить разрешения кода авторизации из собственного клиента при помощи ключа проверки для обмена кодом (PKCE). Является обязательным, если указан параметр code_challenge_method. Дополнительные сведения см. в описании PKCE RFC.

На текущем этапе пользователю предлагается ввести учетные данные и завершить аутентификацию. После проверки подлинности пользователя AD FS возвращает ответ на указанное приложение redirect_uri, используя метод, указанный в параметре response_mode .

Успешный ответ

Успешный ответ с помощью response_mode=query выглядит следующим образом:

GET https://adfs.contoso.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345

Параметр	Описание
кодом	Маркер authorization_code , запрошенный приложением. Приложение может использовать код авторизации для запроса маркера доступа для целевого ресурса. Срок действия кодов авторизации очень мал и обычно истекает по прошествии порядка 10 минут.
state	Если запрос содержит параметр state, то в ответе должно отображаться то же значение. Приложение должно убедиться, что значения параметра state в запросе и отклике идентичны.

Запросите маркер доступа

Теперь, когда вы приобрели authorization_code и получили разрешение пользователя, вы можете активировать код для требуемого access_token ресурса. Активация кода путем отправки запроса POST в конечную точку /token:

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for confidential clients (web apps)

Параметр	Обязательный/необязательный	Description
client_id	обязательно	Идентификатор приложения (клиента), назначенный приложению AD FS.
grant_type	обязательно	Должен быть authorization_code для потока кода авторизации.
кодом	обязательно	Значение authorization_code, полученное в первой части потока.
redirect_uri	обязательно	То же значение redirect_uri, что использовалось для получения authorization_code.
client_secret	необходим для веб-приложений	Секрет приложения, который вы создали во время регистрации приложения в AD FS. Не следует использовать секрет приложения в нативном приложении, так как на устройствах нет возможности надежно хранить client_secrets. Этот секрет требуется для веб-приложений и веб-API с возможностью безопасного хранения секрета клиента на сервере. Секрет клиента должен быть преобразован в формат URL-адреса перед отправкой. Эти приложения также могут использовать проверку подлинности на основе ключей, подписывая JWT и добавляя его в виде параметра client_assertion.
code_verifier	необязательно	Тот же code_verifier, который использовался для получения authorization_code. Является обязательным, если в запросе на код авторизации использовался PKCE. Дополнительные сведения см. в описании PKCE RFC. Этот параметр применяется к AD FS 2019 и более поздним версиям

Успешный ответ

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

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Параметр	Описание
access_token;	Запрашиваемый маркер доступа. Приложение может использовать этот маркер для проверки подлинности при обращении к защищенному ресурсу (веб-API).
token_type	Указывает значение типа маркера. В AD FS поддерживается только один тип — Bearer (носитель).
expires_in	Срок действия маркера доступа (в секундах).
refresh_token	Маркер обновления OAuth 2.0. Приложение может использовать этот маркер для получения дополнительных маркеров доступа после истечения срока действия текущего маркера доступа. Токены обновления действуют в течение долгого времени. Их можно использовать для длительного сохранения доступа к ресурсам.
refresh_token_expires_in	Срок действия маркера обновления (в секундах).
id_token	A JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или обеспечения безопасности.

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

GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Поток предоставления токена обновления

Срок действия маркеров доступа весьма ограничен, поэтому их нужно обновлять после его истечения, чтобы продолжить пользоваться запросами. Это можно сделать, отправив другой запрос POST в /token конечную точку, на этот раз предоставив refresh_token вместо кода. Маркеры обновления действуют для всех разрешений, для которых клиент уже получил маркер доступа.

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

Хотя маркеры обновления не отозваны при получении новых маркеров доступа, ожидается, что вы не будете карта старый маркер обновления. Согласно спецификации OAuth 2.0, говорится: "Сервер авторизации может выдавать новый маркер обновления, в этом случае клиент должен отсоответить карта старый маркер обновления и заменить его новым маркером обновления. Сервер авторизации может отозвать старый маркер обновления после выдачи нового маркера обновления клиенту". AD FS выдает маркер обновления, если время существования нового маркера обновления превышает предыдущее время существования маркера обновления. См. сведения о времени существования маркера обновления AD FS в статье Параметры единого входа AD FS.

// Line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for confidential clients (web apps)

Параметр	Обязательно/Необязательно	Description
client_id	обязательно	Идентификатор приложения (клиента), назначенный приложению AD FS.
grant_type	обязательно	Должен быть refresh_token для этого участка потока кода авторизации.
resource	необязательно	URL-адрес веб-API. Примечание. Если используется клиентская библиотека MSAL, параметр ресурса не отправляется. Вместо этого URL-адрес ресурса отправляется как часть параметра область: scope = [resource url]//[scope values e.g., openid] если ресурс не передается здесь или в область, AD FS использует urn:microsoft:userinfo по умолчанию. Политики ресурсов userinfo, такие как MFA, политика выдачи или авторизации, не могут быть настроены.
область	необязательно	Список областей с разделителями-пробелами.
refresh_token	обязательно	Токен обновления, полученный на втором участке потока.
client_secret	необходим для веб-приложений	Секрет приложения, созданный на портале регистрации для приложения. Его не следует использовать в собственном приложении, так как client_secrets невозможно надежно хранить на устройствах. Этот секрет требуется для веб-приложений и веб-API с возможностью безопасного хранения секрета клиента на сервере. Эти приложения также могут использовать проверку подлинности на основе ключей, подписывая JWT и добавляя его в виде параметра client_assertion.

Успешный ответ

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

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}

Параметр	Описание
access_token;	Запрашиваемый маркер доступа. Приложение может использовать этот маркер для аутентификации в защищенном ресурсе, таком как веб-API.
token_type	Указывает значение типа маркера. В AD FS поддерживается только один тип — Bearer (носитель).
expires_in	Срок действия маркера доступа (в секундах).
область	Области, для которых действителен маркер доступа.
refresh_token	Маркер обновления OAuth 2.0. Приложение может использовать этот маркер для получения дополнительных маркеров доступа после истечения срока действия текущего маркера доступа. Токены обновления действуют в течение долгого времени. Их можно использовать для длительного сохранения доступа к ресурсам.
refresh_token_expires_in	Срок действия маркера обновления (в секундах).
id_token	A JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или обеспечения безопасности.

Поток On-Behalf-Of

Примечание.

Корпорация Майкрософт настоятельно рекомендует переход на идентификатор Microsoft Entra, а не обновление до более новой версии AD FS. Дополнительные сведения о потоке On-Behalf-Of в идентификаторе Microsoft Entra см. в платформа удостоверений Майкрософт.

Поток On-Behalf-Of (OBO) в OAuth 2.0 используется в том случае, когда приложение вызывает службу или веб-API, который, в свою очередь, должен вызывать другую службу или веб-API. Идея состоит в том, чтобы распространить делегированное удостоверение пользователя и разрешения с помощью цепочки запросов. Чтобы служба среднего уровня выполняла запросы к подчиненной службе с проверкой подлинности, ей необходимо обеспечить защиту маркеру доступа в AD FS от имени пользователя.

Схема протокола

Предположим, что пользователь прошел проверку подлинности в приложении с помощью потока предоставления кода авторизации OAuth 2.0, описанного в предыдущем разделе. На этом этапе приложение содержит маркер доступа для API А (маркер A) с утверждениями пользователя и разрешением на доступ к веб-API среднего уровня (API A). Убедитесь, что клиент запрашивает в маркере область user_impersonation. Теперь API A должен выполнить запрос к веб-API нижнего уровня (API B) с проверкой подлинности.

Последующие шаги образуют поток OBO. Эти шаги поясняются на следующей схеме.

1. Клиентское приложение выполняет запрос к API A с маркером A. Примечание. При настройке потока OBO в AD FS убедитесь, что выбраны область user_impersonation и клиент выполняет запрос user_impersonation область в запросе.
2. API A выполняет проверку подлинности в конечной точке выдачи маркера AD FS и запрашивает маркер для доступа к API B. Обратите внимание: при настройке этого потока в AD FS убедитесь, что API A также зарегистрирован в качестве серверного приложения с clientID с таким же значением, как и идентификатор ресурса в API A.
3. Конечная точка выдачи маркера AD FS проверяет учетные данные API А с использованием маркера А и выдает маркер доступа для API Б (маркер Б).
4. Маркер B задается в заголовке авторизации запроса к API B.
5. API B возвращает данные из защищенного ресурса.

Запрос маркера взаимного доступа между службами

Чтобы запросить маркер доступа, выполните HTTP-запрос POST к конечной точке маркеров AD FS со следующими параметрами.

Первый сценарий: запрос маркера доступа с помощью общего секрета

Для общего секрета запрос маркера доступа между службами содержит следующие параметры:

Параметр	Обязательно/Необязательно	Description
grant_type	обязательно	Тип запроса маркера. Для запроса с использованием JWT должно быть указано значение urn:ietf:params:oauth:grant-type:jwt-bearer.
client_id	обязательно	Идентификатор клиента, который вы настроили при регистрации первого веб-API для серверного приложения (приложение среднего уровня). Он должен совпадать с идентификатором ресурса, используемым в первом этапе, то есть URL-адресом первого веб-API.
client_secret	обязательно	Секрет приложения, созданный во время регистрации серверного приложения в AD FS.
assertion	обязательно	Значение токена, используемого в запросе.
requested_token_use	обязательно	Указывает, как должен быть обработан запрос. В потоке On-Behalf-Of должно быть указано значение on_behalf_of.
resource	обязательно	Идентификатор ресурса, предоставленный при регистрации первого веб-API в качестве серверного приложения (приложение среднего уровня). Идентификатор ресурса должен быть URL-адресом второго вызова приложения среднего уровня веб-API от имени клиента.
область	необязательно	Список областей для запроса токена, разделенный пробелами.

Пример

В приведенном ниже примере HTTP POST запрашивается маркер доступа и маркер обновления.

//line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid

Второй сценарий: запрос маркера доступа с помощью сертификата

Запрос маркера взаимного доступа между службами с помощью сертификата содержит следующие параметры:

Параметр	Обязательный или необязательный	Description
grant_type	обязательно	Тип запроса маркера. Для запроса с использованием JWT должно быть указано значение urn:ietf:params:oauth:grant-type:jwt-bearer.
client_id	обязательно	Идентификатор клиента, который вы настроили при регистрации первого веб-API для серверного приложения (приложение среднего уровня). Он должен совпадать с идентификатором ресурса, используемым в первом этапе, то есть URL-адресом первого веб-API.
client_assertion_type	обязательно	Значение должно быть urn:ietf:params:oauth:client-assert-type:jwt-bearer.
client_assertion	обязательно	Утверждение (JSON Web Token), которое необходимо создать и подписать с помощью сертификата, зарегистрированного как учетные данные для приложения.
assertion	обязательно	Значение токена, используемого в запросе.
requested_token_use	обязательно	Указывает, как должен быть обработан запрос. В потоке On-Behalf-Of должно быть указано значение on_behalf_of.
resource	обязательно	Идентификатор ресурса, предоставленный при регистрации первого веб-API в качестве серверного приложения (приложение среднего уровня). Идентификатор ресурса должен быть URL-адресом второго вызова приложения среднего уровня веб-API от имени клиента.
область	необязательно	Список областей для запроса токена, разделенный пробелами.

Обратите внимание, что параметры почти одинаковы. Этот пример аналогичен запросу по общему секрету, за исключением того, что параметр client_secret заменяется двумя параметрами: client_assertion_type и client_assertion.

Пример

Следующий HTTP POST запрашивает маркер доступа для веб-API с сертификатом.

// line breaks for legibility only

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid

Ответ для токена доступа между службами

Если доступ предоставлен, ответ будет содержать JSON-файл OAuth 2.0 со следующими параметрами.

Параметр	Описание
token_type	Указывает значение типа маркера. В AD FS поддерживается только один тип — Bearer (носитель).
область	Область доступа, предоставляемая токеном.
expires_in	Срок действия маркера доступа (в секундах).
access_token;	Запрашиваемый маркер доступа. Вызывающая служба может использовать этот токен для проверки подлинности принимающей службы.
id_token	A JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или обеспечения безопасности.
refresh_token	Токен обновления для запрошенного токена доступа. Вызывающая служба может использовать этот токен для запроса другого токена доступа после того, как срок действия текущего токена доступа истек.
Refresh_token_expires_in	Срок действия маркера обновления (в секундах).

Пример ответа с успешным предоставлением доступа

Ниже представлен пример с ответом об успешном выполнении запроса маркера доступа к веб-API.

{
  "token_type": "Bearer",
  "scope": openid,
  "expires_in": 3269,
  "access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
  "id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
  "refresh_token": "OAQABAAAAAABnfiG…"
  "refresh_token_expires_in": 28800,
}

Используйте маркер доступа для доступа к защищенному ресурсу Теперь служба среднего уровня может использовать маркер, полученный в предыдущем примере ответа, чтобы выполнить прошедшие проверку подлинности запросы к нижестоящему веб-API, задав маркер в заголовке авторизации.

Пример

GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…

Поток предоставления учетных данных клиента

Примечание.

Корпорация Майкрософт настоятельно рекомендует переход на идентификатор Microsoft Entra, а не обновление до более новой версии AD FS. Дополнительные сведения о потоке предоставления учетных данных клиента в идентификаторе Microsoft Entra см. в разделе "Поток предоставления учетных данных клиента" в платформа удостоверений Майкрософт.

Учетные данные клиента OAuth 2.0, указанные в RFC 6749, можно использовать для доступа к размещенным в Интернете ресурсам с помощью удостоверения приложения. Этот тип предоставления разрешения часто используется для взаимодействия между серверами, которое должно выполняться в фоновом режиме без непосредственного взаимодействия с пользователем. Такие типы приложений часто называют управляющими программами или учетными записями служб.

Процесс предоставления учетных данных клиента OAuth 2.0 позволяет веб-службе (конфиденциальный клиент) вместо олицетворения пользователя использовать свои собственные учетные данные для аутентификации при вызове другой веб-службы. В этом сценарии клиент обычно является веб-службой среднего уровня, службой управляющей программы или веб-сайтом. Для повышения надежности AD FS позволяет вызывающей службе использовать сертификат (вместо общего секрета) в качестве учетных данных.

Схема протокола

На следующей схеме показан поток предоставления учетных данных клиента.

Запрос маркера

Чтобы получить маркер через предоставление учетных данных клиента, отправьте запрос POST к конечной точке AD FS /token:

Первый сценарий: запрос маркера доступа с помощью общего секрета

POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity

Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials

Параметр	Обязательно/Необязательно	Description
client_id	обязательно	Идентификатор приложения (клиента), назначенный приложению AD FS.
область	необязательно	Разделенный пробелами список областей , для которого необходимо согласие пользователя.
client_secret	обязательно	Секрет клиента, который вы создали для приложения на портале регистрации приложений. Секрет клиента должен быть преобразован в формат URL-адреса перед отправкой.
grant_type	обязательно	Должен иметь значениеclient_credentials.

Второй сценарий: запрос маркера доступа с помощью сертификата

POST /adfs/oauth2/token HTTP/1.1

// Line breaks for clarity

Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials

Параметр	Обязательно/Необязательно	Description
client_assertion_type	обязательно	Значение должно быть задано как urn:ietf:params:oauth:client-assert-type:jwt-bearer.
client_assertion	обязательно	Утверждение (JSON Web Token), которое необходимо создать и подписать с помощью сертификата, зарегистрированного как учетные данные для приложения.
grant_type	обязательно	Должен иметь значениеclient_credentials.
client_id	необязательно	Идентификатор приложения (клиента), назначенный приложению AD FS. Это часть client_assertion, поэтому здесь не требуется передавать его.
область	необязательно	Разделенный пробелами список областей , для которого необходимо согласие пользователя.

Использование маркера

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

GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...

Поток предоставления учетных данных владельца ресурса с паролем (не рекомендуется)

Примечание.

Корпорация Майкрософт настоятельно рекомендует переход на идентификатор Microsoft Entra, а не обновление до более новой версии AD FS. Дополнительные сведения о потоке предоставления учетных данных владельца ресурса в идентификаторе Microsoft Entra ID см. в платформа удостоверений Майкрософт потоке предоставления учетных данных владельца ресурса.

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

Схема протокола

На следующей схеме показано представление потока ROPC.

Запрос авторизации

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

// Line breaks and spaces are for legibility only.

POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password

Параметр	Обязательно/Необязательно	Description
client_id	обязательно	Client ID
grant_type	обязательно	Необходимо задать пароль.
username	обязательно	Адрес электронной почты пользователя.
password	обязательно	Пароль пользователя.
область	необязательно	Список областей с разделителями-пробелами.

Успешный ответ аутентификации

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

{
    "token_type": "Bearer",
    "scope": "openid",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "refresh_token_expires_in": 28800,
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}

Параметр	Описание
token_type	Всегда задано значение носителя.
область	Если возвращен маркер доступа, этот параметр содержит список областей, для которых действует этот маркер.
expires_in	Количество секунд, в течение которых действует предоставленный маркер доступа.
access_token;	Выдается для запрошенных областей.
id_token	A JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или обеспечения безопасности.
refresh_token_expires_in	Срок действия прилагаемого маркера обновления (в секундах).
refresh_token	Выдано, если исходный параметр область включал offline_access.

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

Поток кода устройства

Примечание.

Корпорация Майкрософт настоятельно рекомендует переход на идентификатор Microsoft Entra, а не обновление до более новой версии AD FS. Дополнительные сведения о потоке кода устройства в идентификаторе Microsoft Entra см. в платформа удостоверений Майкрософт.

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

Схема протокола

Весь поток кода устройства аналогичен приведенному на следующей схеме. Описание каждого шага приведено далее в этой статье.

Запрос авторизации устройства

Клиент должен сначала обратиться к серверу проверки подлинности и получить код для устройства и пользователя, который используется для запуска проверки подлинности. Клиент собирает этот запрос из конечной точки /devicecode. В этом запросе клиент также должен добавить разрешения, которые ему требуется получить от пользователя. С момента отправки этого запроса пользователь может войти только через 15 минут (обычное значение для expires_in), поэтому только выполните этот запрос, когда пользователь указал, что он готов войти.

// Line breaks are for legibility only.

POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
scope=openid

Параметр	Условие	Description
client_id	обязательно	Идентификатор приложения (клиента), назначенный приложению AD FS.
область	необязательно	Список областей с разделителями-пробелами.

Ответ авторизации устройства

Успешный ответ — это объект JSON, содержащий необходимые сведения для входа пользователя.

Параметр	Описание
device_code	Длинная строка, используемая для проверки сеанса между клиентом и сервером авторизации. Клиент использует этот параметр для запроса маркера доступа от сервера авторизации.
user_code	Короткая строка, которая отображается пользователю, для идентификации того же сеанса на другом устройстве.
verification_uri	Универсальный код ресурса (URI), к которым пользователь должен перейти с помощью user_code для входа.
verification_uri_complete	Универсальный код ресурса (URI), к которым пользователь должен перейти с помощью user_code для входа. Он предварительно заполнен user_code, чтобы пользователь не должен вводить user_code
expires_in	Количество секунд до истечения срока действия device_code и user_code.
interval	Число секунд ожидания клиентом между опрашивающими запросами.
message	Понятная пользователю строка с инструкциями. Его можно локализовать, включив параметр запроса в запрос формы ?mkt=xx-XX, заполнив соответствующий код языка и региональных параметров.

Проверка подлинности пользователя

После того как клиент получит user_code и verification_uri, он отображает эти сведения пользователю, введя их в систему с помощью мобильного телефона или браузера ПК. Кроме того, клиент может использовать QR-код или аналогичный механизм для отображения verfication_uri_complete, что делает шаг ввода user_code для пользователя. Хотя пользователь выполняет проверку подлинности в verification_uri, клиент должен опрашивание конечной точки /token для запрошенного маркера с помощью device_code.

POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 6731de76-14a6-49ae-97bc-6eba6914391e
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8

Параметр	обязательно	Описание
grant_type	обязательно	Должен быть urn:ietf:params:oauth:grant-type:device_code
client_id	обязательно	Должен соответствовать client_id, используемому в первоначальном запросе.
кодом	обязательно	Device_code, возвращенные в запросе авторизации устройства.

Успешный ответ аутентификации

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

Параметр	Описание
token_type	Всегда "Медведь".
область	Если маркер доступа был возвращен, он выводит список область допустимого маркера доступа.
expires_in	Количество секунд, в течение которых маркер доступа является допустимым.
access_token;	Выдается для запрошенных областей.
id_token	Выдано, если исходный параметр область включал область openid.
refresh_token	Выдано, если исходный параметр область включал offline_access.
refresh_token_expires_in	Срок действия прилагаемого маркера обновления (в секундах).

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

Полный список пошаговых руководств по использованию соответствующих потоков вы найдете на странице о разработке для AD FS.