- OAuth 2
- Алексей Добрый
- Роль
- Стороннее приложение: Клиент
- API: сервер ресурсов
- Авторизация Сервер
- Пользователь, владелец ресурса
- Создать приложение
- Перенаправление URI
- clientid, secret
- Авторизация
- Приложение веб-сервера
- Authorization
- Получить токен доступа
- Одностраничные приложения (SPA)
- Авторизация
- Получите доступ к token
- Мобильные приложения
- Авторизация
- Другие типы
- Пароль
- Доступ к приложению
- Запросы
- Поток кода авторизации OAuth 2.0 и платформа Microsoft Identity
- Диаграмма протокола
- URI конфигурации перенаправления требуется для одного страница приложения
- Запрос кода авторизации
- Успешный ответ
- Сообщение об ошибке
- Коды ошибок конечной точки авторизации
- Запрос ID-токена или гибридная передача
- Успешный ответ
- Активировать код токена доступа
- Запросите токен доступа с помощью client_secret
- Запрос маркера доступа с сертификатом учетных данных
- Успешный ответ
- Сообщение об ошибке
- Коды ошибок конечные точки токена
- Использование токена доступа
- Продлить токен доступа
- Успешный ответ
- Сообщение об ошибке
OAuth 2
Алексей Добрый
Роль
Стороннее приложение: Клиент
Клиент — это приложение , который пытается получить доступ к учетной записи пользователя. Для этого клиенту требуется авторизация от пользователя.
API: сервер ресурсов
Сервер ресурсов — это сервер API, который используется для доступа к пользовательской информации.
Авторизация Сервер
Это сервер, предоставляющий интерфейс, в котором пользователь разрешает или отклоняет запросы на разрешение. В большинстве реализаций это может быть тот же сервер, что и API. В крупных проектах это, скорее всего, будет отдельный сервер.
Пользователь, владелец ресурса
Владелец ресурса — это фактический пользователь, который предоставляет доступ к некоторой его информации.
Создать приложение
Когда вы начинаете использовать процесс OAuth, вам необходимо зарегистрировать новое приложение в службе. При регистрации обычно запрашивается общая информация, такая как имя, веб-сайт, логотип и т. д. Кроме того, необходимо указать URI перенаправления, который будет использоваться для перенаправления пользователей на веб-сервер, браузер или мобильное приложение.
Перенаправление URI
Сервис перенаправляет пользователя только на зарегистрированный идентификатор URI, чтобы снизить риск некоторых атак. Любое перенаправление HTTP должно выполняться через HTTPS. Это защищает токены от перехвата в процессе авторизации. Нативные приложения могут регистрировать URI перенаправления, используя собственную схему URL приложения, которая может выглядеть примерно так: demoapp://redirect .
clientid, secret
После регистрации приложения вы получите Client ID (UID) и секрет. Идентификатор клиента является общедоступной информацией и используется открыто для создания URL-адреса или включения его в код JavaScript приложения на странице. Секрет должен оставаться конфиденциальным и не должен разглашаться. Если приложение не имеет возможности хранить секрет в безопасности, например страница SPA или собственное приложение, тогда секрет не используется, и в идеале секрет не должен раскрываться таким приложениям.
Авторизация
Первым шагом является запрос авторизации пользователя. Для браузеров и мобильных приложений это обычно предоставляемый сервисом интерфейс.
OAuth 2 предоставляет несколько типов авторизации для разных вариантов использования
- Авторизация кода для мобильных приложений, браузерных приложений и браузерных приложений
- Пароль для входа в систему с использованием имени пользователя и пароля ((только для пользовательских приложений)
- Учетные данные клиента для приложений без ассоциации пользователей
- Неявный — этот тип ранее рекомендовался для несекретных клиентов, но был заменен кодом авторизации PKCE.
Приложение веб-сервера
Серверные веб-приложения являются основным типом приложений для работы с OAuth.Приложения написаны на серверных языках и работают на сервере, где находится исходный код. не является общедоступным. Это означает, что приложение может использовать секрет клиента для связи с сервером авторизации?
Authorization
- response_code=code — указывает, что сервер должен вернуть код авторизации
- client_id — ID созданного нами приложения в сервисе
- redirect_uri: URL, на который будет перенаправлен пользователь после завершения авторизации
- область действия — область доступа
- состояние — случайная строка
Сервис должен отображать диалог с возможностью предоставить или запретить доступ. Если пользователь разрешает доступ, сервис перенаправляет его на сайт с кодом авторизации
- код — код авторизации
- статус — строка запроса авторизации
Нам нужно проверить статус, чтобы убедиться, что это «наш» запрос, мы его инициировали. Обычно значение состояния сохраняется в файле cookie или сеансе и сравнивается при получении ответа. Это гарантирует, что точку перенаправления нельзя будет обмануть, отправив произвольные коды авторизации.
Получить токен доступа
Чтобы получить токен, отправьте запрос POST с указанием полученного кода авторизации
- grant_type=authorization_code — введите
- code=AUTH_CODE — код, полученный от сервера авторизации
- redirect_uri=REDIRECT_URI : должен соответствовать URI, указанному в конфигурации приложения в the service
- client_id=CLIENT_ID — ID приложения в сервисе
- client_secret=CLIENT_SECRET — так как запрос отправляется со стороны сервера, мы можем включить секрет
Одностраничные приложения (SPA)
Приложение SPA работает полностью в контексте браузера. после загрузки кода серверного приложения. Код полностью доступен из браузера, а это значит, что нет возможности хранить конфиденциальные данные, пароли, коды и т. д. Использовать Секрет невозможно. Поток авторизации основан на потоке кода авторизации, но с добавлением динамически генерируемых секретов для каждого запроса. Также известен как расширение PKCE.
Ранее. для таких случаев рекомендовалось использовать неявный поток, который возвращал токен доступа сразу после перенаправления и не имел шага получения токена. Текущая рекомендация — использовать поток кода авторизации без использования секретного ключа.
Авторизация
Создайте случайную строку из 43–128 символов, затем сгенерируйте безопасный для URL хэш SHA256 base64 на основе этой строки. Исходная строка будет называться code_verifier , версия хэша code_challenge
Например, строка, code_verifier
Хэш, SHA256, base64-encoded, code_challenge
Входная строка будет иметь вид this
- response_type=code — сервер должен возвращать код авторизации
- client_id — идентификатор приложения
- redirect_uri — адрес перенаправления
- диапазон — область доступа
- статус — случайная строка для проверки запроса
- code_challenge — хэш на основе случайной строки, временный секрет
- code_challenge_method — метод хеширования
Когда пользователь предоставляет разрешение на доступ, перенаправление будет выглядеть следующим образом
После проверки подлинности состояния вы можете запросить токен.
Получите доступ к token
Теперь мы отправляем POST-запрос с кодом авторизации, но в параметрах вместо секрета приложения добавляем созданный выше секрет PKCE
Здесь CODE_VERIFIER — это секрет, который мы создали в начале . Сервер перехватывает CODE_VERIFIER и сравнивает его с ранее отправленным кодом.
Мобильные приложения
Как и браузерные приложения, мобильные приложения не могут обеспечить конфиденциальность при сохранении секретности приложения. Поэтому безопасное использование секретного ключа невозможно.
Авторизация
Пользователь должен быть перенаправлен в родное приложение сервиса на телефоне или на мобильную страницу сервиса. Приложение может зарегистрировать нестандартную схему, такую как my-app://, для запуска нативного приложения.
Например, если установлено приложение Facebook, адрес авторизации может быть таким
Другие типы
Пароль
OAuth предлагает напрямую использовать имя пользователя и пароль для получения токена доступа. В этом случае приложение получает учетные данные пользователя напрямую, а это означает, что этот доступ должны использовать только сервисные приложения, являющиеся частью сервиса. Например, собственное приложение Twitter может использовать тип пароля для входа пользователя в мобильные и настольные приложения.
Чтобы получить токен, просто отправьте простой запрос POST
- grant_type=password — введите
- username=USERNAME — настоящее имя пользователя
- password=PASSWORD — реальный пароль пользователя
- client_id =CLIENT_ID — идентификатор приложения в сервисе
Сервер отвечает токеном доступа.
Опять же, секрет клиента не включен в запрос, что указывает на то, что основное использование потока паролей — мобильное и веб-приложения, где невозможно безопасно хранить секретный код.
Доступ к приложению
В некоторых случаях приложениям требуется доступ с помощью токена, чтобы действовать от своего имени, а не от имени пользователя. Например, для сбора статистики или обновления настроек. Для таких случаев используется последовательность client_credentials
. В этом случае предполагается, что запросы выполняются на стороне сервера.
Запросы
После получения токена он может запрашивать защищенные данные
Все запросы должны выполняться через https, чтобы предотвратить захват и подделку токенов.
Источник
Поток кода авторизации OAuth 2.0 и платформа Microsoft Identity
Приложения, установленные на устройстве, могут использовать код авторизации OAuth 2.0 для доступа к защищенным ресурсам, таким как веб-API. Внедрив OAuth 0.2 и Open ID Connect (OIDC) на платформе Microsoft Identity, мобильные устройства и настольные приложения могут добавить вход в систему и доступ к API.
В этой статье описывается, как запрограммировать протокол непосредственно в приложении, используя любой язык. . . По возможности мы рекомендуем использовать поддерживаемые библиотеки проверки подлинности Майкрософт (MSAL) для получения токенов и вызова безопасных веб-API. Дополнительные сведения см. в примерах приложений, которые они используют. MSAL.
Описание потока кода авторизации OAuth 2.0 см. в разделе 4.1 спецификации OAuth 2.0. При использовании OIDC этот поток выполняет аутентификацию и авторизацию для большинства типов приложений. Эти типы включают одностраничные приложения, веб-приложения и изначально установленные приложения. Этот поток гарантирует, что приложения безопасно получат access_token для использования ресурсов, защищенных платформой удостоверений Майкрософт. Приложения могут обновлять маркеры обновления и получать различные маркеры доступа и маркеры идентификации для вошедшего в систему пользователя.
Попробуйте этот и другие запросы на Postman — не забудьте обменяться маркерами и маркерами! !
Диаграмма протокола
На этой диаграмме представлен обзор потока аутентификации для приложения.
URI конфигурации перенаправления требуется для одного страница приложения
Поток кода авторизации для одностраничных приложений требует дополнительной настройки. Следуйте инструкциям по созданию одностраничных приложений, чтобы правильно пометить URI перенаправления как включенный общий доступ к ресурсам (CORS). Чтобы обновить существующий URI перенаправления для включения CORS, откройте редактор манифеста и задайте для поля типа URI перенаправления значение spa в разделе answerUrlsWithType. Вы также можете выбрать URI перенаправления в Аутентификация > Интернет и выберите URI для переноса с помощью потока кода авторизации.
spa Тип перенаправления совместим с потоком по умолчанию. Приложения, которые в настоящее время используют неявный поток для получения токенов, они могут безопасно перейти на тип URI перенаправления spa и продолжать использовать поток по умолчанию.
Если вы попытаетесь использовать поток кода авторизации без настройки CORS для URI перенаправления, в консоли появится следующее сообщение об ошибке. :
Если это так, перейдите к журналу приложений и обновите URI перенаправления, чтобы приложение записывало spa.
Приложения не могут использовать URI перенаправления spa. с потоками не-SPA, такими как собственные потоки приложений или потоки учетных данных клиента. В целях обеспечения безопасности и передового опыта платформа Microsoft Identity Platform вернет ошибку, если вы попытаетесь использовать URI перенаправления spa без заголовка источника. Точно так же платформа идентификации Microsoft также предотвращает использование учетных данных клиента, когда присутствует заголовок Origin, чтобы гарантировать, что секреты не используются в браузере.
Запрос кода авторизации
Начинается поток кода авторизации, когда клиент перенаправляет пользователя на конечную точку /authorize. В этом запросе клиент запрашивает у пользователя разрешения openid , offline_access и https://graph.microsoft.com/mail.read.
Некоторые разрешения ограничены администраторами, например, запись данных в каталог с помощью Directory.ReadWrite.All . Если приложение запрашивает доступ к любому из этих разрешений у бизнес-пользователя, отображается сообщение об ошибке, в котором говорится, что пользователь не может предоставить разрешение приложению. Чтобы запросить доступ к областям только для администратора, вы должны обратитесь к глобальному администратору напрямую. Дополнительную информацию см. в разделе Разрешения только для администратора.
Если не указано иное, для необязательных параметров нет значений по умолчанию. Однако для запроса, в котором отсутствуют необязательные параметры, определено поведение по умолчанию. По умолчанию текущий пользователь будет входить в систему немедленно, нескольким пользователям будет показан выбор учетной записи, и ни одному вошедшему пользователю не будет показана страница входа.
Пожалуйста, выберите ссылку ниже, чтобы выполнить этот запрос. После авторизации браузер будет перенаправлен на http://localhost/myapp/, где адресная строка — это код. https://login.microsoftonline.com/common/oauth2/v2.0/authorize.
Параметр | Обязательный или необязательный | Описание |
---|---|---|
арендатор | обязательный | Значение |
client_id | обязательный | Идентификатор приложения (клиента) Назначается вашему приложению Azure Применение функции регистрации портала. |
response_type | обязательный | Должен содержать код для потока кода авторизации. Вы также можете включить id_token или токен при использовании гибридного потока. |
redirect_uri | требуется | redirect_uri для приложения, через которое вы можете отправлять и получать ответы на запросы аутентификации. Он должен точно совпадать с одним из URI перенаправления, зарегистрированных на портале, но должен быть в форме закодированного URL. Для нативных и мобильных приложений следует использовать одно из рекомендуемых значений: https://login.microsoftonline.com/common/oauth2/nativeclient (для приложений, использующих нативные браузеры) или http://localhost (для приложений, использующих нативные браузеры). |
область действия | обязательное | Список полей, разделенных пробелами, для которых требуется согласие пользователя. Для части запроса /authorize этот параметр может включать несколько ресурсов. Это значение позволяет приложению соглашаться на вызов различных веб-API. |
response_mode | рекомендуется | Указывает, как платформа идентификации должна возвращать приложению запрос тега. |
-query — значение по умолчанию при запросе токена доступа. Введите код в качестве параметра строки запроса в URI перенаправления. Параметр запроса не поддерживается, когда маркер ID запрашивается с использованием неявного потока.
— фрагмент: значение по умолчанию при запросе маркера идентификатора с использованием неявного потока. Также поддерживается по запросу на только код .
— form_post: создайте запрос POST, содержащий код для URI перенаправления. Поддерживается при запросе кода.
— Если prompt=login, пользователь должен ввести данные для входа при появлении запроса. ССО не будет работать.
— Значение prompt=none является противоположным случаем. Гарантирует, что пользователю не будут отображаться интерактивные подсказки. Если запрос автоматически завершается ошибкой при едином входе, платформа идентификации Майкрософт возвращает ошибку, требующую взаимодействия.
— если вы установите prompt=consent , пользователю будет представлено диалоговое окно согласия OAuth при входе в систему с просьбой предоставить разрешение на запрос.
— prompt =select_account прерывает SSO, позволяя вам выбрать учетную запись из списка всех учетных записей в сеансе, любую сохраненную учетную запись или полностью использовать другую учетную запись.
Если этот параметр не указан, Предполагается, что code_challenge имеет необработанный текстовый формат, если установлен code_challenge. Microsoft Identity Platform поддерживает S256 и необработанные данные. Дополнительные сведения см. в документе RFC PKCE. Этот параметр требуется для одностраничных приложений, использующих поток кода авторизации.
На текущем этапе пользователю предлагается ввести учетные данные и завершить аутентификацию. Платформа Microsoft Identity также проверяет, согласился ли пользователь предоставить разрешения, указанные в параметре запроса области действия. Если пользователь не предоставил какие-либо из этих разрешений, конечная точка запросит их для них. См. разрешения и согласие для платформы Microsoft Identity.
После аутентификации пользователя и предоставления разрешения платформа Microsoft Identity возвращает ответ на указанный redirect_uri в приложение, используя метод, указанный в параметре response_mode.
Успешный ответ
В этом примере показан успешный ответ с response_mode=query :
Параметр | Описание |
---|---|
code | Значение author_code, запрошенное приложением. Приложение может использовать этот код авторизации для запроса маркера доступа к целевому ресурсу. Коды авторизации имеют короткий срок действия. и обычно истекает примерно через 10 минут. |
состояние | Если параметр состояния включен в запрос, такое же значение должно быть включено в ответ на этот запрос. Приложение должно проверить соответствие значений параметра «состояние» в запросе и ответы. |
Вы также можете получить токен ID, если запросите его и при регистрации приложения включено неявное предоставление. Такое поведение иногда называют гибридным потоком . Используется такими платформами, как ASP.NET.
Сообщение об ошибке
Сообщения об ошибках также могут отправляться на redirect_uri для правильной обработки приложения:
Параметр | Описание |
---|---|
ошибка | Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок. и они реагируют на ошибки. Эта часть ошибки предназначена для того, чтобы приложение могло правильно отреагировать на ошибку, но не объясняет подробно, почему произошла ошибка. |
error_description | Конкретное описание сообщения об ошибке, по которому разработчик может определить причину ошибки проверки. Этот раздел ошибок содержит большую часть полезной информации о причинах ошибки . |
Коды ошибок конечной точки авторизации
В следующей таблице описаны различные коды ошибок, которые могут быть возвращены в параметре ошибки ошибки. ответ.
Код ошибки | Описание | Действия клиента |
---|---|---|
invalid_request | Ошибка протокола, например, требуется отсутствующий параметр. | Пожалуйста, исправьте запрос и отправьте его повторно. Это ошибка разработки, которая обычно выявляется при первичном тестировании. |
author_client | Клиентское приложение не может запросить код авторизации. | Эта ошибка обычно возникает, если клиентское приложение не зарегистрировано в Azure AD или не добавлено в клиент Azure AD пользователя. Приложение может предложить пользователю инструкции по установке приложения и его добавлению в Azure AD. |
access_denied | Использование запрещено владельцем ресурса | Клиентское приложение может уведомить пользователя о том, что для продолжения требуется согласие пользователя. |
response_type_not_supported | Сервер авторизации не поддерживает тип ответа в запросе. | Пожалуйста, исправьте запрос и отправьте его повторно. Это ошибка разработки, которая обычно выявляется во время первоначального тестирования. Если он появляется в гибридном потоке, это означает, что должна быть включена опция неявного предоставления маркера идентификатора для регистрации клиентского приложения. |
server_error | На сервере произошла непредвиденная ошибка. | Повторите запрос. Эти ошибки могут возникать из-за временных условий. Клиентское приложение может сообщить, что его ответ был задержан из-за временной ошибки. |
временно_недоступно | Сервер временно занят и не может обработать запрос. | Повторите запрос. Клиентское приложение может сообщить, что его ответ задержан из-за временного условия. |
invalid_resource | Целевой ресурс недействителен, поскольку не существует. Azure AD не может найти ресурс или он неправильно настроен. | Это означает, что ресурс не существует или не настроен в арендаторе. Приложение может предложить пользователю установить приложение и добавить его в Azure AD. |
login_required | Слишком много пользователей или пользователи не найдены. | Клиент запросил автоматическую аутентификацию (prompt=none), но пользователь не найден. Эта ошибка может означать, что в сеансе есть несколько активных пользователей или что пользователей нет. Восточная ошибка учитывает выбранного клиента. Например, если у вас есть две учетные записи Azure AD и одна учетная запись Майкрософт и вы выбрали «Потребители», будет работать автоматическая проверка подлинности. |
interaction_required | Запрос требует взаимодействия с | Требуется дополнительный этап проверки подлинности или согласие. Повторить запрос без prompt=none . |
Запрос ID-токена или гибридная передача
Чтобы приложение знало, кто оно перед активацией кода авторизации, оно часто также по запросу запрашивает идентификационный токен для кода авторизации. Этот подход называется гибридным потоком , поскольку неявное предоставление смешивается с потоком код авторизации.
Гибридный поток обычно используется в веб-приложениях, которым необходимо отображать страницу пользователю без блокировки кода. активация, особенно в ASP.NET. Эта модель снижает задержку в традиционных и одностраничных веб-приложениях.
Гибридный поток похож на описанный выше поток кода авторизации, но включает три дополнения. Все эти дополнения необходимы для запроса маркера идентификатора: новые области действия, новый тип ответа и новый параметр запроса одноразового номера.
Параметр обновлен | Требуется или необязательный | Описание |
---|---|---|
response_type | обязательный | Добавьте id_token, чтобы сообщить серверу, что приложение должно иметь идентификатор токен в конечной точке ответа/авторизации. |
диапазон | обязательный | Для токенов идентификатора обновите этот параметр, чтобы включить диапазоны токенов идентификатора: openid и, возможно, профиль и адрес электронной почты. |
не требуется | Значение, включенное в запрос и сгенерированное приложением, включенным в id_token в качестве объявления. Приложение может проверить это значение, чтобы смягчить атаки воспроизведения токена. Значение обычно представляет собой случайно сгенерированную уникальную строку, которую можно использовать для идентификации источника запроса. | |
response_mode | рекомендуемый | Указывает метод, которым будет отправлено в приложение. По умолчанию код авторизации или фрагмент запрашивается только в том случае, если запрос содержит id_token response_type , как указано в спецификации OpenID. Приложениям рекомендуется использовать form_post , особенно когда http://localhost используется в качестве URI перенаправления. |
Использование фрагмента в качестве режима ответа вызывает проблемы для веб-приложений, считывающих код перенаправления. Браузеры не передают фрагмент на веб-сервер. В таких ситуациях приложения должны использовать режим ответа form_post, чтобы убедиться, что все данные отправлены на сервер.
Успешный ответ
В этом примере показан успешный ответ с response_mode=fragment:
Параметр | Описание |
---|---|
код | Код авторизации, запрошенный запрос. Приложение может использовать код авторизации для запроса маркера доступа к целевому ресурсу. Токены авторизации короткие и обычно истекают примерно через 10 минут. |
id_token | Идентификационный токен для пользователя, выданный неявным предоставлением . Он содержит специальное утверждение c_hash, которое является хэшем кода в том же утверждении. |
состояние | Если в запросе включен параметр состояния, такое же значение должно быть включено в ответ на этот запрос. Приложение должно проверить, совпадают ли значения параметра «состояние» в запросе и ответе. |
Активировать код токена доступа
Все конфиденциальные клиенты могут использовать секреты клиента или учетные данные сертификата. Симметричные общие секреты генерируются платформой удостоверений Майкрософт. Учетные данные сертификата — это асимметричные ключи, отправленные разработчиком. Дополнительные сведения см. в разделе Учетные данные сертификата для аутентификации приложения Microsoft Identity Platform.
Рекомендуется использовать учетные данные сертификата для повышения безопасности. Общедоступные клиенты, в том числе собственные приложения и одностраничные приложения, не должны использовать секреты или сертификаты при активации кода авторизации. Всегда следите за тем, чтобы URI перенаправления включали тип приложения и были уникальными.
Запросите токен доступа с помощью client_secret
После получения кода авторизации и разрешения от пользователя вы можете использовать этот код для получения токен доступа к нужным ресурсам. Чтобы получить код, отправьте запрос POST на конечную точку /token:
Параметр | Обязательный или необязательный | Описание |
---|---|---|
арендатор | требуется | Значение |
client_id | обязательно | client_id приложение (клиент) , назначенное вашему приложению на странице регистрации приложения на портале Azure. |
область действия | необязательно | Список областей действия, разделенных пробелами. Все домены должны быть из одного источника, а также с доменами OIDC (профиль, openid, электронная почта). См. разрешения и согласие для платформы удостоверений Майкрософт. Этот параметр является расширением потока кода авторизации Microsoft, который позволяет приложениям объявлять ресурсы, для которых они хотят получить маркер, во время активации маркера. |
code | обязательный | Значение авторизации_кода, полученное в первой части потока. |
redirect_uri | обязательно | То же значение redirect_uri, которое использовалось для получения кода авторизации. |
grant_type | обязательно | Должен быть author_code для потока кода авторизации. |
code_checker | рекомендуется | Тот же code_checker, который использовался для получения кода авторизации. Обязательно, если в запросе кода авторизации использовался PKCE. Дополнительные сведения см. в описании PKCE RFC. |
client_secret | требуется для конфиденциальных веб-приложений | Секретный ключ приложения, сгенерированный на портале регистрации для приложения. Не используйте секретный ключ приложения в своих app или в одностраничном приложении, потому что client_secret нельзя безопасно хранить на устройствах или веб-сайтах. Требуется для веб-приложений и веб-API с возможностью безопасного хранения client_secret на сервере. Как и во всех описанных здесь параметрах, секрет клиента перед отправкой должен быть закодирован в URL-адресе. Этот шаг обычно выполняется с помощью SDK. Дополнительные сведения о кодировании URI см. в разделе Спецификации синтаксиса URI. Также поддерживается базовый шаблон аутентификации вместо предоставления учетных данных в заголовке авторизации в соответствии с RFC 6749. |
Запрос маркера доступа с сертификатом учетных данных
Параметр | Обязательный или необязательный | Описание |
---|---|---|
арендатор | требуется | Значение |
client_id | обязательно | Идентификатор приложения (клиента) , назначенный вашему приложению на странице регистрации приложения Azure Портал. |
область действия | необязательно | Список областей действия, разделенных пробелами. Все домены должны быть из одного источника, а также с доменами OIDC (профиль, openid, электронная почта). Смотрите тему для получения дополнительной информации Авторизация и согласие для платформы Microsoft Identity. Этот параметр является расширением Microsoft для потока кода авторизации. Это расширение позволяет приложениям объявлять ресурсы, которые они хотят использовать при активации токена. |
code | обязательный | Значение авторизации_кода, полученное в первой части потока. |
redirect_uri | обязательно | То же значение redirect_uri, которое использовалось для получения кода авторизации. |
grant_type | обязательно | Должен быть author_code для потока кода авторизации. |
code_verifier | рекомендуется | Тот же code_verifier, который использовался для получения авторизации_кода. Обязательно, если в запросе кода авторизации использовался PKCE. Дополнительные сведения см. в документе RFC PKCE. |
client_assertion_type | требуется для конфиденциальных веб-приложений | Чтобы использовать учетные данные сертификата, необходимо установить urn: ietf :params:oauth:client -assertion- тип: jwt-носитель. |
client_assertion | требуется для конфиденциальных веб-приложений | Утверждение (веб-маркер JSON), сгенерированное и подписанное сертификатом, зарегистрированным в качестве учетных данных для приложения . Прочтите об учетных данных сертификата, чтобы узнать, как написать сертификат и настроить формат выражения. |
Обратите внимание, что параметры те же, что и при запросе общего секрета, за исключением того, что параметр client_secret заменен двумя параметрами: client_assertion_type и client_assertion .
Успешный ответ
Ниже приведен пример успешного ответа токена:
Параметр | Описание |
---|---|
access_token | Запрошенный токен доступа. Приложение может использовать этот токен для аутентификации на безопасном ресурсе, таком как веб-API. |
token_type | Указывает значение типа токена. Единственный тип, поддерживаемый Azure AD, — это носитель |
expires_in | Срок действия токена доступа (в секундах). |
диапазон | Диапазоны, для которых действителен access_token. Дополнительный элемент. Этот параметр не является стандартным, и если его не указать, токен будет использоваться для доменов, запрошенных на начальном этапе последовательности. |
refresh_token | Токен обновления OAuth 2.0 . Приложение может использовать этот токен для получения дополнительных токенов доступа после истечения срока действия текущей закладки. Токены обновления имеют длительный срок действия. Они могут поддерживать доступ к ресурсам в течение более длительных периодов времени. Дополнительные сведения о том, как обновить маркер доступа, см. в разделе Обновление маркера доступа далее в этой статье. Примечание. При условии только если требуется область автономного доступа. |
id_token | веб-токен JSON. Приложение может расшифровывать сегменты этого токена и запрашивать информацию о вошедшем в систему пользователе. Приложение может хранить и отображать значения, а конфиденциальные клиенты могут использовать этот токен для авторизации. См. ссылку id_token для получения дополнительной информации. Примечание. Предоставляется только в том случае, если был запрошен домен openid. |
Сообщение об ошибке
Пример сообщения об ошибке:
Параметр | Описание |
---|---|
ошибка | Строка кода ошибки, которую можно использовать для классификации типов возникающих ошибок. , и реагировать на ошибки. |
error_description | Особое сообщение об ошибке, которое разработчик может использовать для определения причины сбоя проверки. |
error_codes | Список кодов ошибок, характерных для службы маркеров безопасности, которые могут помочь в диагностике. |
метка времени | Время ошибки. |
trace_id | Уникальный идентификатор запроса, который может помочь в диагностике. |
корреляция_ид | Уникальный идентификатор запроса, который может помочь диагностировать несколько компонентов. |
Коды ошибок конечные точки токена
Код ошибки | Описание | Действие клиента |
---|---|---|
Invalid_Request | Ошибка протокола, например отсутствие обязательного параметра. | Исправьте приложение или регистрацию приложения и снова отправьте приложение. |
invalid_grant | Неверный или устаревший код авторизации или аутентификатор PKCE. | Повторите запрос к конечной точке /authorize и проверьте правильность параметра code_verifier. |
author_client | У вас нет прав на использование этого типа предоставления аутентификации при аутентификации аутентифицированного клиента. | Эта ошибка обычно возникает, если клиентское приложение не зарегистрировано в Azure AD или не добавлено в клиент Azure AD пользователя. Приложение может предложить пользователю установить приложение и добавить его в Azure AD. |
invalid_client | Ошибка аутентификации клиента. | Неверные учетные данные клиента. Чтобы решить эту проблему, администратор приложения должен обновить учетные данные. |
unsupported_grant_type | Сервер авторизации не поддерживает тип предоставления. | Измените тип гранта в запросе. Этот тип ошибки должен возникать только во время разработки и должен быть обнаружен во время начального тестирования. |
invalid_resource | Цель ресурс недействителен, поскольку он не существует. Azure AD не может найти ресурс или он неправильно настроен. | Этот код указывает, что ресурс, если он существует, не настроен в арендаторе. Приложение может предложить пользователю инструкции по установке приложения и его добавлению в Azure AD. |
взаимодействие_требуется | Повторите запрос /authorize с теми же областями. | |
временно_недоступно | Сервер временно занят и не может обработать запрос. | Повторите запрос через некоторое время. Клиентское приложение может сообщить, что его ответ задержан из-за временного условия. |
accept_required | Запрос требует согласия пользователя. Эта ошибка не является стандартной. Обычно он возвращается только для конечной точки /authorize в соответствии со спецификацией OIDC. Возвращается параметром области в потоке активации кода, который запрашивает отсутствие разрешений у клиентского приложения. | Клиент должен отправить пользователя обратно в конечную точку /authorize с правильной областью действия, чтобы разрешить авторизацию. |
invalid_scope | Приложение запросило недопустимую область действия. | Измените значение параметра области действия в запросе проверки на допустимое значение. |
Одностраничные приложения могут показать ошибку invalid_request, указывающую, что обмен токенами из разных источников разрешен только для клиентов «одностраничного приложения». одна страница». Это означает, что URI перенаправления, используемый для запроса токена, не помечен как URI перенаправления spa. Дополнительные сведения о том, как включить этот поток, см. в разделе Этапы регистрации приложения.
Использование токена доступа
Если вы успешно получили access_token, вы можете использовать этот токен в запросах от веб-API, включив его в заголовок авторизации.
Продлить токен доступа
У токенов доступа короткий срок действия. . Обновляйте их по истечении срока действия, чтобы сохранить доступ к ресурсам. Для этого отправьте еще один запрос POST на конечную точку /token и укажите refresh_token вместо code. Токены обновления действительны для всех разрешений, на которые клиент уже получил согласие. Например , токен обновления, выданный в запросе scope=mail.read, можно использовать для запроса нового токена доступа для scope=api://contoso.com/api/UseResource .
Токены обновления для веб-приложений и собственных приложений ace не имеют установленной даты истечения срока действия. Жетоны обновления обычно имеют относительно длительный срок службы. Однако в некоторых случаях токен обновления устарел или отозван, либо у вас недостаточно прав для этого. Ваше приложение должно ожидать и обрабатывать ошибки, возвращаемые стороной, выдавшей токен. Одностраничные приложения получают токен на 24 часа срок службы, который требует повторной проверки каждый день. Это можно сделать в iframe без вмешательства пользователя, если включены сторонние файлы cookie. Однако они должны выполняться на верхнем уровне (полная навигация по страницам или всплывающее окно) в браузерах без сторонних файлов cookie, таких как Safari.
Жетоны обновления не отменяются, если они используются для получения новых токенов доступа. Ожидается, что старый токен обновления будет удален. Спецификация OAuth 2.0 гласит: «Сервер авторизации может выдать новый токен обновления. В этом случае клиент должен удалить старый токен обновления и заменить его новым токеном обновления. Сервер авторизации может отозвать предыдущий токен обновления после выдачи новый токен обновления для клиента.»
Для токенов обновления, отправленных на URI перенаправления, зарегистрированный как spa, срок действия токена обновления истекает через 24 часа. Дополнительные токены обновления, полученные с первоначальным токеном обновления, наследуют это время истечения срока действия, поэтому приложение должно подготовиться к перезапуску потока кода проверки подлинности с интерактивной проверкой подлинности, чтобы получать новый токен обновления каждые 24 часа. Пользователям не нужно вводить учетные данные. Как правило, они даже не видят никаких признаков взаимодействия, просто перезагружают приложение. Чтобы просмотреть сеанс входа в систему, браузер должен посетить страницу входа в систему верхнего уровня. Это связано с функциями конфиденциальности браузера, которые блокируют сторонние файлы cookie.
Параметр | Тип | Описание |
---|---|---|
Арендатор | обязательный | Значение |
client_id | обязательно | Идентификатор приложения (клиента) , присвоенный вашему приложению функцией регистрации приложения из Портал Azure. |
grant_type | обязательно | Должен быть refresh_token для этой части потока кода авторизации. |
область действия | необязательно | Список областей действия, разделенных пробелами. Области, требуемые в этой ветви, должны быть эквивалентны или подмножеством областей, требуемых в исходной ветви запроса author_code. Если области, указанные в этом запросе, включают несколько серверов ресурсов, платформа удостоверений Майкрософт возвращает маркер для ресурса, указанного в первой области. См. Разрешения и согласие платформы Microsoft Identity. |
refresh_token | требуется | refresh_token, полученный во второй части потока. |
client_secret | требуется для веб-приложений | Секрет приложения, созданный вами на портале регистрации приложений. Его не следует использовать в нативном приложении, потому что при сохранении client_secret в устройство не может быть полностью безопасным. Требуется для веб-приложений и веб-API с возможностью безопасного хранения client_secret на сервере. Этот секретный ключ должен быть закодирован в URL-адресе. Дополнительные сведения см. в разделе Общие спецификации синтаксиса URI. |
Успешный ответ
Ниже приведен пример успешного ответа токена:
Параметр | Описание |
---|---|
access_token | Запрошенный токен доступа. Приложение может использовать этот токен для аутентификации на безопасном ресурсе, таком как веб-API. |
token_type | Указывает значение типа токена. Единственный тип, поддерживаемый Azure AD, — это Volume. |
expires_in | Срок действия токена доступа (в секундах). |
scope | Scope, для которых допустим access_token. |
refresh_token | Новый токен обновления OAuth 2.0. Вы должны заменить старый токен обновления вновь приобретенным токеном обновления, чтобы гарантировать, что срок действия токенов обновления истекает как можно дольше. Примечание. Предоставляется только в том случае, если требуется область автономного доступа. |
id_token | Неподписанный веб-токен JSON. Приложение может расшифровывать сегменты этого токена и запрашивать информацию о авторизованный пользователь. Эти значения могут кэшироваться и/или отображаться в приложении, но не должны использоваться ни в каком процессе авторизации или безопасности. Дополнительные сведения о id_token см. в статье Маркеры идентификаторов платформы Microsoft Identity. Примечание. Предоставляется только в том случае, если был запрошен домен openid. |
Не пытайтесь проверять или читать флаги в своем коде для любого API, которым вы не владеете, включая флаги в этом примере. Токены для служб Майкрософт могут использовать специальный формат, который не будет проверен как JWT, а также может быть зашифрован для потребителя (учетная запись Майкрософт). Хотя чтение токена является полезным инструментом для отладки и обучения, не полагайтесь на него в своем коде и не полагайтесь на информацию, относящуюся к токену, которая не предназначена для API, которым он управляет.
Сообщение об ошибке
Параметр | Описание |
---|---|
error | Строка кода ошибки, которую можно использовать классифицировать типы возникающих ошибок и реагировать на них. |
error_description | Особое сообщение об ошибке, которое позволяет разработчику определить причину сбоя проверки. |
Коды ошибок | Список кодов ошибок службы токенов безопасности, которые могут помочь в диагностике. |
метка времени | Произошло ошибка времени. |
trace_id | Уникальный идентификатор запроса, который может помочь в диагностике. |
корреляция_id | Уникальный идентификатор запроса, который может помочь диагностировать несколько компонентов. |
См. Коды ошибок конечной точки токена для описания кодов ошибок и рекомендуемых действий на клиенте.
Источник