Ввод кода на странице авторизации Яндекс OAuth

На некоторых устройствах (например, на телевизорах) вводить код подтверждения в приложении может быть неудобно. В этом случае можно предложить пользователю ввести код на странице авторизации Яндекс OAuth:

  1. Чтобы пользователь подтвердил доступ к своим данным, настройте в приложении запрос для двух кодов: device_code для устройства и user_code для пользователя. Для этого используйте запрос кодов подтверждения.

    Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.

  2. После получения кодов приложение одновременно:

  3. Если код введен корректно, Яндекс OAuth предложит разрешить или запретить доступ приложению. Яндекс OAuth возвращает токен в ответ на следующий запрос приложения.

Запрос кодов подтверждения

Формат запроса

Приложение должно запросить коды подтверждения с помощью HTTP-метода POST:

POST /device/code
Host: https://oauth.yandex.ru/

 & client_id=<идентификатор приложения>
[& device_id=<идентификатор устройства>]
[& device_name=<имя устройства>]
[& scope=<запрашиваемые необходимые права>]
[& optional_scope=<запрашиваемые опциональные права>]

Обязательные параметры

Параметр

Описание

client_id

Идентификатор приложения. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения.

Дополнительные параметры

Параметр

Описание

device_id

Уникальный идентификатор устройства, для которого запрашивается токен. Чтобы обеспечить уникальность, достаточно один раз сгенерировать UUID и использовать его при каждом запросе нового токена с данного устройства.

Идентификатор должен быть не короче 6 символов и не длиннее 50. Допускается использовать только печатаемые ASCII-символы (с кодами от 32 до 126).

Подробнее о работе с токенами для отдельных устройств читайте на странице Отзыв токена для устройства.

Если параметр device_id передан без параметра device_name, в пользовательском интерфейсе токен будет помечен как выданный для неизвестного устройства.

Внимание

У приложения не может быть больше 30 токенов, привязанных к устройствам определенного пользователя. Если Яндекс OAuth успешно выдает приложению новый токен для устройства, самый старый из таких токенов перестает работать.

device_name

Имя устройства, которое следует показывать пользователям. Не длиннее 100 символов.

Для мобильных устройств рекомендуется передавать имя устройства, заданное пользователем. Если такого имени нет, его можно собрать из модели устройства, названия и версии ОС и т. д.

Если параметр device_name передан без параметра device_id, он будет проигнорирован. Яндекс OAuth сможет выдать только обычный токен, не привязанный к устройству.

scope

Список прав доступа, необходимых приложению. Значения в списке разделяются пробелами.

Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения.

Если параметры scope и optional_scope не переданы, то токен будет выдан с правами, указанными при регистрации приложения.

optional_scope

Опциональные права запрашиваются в дополнение к правам, указанным в параметре scope.

Права должны запрашиваться из перечня, определенного при регистрации приложения. Узнать допустимые права можно по ссылке https://oauth.yandex.ru/client/<client_id>/info, указав вместо <client_id> идентификатор приложения.

Пользователь может выбрать, какие из опциональных прав предоставить. Токен будет выдан с правами, указанными в параметре scope, и правами, выбранными пользователем из указанных в параметре optional_scope.

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

Примечание

Права доступа, запрошенные одновременно через параметр scope и через параметр optional_scope, будут считаться опциональными.

Формат ответа

Яндекс OAuth возвращает код для пользователя и информацию для запроса токена:

200 OK

Content-type: application/json

{
   "device_code": "3e2a5a5c0e02439aa78a23442721848c",
   "user_code": "h5nbcr6c",
   "verification_url": "https://oauth.yandex.ru/device",
   "interval": 5,
   "expires_in": 300
}

Параметры ответа:

Свойство

Описание

device_code

Код, с которым следует запрашивать OAuth-токен.

user_code

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

verification_url

Адрес страницы, на которой пользователь должен ввести код из свойства user_code: https://oauth.yandex.ru/device.

interval

Минимальный интервал в секундах, с которым приложение должно запрашивать OAuth-токен. Если запросы будут приходить чаще, Яндекс OAuth может ответить ошибкой.

expires_in

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

Если выдать токен не удалось, ответ содержит описание ошибки:

{
   "error_description": "<описание ошибки>",
   "error": "<код ошибки>"
}

Возможные коды ошибок:

  • invalid_client ― приложение с указанным идентификатором (параметр client_id) не найдено или заблокировано. Этот код также возвращается, если в параметре client_secret передан неверный секретный ключ.

  • invalid_request ― неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса).

  • unauthorized_client — приложение было отклонено при модерации или только ожидает ее. Также возвращается, если приложение заблокировано.

  • Basic auth required — тип авторизации, указанный в заголовке Authorization, отличен от Basic.

  • Malformed Authorization header — заголовок Authorization не соответствует формату <client_id>:<client_secret>, или эта строка не закодирована методом base64.

Обмен кода подтверждения на OAuth-токен

Формат запроса

Приложение отправляет код устройства, а также свой идентификатор и пароль в POST-запросе.

POST /token HTTP/1.1
Host: https://oauth.yandex.ru/
Content-type: application/x-www-form-urlencoded
Content-Length: <длина тела запроса>
[Authorization: Basic <закодированная строка `client_id:client_secret`>]

   grant_type=device_code
 & code=<код устройства>
[& client_id=<идентификатор приложения>]
[& client_secret=<секретный ключ>]

Обязательные параметры

Параметр

Описание

grant_type

Способ запроса OAuth-токена.

Если вы используете код подтверждения для устройства, укажите значение device_code.

code

Код из параметра device_code, полученный на этапе запроса кодов подтверждения.

Время жизни предоставленного кода — 10 минут. По истечении этого времени код нужно запросить заново.

Дополнительные параметры

Параметр

Описание

client_id

Идентификатор приложения. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения.

Секретный ключ и идентификатор приложения также можно передать в заголовке Authorization.

client_secret

Секретный ключ. Доступен в свойствах приложения. Чтобы открыть свойства, перейдите в Яндекс OAuth и нажмите на название приложения.

Секретный ключ и идентификатор приложения также можно передать в заголовке Authorization.

Параметры запроса должны передаваться в теле запроса и должны быть закодированы в 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"
}

Параметры ответа:

Свойство

Описание

token_type

Тип выданного токена. Всегда принимает значение bearer.

access_token

OAuth-токен с запрошенными правами или с правами, указанными при регистрации приложения.

expires_in

Время жизни токена в секундах.

refresh_token

Токен, который можно использовать для продления срока жизни соответствующего OAuth-токена. Время жизни refresh-токена совпадает с временем жизни OAuth-токена.

scope

Права, запрошенные разработчиком или указанные при регистрации приложения. Поле scope является дополнительным и возвращается, если 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.

Предыдущая
Получение кода подтверждения от пользователя
Следующая
Этап 3. Получение информации о пользователе
В этой статье: