Получение кода подтверждения из URL
-
Чтобы пользователь подтвердил доступ к своим данным, настройте в приложении переход на страницу Яндекс OAuth. Для этого используйте запрос для получения кода подтверждения из URL.
Когда пользователь разрешает приложению доступ к своим данным, Яндекс OAuth перенаправляет его в приложение на адрес, указанный в поле Redirect URI при регистрации приложения.
-
Код подтверждения возвращается в URL перенаправления. Чтобы обменять код подтверждения на OAuth-токен, приложение должно отправить POST-запрос.
Полученный токен можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в браузере или открытых конфигурационных файлах.
Для дополнительной защиты ваших данных при передаче в запросах можно использовать параметры, которые поддерживает расширение PKCE протокола OAuth 2.0: случайную строку code_verifier и преобразованную версию этой строки code_challenge, а также данные о методе преобразования — code_challenge_method.
Запрос кода подтверждения
Формат запроса
https://oauth.yandex.ru/authorize?response_type=code
& client_id=<идентификатор приложения>
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& redirect_uri=<адрес перенаправления>]
[& login_hint=<имя пользователя или электронный адрес>]
[& scope=<запрашиваемые необходимые права>]
[& optional_scope=<запрашиваемые опциональные права>]
[& force_confirm=yes]
[& state=<произвольная строка>]
[& code_challenge=<преобразованная верcия верификатора code_verifier>]
[& code_challenge_method=<метод преобразования>]
Обязательные параметры
|
Параметр |
Описание |
|
|
Требуемый ответ. При запросе кода подтверждения следует указать значение |
|
|
Идентификатор приложения. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения. |
Дополнительные параметры
|
Параметр |
Описание |
|
|
Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства. Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126). Подробнее о работе с токенами для отдельных устройств читайте на странице Отзыв токена для устройства. Если параметр Внимание У приложения не может быть больше 30 токенов, привязанных к устройствам определенного пользователя. Если Яндекс OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать. |
|
|
Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр |
|
|
URL, на который нужно перенаправить пользователя после того, как он разрешил приложению доступ. По умолчанию используется первый Redirect URI, указанный в настройках приложения (Платформы → Веб-сервисы → Redirect URI). В значении параметра допустимо указывать только те адреса, которые перечислены в настройках приложения. Если совпадение неточное, параметр игнорируется. |
|
|
Явное указание аккаунта, для которого запрашивается токен. В значении параметра можно передавать логин аккаунта на Яндексе, а также адрес Яндекс Почты или Яндекс Почты для домена. Параметр позволяет помочь пользователю авторизоваться на Яндексе с тем аккаунтом, к которому нужен доступ приложению. Получив параметр, Яндекс OAuth проверяет авторизацию пользователя:
Если параметр указывает на несуществующий аккаунт, Яндекс OAuth сможет только сообщить об этом пользователю. Приложению придется запрашивать токен заново. |
|
|
Список прав доступа, необходимых приложению. Значения в списке разделяются пробелами. Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения. Если параметры |
|
|
Опциональные права запрашиваются в дополнение к правам, указанным в параметре Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения. Пользователь может выбрать, какие из опциональных прав предоставить. Токен будет выдан с правами, указанными в параметре Параметр можно использовать, например, если приложению нужна электронная почта для регистрации пользователя, а доступ к портрету желателен, но не обязателен. Примечание Права доступа, запрошенные одновременно через параметр |
|
|
Признак того, что у пользователя обязательно нужно запросить разрешение на доступ к аккаунту (даже если пользователь уже разрешил доступ данному приложению). Получив этот параметр, Яндекс OAuth предложит пользователю разрешить доступ приложению и выбрать нужный аккаунт Яндекса. Параметр полезен, например, если пользователь вошел на сайт с одним аккаунтом Яндекса и хочет переключиться на другой аккаунт. Если параметр не использовать, пользователю придется явно менять аккаунт на каком-нибудь сервисе Яндекса или отзывать токен, выданный сайту. Параметр обрабатывается, если для него указано значение |
|
|
Строка состояния, которую Яндекс OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
|
|
Версия верификатора |
|
|
Метод преобразования |
Формат ответа
Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.
http://www.example.com/token?code=<код подтверждения>
[& state=<значение параметра state в запросе>]
Параметры ответа:
|
Свойство |
Описание |
|
|
Код подтверждения, который можно обменять на OAuth-токен. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
|
|
Строка состояния, которую Яндекс OAuth возвращает без изменения. Максимальная допустимая длина строки — 1024 символа. Можно использовать, например, для защиты от CSRF-атак или идентификации пользователя, для которого запрашивается токен. |
Если код подтверждения выдать не удалось, то Яндекс OAuth указывает в URL код ошибки и ее описание.
http://www.example.com/token?error=<код ошибки>
& error_description=<описание ошибки>
[& state=<значение параметра state в запросе>]
Возможные коды ошибок:
-
unauthorized_client— приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано.
Обмен кода подтверждения на OAuth-токен
Формат запроса
POST /token HTTP/1.1
Host: https://oauth.yandex.ru/
Content-type: application/x-www-form-urlencoded
Content-Length: <длина тела запроса>
[Authorization: Basic <закодированная методом base64 строка `client_id:client_secret`>]
grant_type=authorization_code
& code=<код подтверждения>
[& client_id=<идентификатор приложения>]
[& client_secret=<секретный ключ>]
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& code_verifier=<верификатор>]
Обязательные параметры
|
Параметр |
Описание |
|
|
Способ запроса OAuth-токена. Если вы используете код подтверждения, укажите значение |
|
|
Код подтверждения, полученный от Яндекс OAuth. Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново. |
Дополнительные параметры
|
Параметр |
Описание |
|
|
Идентификатор приложения. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения. Секретный ключ и идентификатор приложения также можно передать в заголовке |
|
|
Секретный ключ. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения. Секретный ключ и идентификатор приложения также можно передать в заголовке Если для защиты данных применяется расширение PKCE и в запросе передается параметр |
|
|
Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства. Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126). Подробнее о работе с токенами для отдельных устройств читайте на странице Отзыв токена для устройства. Если параметр Внимание У приложения не может быть больше 30 токенов, привязанных к устройствам определенного пользователя. Если Яндекс OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать. |
|
|
Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов. Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д. Если параметр |
|
|
Верификатор, обеспечивающий защиту передаваемых данных. Параметр применяется при использовании расширения PKCE. Представляет собой случайную строку, сгенерированную приложением, на основании которой формируется |
Параметры запроса должны передаваться в теле запроса и должны быть закодированы в urlencode.
Примечание
Чтобы передать идентификатор и секретный ключ в заголовке Authorization, закодируйте строку <client_id>:<client_secret> методом base64.
Если Яндекс OAuth получает заголовок Authorization, параметры client_id и client_secret в теле запроса игнорируются.
Формат ответа
Яндекс OAuth возвращает OAuth-токен, refresh-токен и время их жизни в JSON-формате:
200 OK
Content-type: application/json
{
"token_type": "bearer",
"access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs",
"expires_in": 124234123534,
"refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ",
"scope": "login:info login:email login:avatar"
}
Параметры ответа:
|
Свойство |
Описание |
|
|
Тип выданного токена. Всегда принимает значение |
|
|
OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения. |
|
|
Время жизни токена в секундах. |
|
|
Токен, который можно использовать для продления срока жизни соответствующего OAuth-токена. Время жизни refresh-токена совпадает с временем жизни OAuth-токена. |
|
|
Права, запрошенные разработчиком или указанные при регистрации приложения. Поле |
Если выдать токен не удалось, ответ содержит описание ошибки:
{
"error_description": "<описание ошибки>",
"error": "<код ошибки>"
}
Возможные коды ошибок:
-
authorization_pending— пользователь еще не ввел код подтверждения. -
bad_verification_code— переданное значение параметраcodeне является 7-значным числом. -
invalid_client― приложение с указанным идентификатором (параметрclient_id) не найдено или заблокировано. Этот код также возвращается, если в параметреclient_secretпередан неверный секретный ключ. -
invalid_grant— неверный или просроченный код подтверждения. -
invalid_request― неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса). -
invalid_scope— права приложения изменились после генерации кода подтверждения. -
unauthorized_client— приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано. -
unsupported_grant_type― недопустимое значение параметраgrant_type. -
Basic auth required— тип авторизации, указанный в заголовкеAuthorization, отличен отBasic
. -
Malformed Authorization header— заголовокAuthorizationне соответствует формату<client_id>:<client_secret>, или эта строка не закодирована методом base64.