Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Предупреждение
Это содержимое предназначено для более старой конечной точки Azure AD версии 1.0. Используйте платформу удостоверений Майкрософт для новых проектов.
Примечание.
Если вы не сообщаете серверу, какой ресурс планируется вызвать, сервер не будет запускать политики условного доступа для этого ресурса. Поэтому для активации MFA необходимо включить ресурс в URL-адрес.
Azure Active Directory (Azure AD) использует OAuth 2.0 для авторизации доступа к веб-приложениям и веб-API в клиенте Azure AD. Это руководство независимо от языка и описывает, как отправлять и получать HTTP-сообщения без использования любой из наших библиотек с открытым кодом.
Описание потока кода авторизации OAuth 2.0 см. в разделе 4.1 спецификации OAuth 2.0. Он используется для выполнения проверки подлинности и авторизации в большинстве типов приложений, включая веб-приложения и собственные установленные приложения.
Регистрация приложения в клиенте AD
Сначала зарегистрируйте приложение в клиенте Azure Active Directory (Azure AD). Это даст вам идентификатор вашего приложения, а также позволяет ему получать токены.
Войдите на портал Azure.
Выберите арендатора Azure AD, выбрав свою учетную запись в правом верхнем углу страницы, затем перейдите к навигации "Переключить каталог" и выберите соответствующего арендатора.
- Пропустите этот шаг, если у вас есть только один клиент Azure AD в учетной записи или вы уже выбрали соответствующий клиент Azure AD.
На портале Azure найдите и выберите Azure Active Directory.
В левом меню Azure Active Directory выберите Регистрация приложений, а затем выберите Новая регистрация.
Следуйте инструкциям и создайте новое приложение. Для этого руководства не имеет значения, будет ли это веб-приложение или общедоступное клиентское приложение (мобильное или настольное &), но если вы хотите получить конкретные примеры для веб-приложений или общедоступных клиентских приложений, ознакомьтесь с нашими быстрыми стартами .
- Имя служит названием вашего приложения и описывает его конечным пользователям.
- В разделе Поддерживаемые типы учетных записей выберите Accounts in any organizational directory and personal Microsoft accounts (Учетные записи в любом каталоге организации и личные учетные записи Майкрософт).
- Укажите URI перенаправления. Для веб-приложений это базовый URL-адрес приложения, в котором пользователи могут войти. Например,
http://localhost:12345. Для публичного клиента (мобильного и десктопа) Azure AD использует его для возврата ответов с токенами. Введите значение, определенное для приложения. Например,http://MyFirstAADApp.
После завершения регистрации Azure AD назначит приложению уникальный идентификатор клиента (идентификатор приложения ). Это значение необходимо в следующих разделах, поэтому скопируйте его на страницу приложения.
Чтобы найти приложение на портале Azure, выберите Регистрация приложений, а затем выберите Просмотр всех приложений.
Поток авторизации OAuth 2.0
На высоком уровне весь поток авторизации для приложения выглядит примерно так:
Запрос кода авторизации
Поток кода авторизации начинается с того, что клиент направляет пользователя к конечной точке /authorize . В этом запросе клиент указывает разрешения, необходимые пользователю. Конечную точку авторизации OAuth 2.0 для клиента можно получить, выбрав регистрации приложений > конечных точек на портале Azure.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
| Параметр | Тип | Описание |
|---|---|---|
| арендатор | Обязательно | Значение {tenant} в пути запроса можно использовать для того, чтобы контролировать, кто может входить в приложение. Допустимые значения — это идентификаторы клиента, например 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 или contoso.onmicrosoft.com или common для маркеров, независимых от клиента. |
| идентификатор клиента | Обязательно | Идентификатор приложения, назначенный приложению при регистрации в Azure AD. Это можно найти на портале Azure. Нажмите Azure Active Directory в боковой панели служб, нажмите Регистрация приложенийи выберите приложение. |
| тип_ответа | Обязательно | Должен содержать code для потока кода авторизации. |
| перенаправление_uri | рекомендуется | Redirect_uri вашего приложения, где ваше приложение может отправлять и получать ответы проверки подлинности. Он должен точно соответствовать одному из redirect_uris, зарегистрированных на портале, но при этом должен быть закодирован в формате URL. Для собственных мобильных приложений & следует использовать значение https://login.microsoftonline.com/common/oauth2/nativeclientпо умолчанию. |
| режим_ответа | необязательно | Указывает метод, с помощью которого результирующий маркер будет отправлен приложению. Возможные значения: query, fragment или form_post.
query предоставляет код в качестве параметра строки запроса в URI перенаправления. Если вы запрашиваете маркер идентификатора с помощью неявного потока, нельзя использовать query, как указано в спецификации openID . Если вы запрашиваете только код, можно использовать query, fragmentили form_post.
form_post выполняет POST, содержащий код на URI перенаправления. Значение по умолчанию query для потока кода. |
| государство | рекомендуется | Значение, включенное в запрос, которое также возвращается в ответе токена. Как правило, для предотвращения подделки межсайтовых запросовиспользуется генерируемое случайным образом уникальное значение. Состояние также используется для кодирования сведений о состоянии пользователя в приложении до того, как произошел запрос на аутентификацию, например, страницу или представление, на котором они находились. |
| ресурс | рекомендуется | URI идентификатора приложения для целевого веб-API (защитного ресурса). Чтобы найти URI идентификатора приложения, на портале Azure щелкните Azure Active Directory, щелкните регистрации приложений, откройте страницу настроек приложения, а затем щелкните Свойства. Это может быть также внешний ресурс, например https://graph.microsoft.com. Это необходимо в одном из запросов авторизации или токена. Чтобы уменьшить количество запросов на проверку подлинности, нужно включить его в запрос авторизации, чтобы гарантировать получение согласия от пользователя. |
| охват | игнорируется | Для приложений Azure AD версии 1 области должны быть статически настроены на портале Azure в разделе параметров приложенийи необходимые разрешения . |
| запрос | необязательно | Укажите тип необходимого взаимодействия с пользователем. Допустимые значения: логин: пользователю следует предложить повторно пройти аутентификацию. select_account: пользователю предлагается выбрать учетную запись, прервав единый вход. Пользователь может выбрать существующую учетную запись входа, ввести свои учетные данные для запоминаемой учетной записи или полностью использовать другую учетную запись. согласие: согласие пользователя было предоставлено, но его необходимо обновить. Пользователю должно быть предложено предоставить согласие. admin_consent: администратору необходимо предоставить согласие от имени всех пользователей в своей организации. |
| подсказка_для_входа | необязательно | Можно использовать для предварительной заполнения поля имени пользователя или электронной почты страницы входа для пользователя, если вы знаете свое имя пользователя заранее. Часто приложения используют этот параметр во время повторной проверки подлинности, уже извлекая имя пользователя из предыдущего входа с помощью утверждения preferred_username. |
| подсказка_домена | необязательно | Предоставляет подсказку о том, какого арендатора или домен пользователь должен использовать для входа. Значение domain_hint является зарегистрированным доменом для клиента. Если арендатор федеративно подключён к локальному каталогу, AAD перенаправляется на указанный сервер федерации арендатора. |
| code_challenge_method | рекомендуется | Метод, используемый для кодирования code_verifier в параметре code_challenge. Может быть одним из plain или S256. Если этот параметр не указан, для code_challenge принимается формат открытого текста, если задано значение code_challenge. Azure AAD версии 1.0 поддерживает как plain, так и S256. Дополнительную информацию см. в PKCE RFC. |
| задача_по_кодированию | рекомендуется | Используется для защиты предоставления кодов авторизации с помощью ключа доказательства для обмена кодами (PKCE) из нативного или общедоступного клиента. Является обязательным, если указан параметр code_challenge_method. Дополнительную информацию см. в PKCE RFC. |
Примечание.
Если пользователь является частью организации, администратор организации может согласиться или отказаться от имени пользователя или разрешить пользователю согласие. Пользователь получает возможность предоставления согласия только в том случае, если администратор разрешает его.
На этом этапе пользователю предлагается ввести свои учетные данные и предоставить согласие на разрешения, запрошенные приложением на портале Azure. После проверки подлинности пользователя и предоставления согласия Azure AD отправляет ответ приложению по адресу redirect_uri в запросе с кодом.
Успешный ответ
Успешный ответ может выглядеть следующим образом:
GET HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
| Параметр | Описание |
|---|---|
| согласие администратора | Значение True, если администратор согласился с запросом на предоставление согласия. |
| код | Код авторизации, запрошенный приложением. Приложение может использовать код авторизации для запроса токена доступа для целевого ресурса. |
| состояние_сессии | Уникальное значение, определяющее текущий сеанс пользователя. Это значение — GUID, но его следует обрабатывать как непрозрачное значение, переданное без проверки. |
| государство | Если параметр состояния включен в запрос, то в ответе должно появиться то же значение. Рекомендуется убедиться в том, что значения состояния в запросе и ответе идентичны, прежде чем использовать ответ. Это помогает обнаружить атаки межсайтовой подделки запросов (CSRF) против клиента. |
Ответ на ошибку
Ответы об ошибках также могут быть отправлены в redirect_uri, чтобы приложение могло их обрабатывать надлежащим образом.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
Коды ошибок на конечной точке авторизации
В следующей таблице описаны различные коды ошибок, которые могут возвращаться в параметре ответа с ошибкой error.
| Код ошибки | Описание | Действие клиента |
|---|---|---|
| недействительный_запрос | Ошибка протокола, например отсутствует обязательный параметр. | Исправьте запрос и отправьте его повторно. Это ошибка разработки, и она обычно обнаруживается во время первоначального тестирования. |
| неавторизованный клиент | Клиентское приложение не может запрашивать код авторизации. | Обычно это происходит, когда клиентское приложение не зарегистрировано в Azure AD или не добавляется в клиент Azure AD пользователя. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в Azure AD. |
| Доступ запрещен | Владелец ресурса отказал в согласии | Клиентское приложение может уведомить пользователя о том, что оно не может продолжить, если пользователь не предоставит согласие. |
| неподдерживаемый_тип_ответа | Сервер авторизации не поддерживает тип ответа в запросе. | Исправьте запрос и отправьте его повторно. Это ошибка разработки, и она обычно обнаруживается во время первоначального тестирования. |
| ошибка сервера | Сервер обнаружил непредвиденную ошибку. | Повторите запрос. Эти ошибки могут возникать в связи с временными условиями. Клиентское приложение может объяснить пользователю, что его ответ отложен из-за временной ошибки. |
| временно недоступно | Сервер временно занят и не может обработать запрос. | Повторите запрос. Клиентское приложение может объяснить пользователю, что его ответ задерживается из-за временного условия. |
| неверный_ресурс | Целевой ресурс недопустим, так как он не существует, Azure AD не может найти его или неправильно настроен. | Это означает, что ресурс, если он существует, не настроен в клиенте. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в Azure AD. |
Используйте код авторизации, чтобы запросить токен доступа
Теперь, когда вы получили код авторизации и вам предоставлено разрешение пользователем, можно активировать код для токена доступа к нужному ресурсу, отправив запрос POST на конечную точку /token:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd
//NOTE: client_secret only required for web apps
Чтобы найти URI идентификатора приложения, на портале Azure щелкните Azure Active Directory, щелкните регистрации приложений, откройте страницу настроек приложения, а затем щелкните Свойства.
Успешный ответ
Azure AD возвращает маркер доступа при успешном ответе. Чтобы минимизировать сетевые вызовы из клиентского приложения и их связанную задержку, клиентское приложение должно кэшировать маркеры доступа для времени существования маркера, указанного в ответе OAuth 2.0. Чтобы определить время существования маркера, используйте значения параметров expires_in или expires_on.
Если ресурс веб-API возвращает код ошибки invalid_token, это может указывать на то, что ресурс определил, что срок действия маркера истек. Если время по часам клиента и ресурса отличается (известное как "отклонение времени"), ресурс может рассматривать маркер истекшим до его очистки из кэша клиента. Если это происходит, удалите токен из кэша, даже если он по-прежнему находится в пределах его рассчитанного времени жизни.
Успешный ответ может выглядеть следующим образом:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1388444763",
"resource": "https://service.contoso.com/",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
| Параметр | Описание |
|---|---|
| маркер доступа (access_token) | Запрашиваемый маркер доступа. Это непрозрачная строка. Она зависит от того, какой ресурс ожидает получения, и не предназначен для просмотра клиентом. Приложение может использовать этот маркер для аутентификации в защищенном ресурсе, таком как веб-API. |
| тип токена | Указывает значение типа токена. Единственным типом, поддерживаемым Azure AD, является носитель. Дополнительные сведения о токенах типа Bearer см. в стандарте авторизации OAuth2.0: использование токенов Bearer (RFC 6750) |
| срок действия истечет через | Срок действия токена доступа (в секундах). |
| истекает_на | Время истечения срока действия маркера доступа. Дата представлена как количество секунд с 1970-01-01T0:01T0:0Z UTC до истечения срока действия. Это значение используется для определения времени существования кэшированных маркеров. |
| ресурс | URI идентификатора приложения веб-API (защищенный ресурс). |
| охват | Разрешения олицетворения, предоставленные клиентскому приложению. Разрешение по умолчанию — user_impersonation. Владелец защищенного ресурса может зарегистрировать дополнительные значения в Azure AD. |
| рефреш_токен | Токен обновления OAuth 2.0. Приложение может использовать этот маркер для получения дополнительных маркеров доступа по истечении срока действия текущего маркера доступа. Маркеры обновления имеют большие сроки действия, и с их помощью можно сохранять доступ к ресурсам в течение длительного времени. |
| ид_токен | Неподписанный JSON веб-токен (JWT), представляющий токен идентификатора . Приложение может декодировать сегменты этого токена base64Url, чтобы запросить сведения о пользователе, выполнившем вход. Приложение может кэшировать значения и отображать их, но оно не должно полагаться на них для каких-либо границ авторизации или безопасности. |
Дополнительные сведения о веб-токенах JSON см. в спецификации проекта JWT IETF. Чтобы узнать больше о id_tokens, см. описание потока OpenID Connect версии 1.0 в.
Ответ на ошибку
Ошибки конечной точки выдачи маркера — это коды ошибок HTTP, так как клиент вызывает конечную точку выдачи маркера напрямую. Помимо кода состояния HTTP, конечная точка выдачи маркера Azure AD также возвращает документ JSON с объектами, описывающими ошибку.
Пример ответа на ошибку может выглядеть следующим образом:
{
"error": "invalid_grant",
"error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
"error_codes": [
70002,
70008
],
"timestamp": "2016-04-11 18:00:12Z",
"trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
"correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
| Параметр | Описание |
|---|---|
| ошибка | Строка кода ошибки, которая может использоваться для классификации типов возникающих ошибок и может использоваться для реагирования на ошибки. |
| описание ошибки | Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности. |
| коды_ошибок | Список кодов ошибок, специфичных для STS, которые могут помочь при диагностике. |
| отметка времени | Время возникновения ошибки. |
| trace_id | Уникальный идентификатор для запроса, который может помочь при диагностике. |
| идентификатор корреляции | Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Коды состояния HTTP
В следующей таблице перечислены коды состояния HTTP, возвращаемые конечной точкой выдачи маркера. В некоторых случаях код ошибки достаточно для описания ответа, но при наличии ошибок необходимо проанализировать соответствующий документ JSON и проверить его код ошибки.
| КОД HTTP | Описание |
|---|---|
| 400 | Код HTTP по умолчанию. Используется в большинстве случаев и обычно из-за неправильно сформированного запроса. Исправьте запрос и отправьте его повторно. |
| 401 | Сбой проверки подлинности. Например, в запросе отсутствует параметр client_secret. |
| 403 | Ошибка авторизации. Например, у пользователя нет разрешения на доступ к ресурсу. |
| 500 | Внутренняя ошибка произошла в службе. Повторите запрос. |
Коды ошибок конечных точек токенов
| Код ошибки | Описание | Действие клиента |
|---|---|---|
| недействительный_запрос | Ошибка протокола, например отсутствует обязательный параметр. | Исправление и повторная отправка запроса |
| недействительный_доступ | Код авторизации недопустим или истек. | Попробуйте создать запрос к конечной точке /authorize |
| неавторизованный клиент | Клиент, прошедший проверку подлинности, не авторизован для использования этого типа предоставления авторизации. | Обычно это происходит, когда клиентское приложение не зарегистрировано в Azure AD или не добавляется в клиент Azure AD пользователя. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в Azure AD. |
| недопустимый клиент | Сбой проверки подлинности клиента. | Учетные данные клиента недействительны. Чтобы устранить эту проблему, администратор приложения обновляет учетные данные. |
| неподдерживаемый_тип_доступа | Сервер авторизации не поддерживает тип предоставления авторизации. | Измените тип предоставления в запросе. Ошибка этого типа должна происходить только во время разработки, и ее должны обнаружить при первоначальном тестировании. |
| неверный_ресурс | Целевой ресурс недопустим, так как он не существует, Azure AD не может найти его или неправильно настроен. | Это означает, что ресурс, если он существует, не настроен в клиенте. Приложение может предложить пользователю инструкцию по установке приложения и его добавлению в Azure AD. |
| требуется взаимодействие | Для запроса требуется взаимодействие с пользователем. Например, требуется дополнительный шаг проверки подлинности. | Вместо неинтерактивного запроса повторите попытку с интерактивным запросом авторизации для того же ресурса. |
| временно недоступно | Сервер временно занят и не может обработать запрос. | Повторите запрос. Клиентское приложение может объяснить пользователю, что его ответ задерживается из-за временного условия. |
Использование маркера доступа для доступа к ресурсу
Теперь, когда вы успешно приобрели access_token, токен можно использовать в запросах к веб-API, добавив его в заголовок Authorization. Спецификация RFC 6750 объясняет, как использовать маркеры носителя в HTTP-запросах для доступа к защищенным ресурсам.
Пример запроса
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
Ответ на ошибку
Защищенные ресурсы, реализующие и выдающие коды состояния HTTP в соответствии с RFC 6750. Если запрос не содержит аутентификационные данные или отсутствует токен, ответ содержит заголовок WWW-Authenticate. При сбое запроса сервер ресурсов отвечает с кодом состояния HTTP и кодом ошибки.
Ниже приведен пример неудачного ответа, если запрос клиента не включает маркер носителя:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize", error="invalid_token", error_description="The access token is missing.",
Параметры ошибки
Коды ошибок схемы носителя
Спецификация RFC 6750 определяет следующие ошибки для ресурсов, использующих заголовок WWW-Authenticate и схему Bearer в ответе.
| Код состояния HTTP | Код ошибки | Описание | Действие клиента |
|---|---|---|---|
| 400 | недействительный_запрос | Запрос сформирован некорректно. Например, может быть отсутствует параметр или используется один и тот же параметр дважды. | Исправьте ошибку и повторите запрос. Этот тип ошибки должен возникать только во время разработки и обнаруживаться при первоначальном тестировании. |
| 401 | недопустимый токен | Маркер доступа отсутствует, недопустим или отозван. Значение параметра error_description предоставляет дополнительные сведения. | Запросите новый маркер с сервера авторизации. Если новый токен не работает, произошла непредвиденная ошибка. Отправьте пользователю сообщение об ошибке и повторите попытку после случайных задержек. |
| 403 | недостаточный_объем_прав | Токен доступа не содержит прав имперсонации, необходимых для доступа к ресурсу. | Отправьте новый запрос авторизации в конечную точку авторизации. Если ответ содержит параметр области, используйте значение области в запросе к ресурсу. |
| 403 | недостаточный доступ | Объект маркера не имеет разрешений, необходимых для доступа к ресурсу. | Попросите пользователя использовать другую учетную запись или запросить разрешения на указанный ресурс. |
Обновление маркеров доступа
Маркеры доступа являются короткими и должны быть обновлены после истечения срока их действия, чтобы продолжить доступ к ресурсам. Вы можете обновить access_token, отправив другой запрос POST в конечную точку /token, но на этот раз предоставив refresh_token вместо code. Токены обновления действительны для всех ресурсов, на которые ваш клиент уже дал согласие на доступ. Следовательно, токен обновления, выданный по запросу resource=https://graph.microsoft.com, можно использовать для запроса нового токена доступа для resource=https://contoso.com/api.
Маркеры обновления не имеют указанных сроков действия. Обычно у маркеров обновления относительно продолжительный срок действия. Однако в некоторых случаях срок действия токенов обновления истекает, они аннулируются или не обладают достаточными привилегиями для требуемого действия. Ваше приложение должно ожидать и обрабатывать ошибки, возвращаемые эндпоинтом выдачи токена.
При получении ответа с ошибкой маркера обновления удалите текущий маркер обновления и запросите новый код авторизации или маркер доступа. В частности, при использовании токена обновления в потоке предоставления кода авторизации, при получении ответа с кодами ошибок interaction_required или invalid_grant, отмените токен обновления и запросите новый код авторизации.
Пример запроса к конечной точке для конкретного арендатора (можно также использовать общую конечную точку ) для получения нового токена доступа с помощью токена обновления выглядит так:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Успешный ответ
Успешный ответ токена будет выглядеть следующим образом:
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1460404526",
"resource": "https://service.contoso.com/",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
| Параметр | Описание |
|---|---|
| тип токена | Тип токена. Единственным поддерживаемым значением является Bearer. |
| срок действия истечет через | Оставшееся время существования маркера в секундах. Обычное значение равно 3600 (один час). |
| истекает_на | Дата и время истечения срока действия маркера. Дата представлена как количество секунд с 1970-01-01T0:01T0:0Z UTC до истечения срока действия. |
| ресурс | Определяет защищенный ресурс, доступ к которому возможен с использованием токена доступа. |
| охват | Разрешения олицетворения, предоставленные родному клиентскому приложению. Разрешение по умолчанию — user_impersonation. Владелец целевого ресурса может зарегистрировать альтернативные значения в Azure AD. |
| маркер доступа (access_token) | Новый маркер доступа, который был запрошен. |
| рефреш_токен | Новый refresh_token OAuth 2.0, который можно использовать для запроса новых маркеров доступа при истечении срока действия этого ответа. |
Ответ на ошибку
Пример ответа на ошибку может выглядеть следующим образом:
{
"error": "invalid_resource",
"error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
"error_codes": [
50001
],
"timestamp": "2016-04-11 18:59:01Z",
"trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
"correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
| Параметр | Описание |
|---|---|
| ошибка | Строка кода ошибки, которая может использоваться для классификации типов возникающих ошибок и может использоваться для реагирования на ошибки. |
| описание ошибки | Конкретное сообщение об ошибке, с помощью которого разработчик может определить причину возникновения ошибки проверки подлинности. |
| коды_ошибок | Список кодов ошибок, специфичных для STS, которые могут помочь при диагностике. |
| отметка времени | Время возникновения ошибки. |
| trace_id | Уникальный идентификатор для запроса, который может помочь при диагностике. |
| идентификатор корреляции | Уникальный идентификатор для запроса, который может помочь при диагностике нескольких компонентов. |
Описание кодов ошибок и рекомендуемых действий в клиенте см. в разделе Коды ошибок конечных точек токенов.
Дальнейшие действия
Дополнительные сведения о конечной точке Azure AD версии 1.0 и о добавлении проверки подлинности и авторизации в веб-приложения и веб-API см. в примерах приложений.