ссылка для редиректа приложения согласно потоку oauth
OAuth 2.0 простым и понятным языком
На хабре уже писали про OAuth 1.0, но понятного объяснения того, что такое OAuth 2.0 не было. Ниже я расскажу, в чем отличия и преимущества OAuth 2.0 и, как его лучше использовать на сайтах, в мобильных и desktop-приложениях.
Что такое OAuth 2.0
OAuth 2.0 — протокол авторизации, позволяющий выдать одному сервису (приложению) права на доступ к ресурсам пользователя на другом сервисе. Протокол избавляет от необходимости доверять приложению логин и пароль, а также позволяет выдавать ограниченный набор прав, а не все сразу.
Чем отличаются OpenID и OAuth
Не смотря на то, что объяснений на эту тему уже было много, она по-прежнему вызывает некоторое непонимание.
OpenID предназначен для аутентификации — то есть для того, чтобы понять, что этот конкретный пользователь является тем, кем представляется. Например, с помощью OpenID некий сервис Ололо может понять, что зашедший туда пользователь, это именно Рома Новиков с Mail.Ru. При следующей аутентификации Ололо сможет его опять узнать и понять, что, это тот же Рома, что и в прошлый раз.
OAuth же является протоколом авторизации, то есть позволяет выдать права на действия, которые сам Ололо сможет производить в Mail.Ru от лица Ромы. При этом Рома после авторизации может вообще не участвовать в процессе выполнения действий, например, Ололо сможет самостоятельно заливать фотографии на Ромин аккаунт.
Как работает OAuth 2.0
Как и первая версия, OAuth 2.0 основан на использовании базовых веб-технологий: HTTP-запросах, редиректах и т. п. Поэтому использование OAuth возможно на любой платформе с доступом к интернету и браузеру: на сайтах, в мобильных и desktop-приложениях, плагинах для браузеров…
Ключевое отличие от OAuth 1.0 — простота. В новой версии нет громоздких схем подписи, сокращено количество запросов, необходимых для авторизации.
Авторизация для приложений, имеющих серверную часть
Пример
Здесь и далее примеры приводятся для API Mail.Ru, но логика одинаковая для всех сервисов, меняются только адреса страниц авторизации. Обратите внимание, что запросы надо делать по HTTPS.
Редиректим браузер пользователя на страницу авторизации:
Здесь и далее, client_id и client_secret — значения, полученные при регистрации приложения на платформе.
После того, как пользователь выдаст права, происходит редирект на указанный redirect_uri:
Обратите внимание, если вы реализуете логин на сайте с помощью OAuth, то рекомендуется в redirect_uri добавлять уникальный для каждого пользователя идентификатор для предотвращения CSRF-атак (в примере это 123). При получении кода надо проверить, что этот идентификатор не изменился и соответствует текущему пользователю.
Используем полученный code для получения access_token, выполняя запрос с сервера:
Обратите внимание, что в последнем запросе используется client_secret, который в данном случае хранится на сервере приложения, и подтверждает, что запрос не подделан.
В результате последнего запроса получаем сам ключ доступа (access_token), время его «протухания» (expires_in), тип ключа, определяющий как его надо использовать, (token_type) и refresh_token о котором будет подробнее сказано ниже. Дальше, полученные данные можно использовать для доступа к защищенным ресурсам, например, API Mail.Ru:
Авторизация полностью клиентских приложений
Пример
Открываем браузер со страницей авторизации:
После того, как пользователь выдаст права, происходит редирект на стандартную страницу-заглушку, для Mail.Ru это connect.mail.ru/oauth/success.html:
Приложение должно перехватить последний редирект, получить из адреса acess_token и использовать его для обращения к защищенным ресурсам.
Авторизация по логину и паролю
Авторизация по логину и паролю представляет простой POST-запрос, в результате которого возвращается access token. Такая схема не представляет из себя ничего нового, но вставлена в стандарт для общности и рекомендуется к применению только, когда другие варианты авторизации не доступны.
Пример
Восстановление предыдущей авторизации
Обычно, access token имеет ограниченный срок годности. Это может быть полезно, например, если он передается по открытым каналам. Чтобы не заставлять пользователя проходить авторизацию после истечения срока действия access token‘а, во всех перечисленных выше вариантах, в дополнение к access token‘у может возвращаться еще refresh token. По нему можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю.
Пример
Минусы OAuth 2.0
Во всей этой красоте есть и ложка дегтя, куда без нее?
OAuth 2.0 — развивающийся стандарт. Это значит, что спецификация еще не устоялась и постоянно меняется, иногда довольно заметно. Так, что если вы решили поддержать стандарт прямо сейчас, приготовьтесь к тому, что его поддержку придется подпиливать по мере изменения спецификации. С другой стороны, это также значит, что вы можете поучаствовать в процессе написания стандарта и внести в него свои идеи.
Безопасность OAuth 2.0 во многом основана на SSL. Это сильно упрощает жизнь разработчикам, но требует дополнительных вычислительных ресурсов и администрирования. Это может быть существенным вопросом в высоко нагруженных проектах.
Заключение
OAuth — простой стандарт авторизации, основанный на базовых принципах интернета, что делает возможным применение авторизации практически на любой платформе. Стандарт имеет поддержку крупнейших площадок и очевидно, что его популярность будет только расти. Если вы задумались об API для вашего сервиса, то авторизация с использованием OAuth 2.0 — хороший выбор.
OAuth 2.0 простым и понятным языком
На хабре уже писали про OAuth 1.0, но понятного объяснения того, что такое OAuth 2.0 не было. Ниже я расскажу, в чем отличия и преимущества OAuth 2.0 и, как его лучше использовать на сайтах, в мобильных и desktop-приложениях.
Что такое OAuth 2.0
OAuth 2.0 — протокол авторизации, позволяющий выдать одному сервису (приложению) права на доступ к ресурсам пользователя на другом сервисе. Протокол избавляет от необходимости доверять приложению логин и пароль, а также позволяет выдавать ограниченный набор прав, а не все сразу.
Чем отличаются OpenID и OAuth
Не смотря на то, что объяснений на эту тему уже было много, она по-прежнему вызывает некоторое непонимание.
OpenID предназначен для аутентификации — то есть для того, чтобы понять, что этот конкретный пользователь является тем, кем представляется. Например, с помощью OpenID некий сервис Ололо может понять, что зашедший туда пользователь, это именно Рома Новиков с Mail.Ru. При следующей аутентификации Ололо сможет его опять узнать и понять, что, это тот же Рома, что и в прошлый раз.
OAuth же является протоколом авторизации, то есть позволяет выдать права на действия, которые сам Ололо сможет производить в Mail.Ru от лица Ромы. При этом Рома после авторизации может вообще не участвовать в процессе выполнения действий, например, Ололо сможет самостоятельно заливать фотографии на Ромин аккаунт.
Как работает OAuth 2.0
Как и первая версия, OAuth 2.0 основан на использовании базовых веб-технологий: HTTP-запросах, редиректах и т. п. Поэтому использование OAuth возможно на любой платформе с доступом к интернету и браузеру: на сайтах, в мобильных и desktop-приложениях, плагинах для браузеров…
Ключевое отличие от OAuth 1.0 — простота. В новой версии нет громоздких схем подписи, сокращено количество запросов, необходимых для авторизации.
Авторизация для приложений, имеющих серверную часть
Пример
Здесь и далее примеры приводятся для API Mail.Ru, но логика одинаковая для всех сервисов, меняются только адреса страниц авторизации. Обратите внимание, что запросы надо делать по HTTPS.
Редиректим браузер пользователя на страницу авторизации:
Здесь и далее, client_id и client_secret — значения, полученные при регистрации приложения на платформе.
После того, как пользователь выдаст права, происходит редирект на указанный redirect_uri:
Обратите внимание, если вы реализуете логин на сайте с помощью OAuth, то рекомендуется в redirect_uri добавлять уникальный для каждого пользователя идентификатор для предотвращения CSRF-атак (в примере это 123). При получении кода надо проверить, что этот идентификатор не изменился и соответствует текущему пользователю.
Используем полученный code для получения access_token, выполняя запрос с сервера:
Обратите внимание, что в последнем запросе используется client_secret, который в данном случае хранится на сервере приложения, и подтверждает, что запрос не подделан.
В результате последнего запроса получаем сам ключ доступа (access_token), время его «протухания» (expires_in), тип ключа, определяющий как его надо использовать, (token_type) и refresh_token о котором будет подробнее сказано ниже. Дальше, полученные данные можно использовать для доступа к защищенным ресурсам, например, API Mail.Ru:
Авторизация полностью клиентских приложений
Пример
Открываем браузер со страницей авторизации:
После того, как пользователь выдаст права, происходит редирект на стандартную страницу-заглушку, для Mail.Ru это connect.mail.ru/oauth/success.html:
Приложение должно перехватить последний редирект, получить из адреса acess_token и использовать его для обращения к защищенным ресурсам.
Авторизация по логину и паролю
Авторизация по логину и паролю представляет простой POST-запрос, в результате которого возвращается access token. Такая схема не представляет из себя ничего нового, но вставлена в стандарт для общности и рекомендуется к применению только, когда другие варианты авторизации не доступны.
Пример
Восстановление предыдущей авторизации
Обычно, access token имеет ограниченный срок годности. Это может быть полезно, например, если он передается по открытым каналам. Чтобы не заставлять пользователя проходить авторизацию после истечения срока действия access token‘а, во всех перечисленных выше вариантах, в дополнение к access token‘у может возвращаться еще refresh token. По нему можно получить access token с помощью HTTP-запроса, аналогично авторизации по логину и паролю.
Пример
Минусы OAuth 2.0
Во всей этой красоте есть и ложка дегтя, куда без нее?
OAuth 2.0 — развивающийся стандарт. Это значит, что спецификация еще не устоялась и постоянно меняется, иногда довольно заметно. Так, что если вы решили поддержать стандарт прямо сейчас, приготовьтесь к тому, что его поддержку придется подпиливать по мере изменения спецификации. С другой стороны, это также значит, что вы можете поучаствовать в процессе написания стандарта и внести в него свои идеи.
Безопасность OAuth 2.0 во многом основана на SSL. Это сильно упрощает жизнь разработчикам, но требует дополнительных вычислительных ресурсов и администрирования. Это может быть существенным вопросом в высоко нагруженных проектах.
Заключение
OAuth — простой стандарт авторизации, основанный на базовых принципах интернета, что делает возможным применение авторизации практически на любой платформе. Стандарт имеет поддержку крупнейших площадок и очевидно, что его популярность будет только расти. Если вы задумались об API для вашего сервиса, то авторизация с использованием OAuth 2.0 — хороший выбор.
Потоки OpenID Connect или OAuth в AD FS и сценарии использования приложений
Применимо к AD FS 2016 и более поздних версий
| Сценарий | Пошаговое руководство по использованию сценария с примерами | Поток и предоставление OAuth 2.0 | Тип клиента |
|---|---|---|---|
| Single-page app | • Пример с использованием ADAL | Неявно | Общие |
| Web App that signs in users | • Пример с использованием OWIN | Код авторизации | Общедоступный, конфиденциальный |
| Native App calls Web API | • Sample using MSAL • Пример с использованием ADAL | Код авторизации | Общие |
| Web App calls Web API | • Sample using MSAL • Пример с использованием ADAL | Код авторизации | Конфиденциальный |
| Web API calls another web API on behalf of (OBO) the user | • Sample using MSAL • Пример с использованием ADAL | Вызов от имени | Веб-приложение в режиме «конфиденциально» |
| Вызов веб-API в управляющей программе | Учетные данные клиента | Конфиденциальный | |
| Вызов веб-API в веб-приложении с учетными данными пользователя | Учетные данные владельца ресурса с паролем | Общедоступный, конфиденциальный | |
| Вызов веб-API в приложении без использования браузера | Код устройства | Общедоступный, конфиденциальный |
Поток неявного предоставления
Для одностраничных приложений (AngularJS, Ember.js, React.js и т. п.), AD FS поддерживает поток неявного предоставления OAuth 2.0. Неявный поток описан в спецификации OAuth 2,0. Основное его преимущество заключается в том, что приложения могут получать маркеры от AD FS без обмена учетными данными с внутренним сервером. Это позволяет приложению входить в систему пользователя, поддерживать сеанс и получать маркеры для других веб-API в коде JavaScript клиента. При использовании неявного потока, предназначенного для клиента, необходимо учитывать ряд важных соображений безопасности.
Если вы хотите добавить в приложение JavaScript проверку подлинности на основе неявного потока и AD FS, выполните представленные ниже общие шаги.
Схема протокола
На следующей схеме представлен весь неявный поток входа, а каждый его шаг подробно описан в следующих разделах.
Маркер идентификатора запроса и маркер доступа
Чтобы выполнить первый вход пользователя в приложение, можно отправить запрос на проверку подлинности в OpenID Connect и получить маркеры идентификатора и доступа из конечной точки AD FS.
В этом сценарии пользователю будет предложено ввести учетные данные и выполнить проверку подлинности. Когда завершится проверка подлинности для пользователя, конечная точка авторизации AD FS вернет приложению ответ по указанному URI перенаправления (redirect_uri), используя метод из параметра response_mode.
Успешный ответ
Успешный ответ с помощью response_mode=fragment and response_type=id_token+token выглядит следующим образом:
Маркеры обновления
Поток предоставления кода авторизации
Предоставление кода авторизации в OAuth 2.0 можно использовать в веб-приложениях для получения доступа к защищенным ресурсам, таким как веб-API. Поток кода авторизации OAuth 2,0 описан в разделе 4,1 спецификации OAuth 2,0. Он используется для проверки подлинности и авторизации в большинстве типов приложений, в том числе в веб-приложениях и нативных устанавливаемых приложениях. Этот поток позволяет приложениям безопасно получать access_token, чтобы использовать его для доступа к ресурсам с доверием в отношении AD FS.
Схема протокола
На обобщенном уровне поток проверки подлинности для нативного приложения выглядит примерно так:
Запрос кода авторизации
Поток кода авторизации начинается с того, что клиент направляет пользователя в конечную точку /authorize. В этом запросе клиент указывает разрешения, которые нужно получить от пользователя.
В этом сценарии пользователю будет предложено ввести учетные данные и выполнить проверку подлинности. После того как пользователь проходит проверку подлинности, AD FS будет возвращать ответ на ваше приложение в указанном redirect_uri виде с помощью метода, указанного в response_mode параметре.
Успешный ответ
Успешный ответ при использовании response_mode=query выглядит примерно так:
Запрос маркера доступа
Теперь, когда вы приобрели authorization_code и получили разрешение у пользователя, вы можете активировать код для access_token для требуемого ресурса. Для этого отправьте запрос POST к конечной точке /token, как показано ниже.
Успешный ответ
Успешный ответ на запрос маркера будет выглядеть следующим образом:
| Параметр | Описание |
|---|---|
| access_token | Запрошенный маркер доступа. Приложение может использовать этот маркер для проверки подлинности при обращении к защищенному ресурсу (веб-API). |
| token_type | Обозначает значение типа маркера. В AD FS поддерживается только один тип — Bearer (носитель). |
| expires_in | Срок действия маркера доступа (в секундах). |
| refresh_token | Маркер обновления OAuth 2.0. Приложение может с помощью этого маркера получить дополнительные маркеры доступа после истечения срока действия текущего маркера доступа. Refresh_token имеет длительный срок действия и может использоваться для сохранения доступа к ресурсам в течение продолжительного периода времени. |
| refresh_token_expires_in | Срок действия маркера обновления (в секундах). |
| id_token | JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или организации безопасности. |
Использование маркера доступа
Поток предоставления токена обновления
Access_token имеет короткий срок действия, и после истечения этого срока маркер нужно обновить, чтобы сохранить доступ к ресурсам. Это можно сделать, отправив другой запрос POST в /token конечную точку, на этот раз предоставляя refresh_token, а не код. Маркеры обновления действуют для всех разрешений, для которых клиент уже получил маркер доступа.
Маркеры обновления не имеют определенного времени существования. Обычно этот период является относительно долгим. Но может случиться так, что у маркера обновления истекает срок действия, он отзывается или не имеет достаточных привилегий для требуемого действия. В приложении нужно предусмотреть решение для таких ситуаций и правильную обработку ошибок, возвращаемых конечной точкой выдачи маркеров.
Хотя маркеры обновления не отзываются при использовании для получения новых маркеров доступа, обычно предполагается, что старый маркер обновления после этого удаляется. В спецификации OAuth 2.0 указано следующее: «Сервер авторизации МОЖЕТ выдать новый маркер обновления, и в этом случае клиент ДОЛЖЕН удалить старый маркер обновления и заменить его новым маркером обновления. Сервер авторизации может отозвать старый маркер обновления после выпуска нового маркера обновления для клиента «. AD FS выдает маркер обновления, когда время существования нового маркера обновления превышает время существования предыдущего маркера обновления. См. сведения о времени существования маркера обновления AD FS в статье Параметры единого входа AD FS.
| Параметр | Обязательный/необязательный | Описание |
|---|---|---|
| client_id | обязательные | Идентификатор приложения (клиента), который AD FS назначает приложению. |
| grant_type | обязательно | Должен быть refresh_token для этого участка потока кода авторизации. |
| resource | необязательно | The url of your Web API. Обратите внимание, что при использовании клиентской библиотеки MSAL параметр resource не отправляется. Instead the resource url is sent as a part of the scope parameter: scope = [resource url]//[scope values e.g., openid] Если ресурс не передается ни в этом параметре, ни в scope, ADFS будет использовать ресурс по умолчанию — urn:microsoft:userinfo. Политики ресурсов userinfo, например MFA, выдачи сертификатов или авторизации, нельзя настроить. |
| scope | необязательно | Список областей с разделителями-пробелами. |
| refresh_token | обязательные | Содержит маркер обновления, полученный во второй части потока. |
| client_secret | Требуется для веб-приложений. | Секрет приложения, который вы создали на портале регистрации приложения. Не следует использовать его в нативном приложении, так как на устройствах нет возможности надежно хранить client_secrets. Он требуется для веб-приложений и веб-API, которые могут безопасно хранить client_secret на стороне сервера. Эти приложения также могут использовать проверку подлинности на основе ключей, подписывая JWT и добавляя его в виде параметра client_assertion. |
Успешный ответ
Успешный ответ на запрос маркера будет выглядеть следующим образом:
| Параметр | Описание |
|---|---|
| access_token | Запрашиваемый маркер доступа. Приложение может использовать этот маркер для проверки подлинности защищаемого источника, например веб-API. |
| token_type | Обозначает значение типа маркера. В AD FS поддерживается только один тип — Bearer (носитель). |
| expires_in | Срок действия маркера доступа (в секундах). |
| scope | Области, для которых действует access_token. |
| refresh_token | Маркер обновления OAuth 2.0. Приложение может с помощью этого маркера получить дополнительные маркеры доступа после истечения срока действия текущего маркера доступа. Refresh_token имеет длительный срок действия и может использоваться для сохранения доступа к ресурсам в течение продолжительного периода времени. |
| refresh_token_expires_in | Срок действия маркера обновления (в секундах). |
| id_token | JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или организации безопасности. |
Поток On-Behalf-Of
поток On-Behalf-Of в OAuth 2.0 предназначен для случаев, когда приложение вызывает службу или веб-API, которые, в свою очередь, должны обращаться к другой службе или веб-API. Идея состоит в том, чтобы передать по цепочке запросов делегированное удостоверение пользователя и соответствующие разрешения. Чтобы служба среднего уровня выполняла запросы к подчиненной службе с проверкой подлинности, ей необходимо обеспечить защиту маркеру доступа в AD FS от имени пользователя.
Схема протокола
Предположим, что пользователь прошел проверку подлинности в приложении, используя описанный выше поток предоставления кода авторизации OAuth 2.0. На этом этапе приложение имеет маркер доступа для API А (маркер А) с утверждениями пользователя и согласием на доступ к веб-API среднего уровня (API А). Убедитесь, что клиент запрашивает в маркере область user_impersonation. Теперь API A должен выполнить запрос с проверкой подлинности к следующему веб-API в цепочке (API Б).
Ниже перечислены действия в потоке вызова от имени, и они же иллюстрируются на следующей схеме.
Запрос маркера доступа для взаимодействия между службами
Чтобы запросить маркер доступа, выполните HTTP-запрос POST к конечной точке маркеров AD FS со следующими параметрами.
Первый пример. Запрос маркера доступа по общему секрету
При использовании общего секрета запрос маркера взаимного доступа между службами содержит следующие параметры:
| Параметр | Обязательный/необязательный | Описание |
|---|---|---|
| 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 среднего уровня, которое нужно вызывать от имени клиента. |
| scope | необязательно | Список областей для запроса маркера с разделителями-пробелами. |
Пример
В приведенном ниже примере HTTP POST запрашивается маркер доступа и маркер обновления.
Второй пример. Запрос маркера доступа по сертификату
Запрос маркера взаимного доступа между службами с помощью сертификата содержит следующие параметры:
| Параметр | Обязательный или необязательный | Описание |
|---|---|---|
| grant_type | обязательные | Тип запроса маркера. Для запроса с использованием JWT должно быть указано значение urn:ietf:params:oauth:grant-type:jwt-bearer. |
| client_id | обязательные | Идентификатор клиента, который вы настроили при регистрации первого веб-API для серверного приложения (приложение среднего уровня). Он должен совпадать с идентификатором ресурса, который использовался на первом этапе, то есть URL-адресом первого веб-API. |
| client_assertion_type | обязательные | Должно быть указано значение urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| client_assertion | обязательные | Утверждение (JSON Web Token), которое необходимо создать и подписать с помощью сертификата, зарегистрированного вами в качестве учетных данных для приложения. |
| assertion | обязательно | Значение маркера, которое используется в запросе. |
| requested_token_use | обязательно | Позволяет указать, как должен обрабатываться запрос. В потоке On-Behalf-Of должно быть указано значение on_behalf_of. |
| resource | обязательные | Идентификатор ресурса, предоставленный при регистрации первого веб-API в качестве серверного приложения (приложение среднего уровня). Идентификатор ресурса должен быть URL-адресом второго приложения веб-API среднего уровня, которое нужно вызывать от имени клиента. |
| scope | необязательно | Список областей для запроса маркера с разделителями-пробелами. |
Обратите внимание, что здесь используются такие параметры, как и в примере с запросом по общему секрету. Отличается только параметр client_secret, который заменен двумя параметрами: client_assertion_type и client_assertion.
Пример
В следующем примере HTTP-запроса POST запрашивается маркер доступа для веб-API с использованием сертификата.
Ответ на запрос маркера доступа для взаимодействия между службами
Если доступ предоставлен, ответ будет содержать JSON-файл OAuth 2.0 со следующими параметрами.
| Параметр | Описание |
|---|---|
| token_type | Обозначает значение типа маркера. В AD FS поддерживается только один тип — Bearer (носитель). |
| scope | Область доступа, предоставляемая токеном. |
| expires_in | Срок действия маркера доступа (в секундах). |
| access_token | Запрашиваемый маркер доступа. Вызывающая служба может использовать этот токен для проверки подлинности принимающей службы. |
| id_token | JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или организации безопасности. |
| refresh_token | Токен обновления для запрошенного токена доступа. Вызывающая служба может с помощью этого маркера запросить другой маркер доступа после истечения срока действия текущего маркера доступа. |
| Refresh_token_expires_in | Срок действия маркера обновления (в секундах). |
Пример ответа об успешном выполнении
Ниже представлен пример с ответом об успешном выполнении запроса маркера доступа к веб-API.
Использование маркера доступа для доступа к защищенному ресурсу Теперь служба среднего уровня может использовать полученный выше маркер для выполнения проверенных запросов к нижестоящим веб-API, установив маркер в заголовке авторизации.
Пример
Поток предоставления учетных данных клиента
Вы можете использовать учетные данные клиента OAuth 2.0, описанные в RFC 6749, для доступа к размещенным в Интернете ресурсам с применением удостоверения приложения. Этот тип предоставления обычно используется для взаимодействий между серверами, которые должны выполняться в фоновом режиме без активного взаимодействия с пользователем. Эти типы приложений часто называют управляющими программами или учетными записями служб.
Поток предоставления учетных данных клиента OAuth 2.0 позволяет веб-службе (конфиденциальному клиенту) при вызове другой веб-службы проходить проверку подлинности с собственными учетными данными, а не олицетворять пользователя. В этом сценарии клиентом обычно является веб-служба среднего уровня, служба управляющей программы или веб-сайт. Для повышения надежности AD FS позволяет вызывающей службе использовать сертификат (вместо общего секрета) в качестве учетных данных.
Схема протокола
На следующей схеме показан поток предоставления учетных данных клиента.
Запрос маркера
Чтобы получить маркер через предоставление учетных данных клиента, отправьте запрос POST к конечной точке AD FS /token:
Первый пример. Запрос маркера доступа по общему секрету
Второй пример. Запрос маркера доступа по сертификату
Использование маркера
Теперь, когда вы получили маркер, примените его для выполнения запросов к ресурсу. Когда завершится срок действия маркера, повторите запрос к конечной точке /token, чтобы получить новый маркер доступа.
Поток предоставления учетных данных владельца ресурса с паролем (не рекомендуется)
Предоставление учетных данных владельца ресурса с паролем (ROPC) позволяет приложению выполнять вход пользователя путем непосредственной обработки пароля. Поток ROPC требует высокого уровня доверия и создает уязвимость для пользователей, поэтому его следует использовать только в том случае, когда более безопасный поток полностью невозможен.
Схема протокола
На следующей схеме представлен поток ROPC.
Запрос авторизации
Поток ROPC состоит из одного запроса, в котором отправляется идентификатор клиента и учетные данные пользователя поставщику удостоверений, а в ответе возвращаются маркеры. Перед этим клиент должен получить адрес электронной почты и пароль пользователя. Сразу после успешного выполнения запроса клиент обязан безопасно удалить из памяти учетные данные пользователя. Ни в коем случае не сохраняйте эти данные.
| Параметр | Обязательный/необязательный | Описание |
|---|---|---|
| client_id | обязательные | ИД клиента |
| grant_type | обязательные | Должен содержать пароль. |
| username | обязательные | Адрес электронной почты пользователя. |
| пароль | обязательные | Пароль пользователя. |
| scope | необязательно | Список областей с разделителями-пробелами. |
Ответ об успешном прохождении проверки подлинности
Ниже приведен пример успешного ответа маркера:
| Параметр | Описание |
|---|---|
| token_type | Всегда имеет значение Bearer. |
| scope | Если маркер успешно возвращается, этот параметр будет содержать список областей, для которых этот маркер доступа является допустимым. |
| expires_in | Срок действия прилагаемого маркера доступа (в секундах). |
| access_token | Выдается для запрошенных областей. |
| id_token | JSON Web Token (JWT). Приложение может расшифровать сегменты этого маркера, чтобы запросить сведения о выполнившем вход пользователе. Эти значения можно кэшировать и (или) отображать в приложении, но их не следует использовать в любых процессах авторизации или организации безопасности. |
| refresh_token_expires_in | Срок действия прилагаемого маркера обновления (в секундах). |
| refresh_token | Выдается, если исходный параметр области включает значение offline_access. |
Маркер обновления можно использовать для получения новых маркеров доступа и обновления через тот же поток, описанный выше в разделе о потоке предоставления кода проверки подлинности.
Поток кода устройства
С помощью предоставления кода устройства пользователи могут входить на устройства с ограниченными возможностями для ввода данных, например на интеллектуальный телевизор, устройство IoT или принтер. Чтобы реализовать этот поток, на устройстве пользователю предлагается открыть определенную веб-страницу в браузере на другом устройстве и выполнить вход. После входа пользователя устройство получает маркеры доступа и маркеры обновления, если они нужны.
Схема протокола
Весь поток кода устройства выглядит примерно так, как на следующей схеме. Каждый из этих шагов мы опишем далее в этой статье.
Запрос авторизации устройства
Клиент должен сначала обратиться к серверу проверки подлинности и получить код для устройства и пользователя, который используется для запуска проверки подлинности. Клиент получает этот запрос от конечной точки /devicecode. В этом запросе клиент должен также указать разрешения, которые нужно получить от пользователя. С момента отправки этого запроса у пользователя будет всего 15 минут на выполнение входа (типичное значение параметра expires_in), поэтому запрос лучше отправлять только после того, как пользователь подтвердил готовность выполнить вход.
| Параметр | Условие | Описание |
|---|---|---|
| client_id | обязательные | Идентификатор приложения (клиента), который AD FS назначает приложению. |
| scope | необязательно | Список областей с разделителями-пробелами. |
Ответ на запрос авторизации устройства
Успешный ответ содержит объект JSON с информацией, требуемой пользователю для выполнения входа.
Проверка подлинности пользователя
Получив значения user_code и verification_uri, клиент отображает их пользователю вместе с инструкциями по входу через браузер на мобильном телефоне или компьютере. Кроме того, клиент может предоставить QR-код или другой аналогичный механизм для отображения verfication_uri_complete с одновременным вводом user_code. Пока пользователь выполняет проверку подлинности по verification_uri, клиент должен регулярно запрашивать маркер через конечную точку /token с указанием кода устройства (device_code).
| Параметр | обязательные | Описание |
|---|---|---|
| grant_type | обязательные | Должен иметь значение urn:ietf:params:oauth:grant-type:device_code. |
| client_id | обязательные | Должен совпадать с client_id, указанным в первом запросе. |
| code | обязательные | Значение device_code, возвращенное по запросу авторизации устройства. |
Ответ об успешном прохождении проверки подлинности
Успешный ответ на запрос маркера будет выглядеть следующим образом:
| Параметр | Описание |
|---|---|
| token_type | Всегда имеет значение Bearer. |
| scope | Если маркер успешно возвращается, здесь будет содержаться список областей, для которых этот маркер доступа является допустимым. |
| expires_in | Срок действия прилагаемого маркера доступа (в секундах). |
| access_token | Выдается для запрошенных областей. |
| id_token | Выдается, если исходный параметр области включал значение области openid. |
| refresh_token | Выдается, если исходный параметр области включает значение offline_access. |
| refresh_token_expires_in | Срок действия прилагаемого маркера обновления (в секундах). |
Связанное содержимое
Полный список пошаговых руководств по использованию соответствующих потоков вы найдете на странице о разработке для AD FS.