OAuth 2.0 для приложений ТВ и устройств с ограниченным вводом данных

В этом документе объясняется, как реализовать авторизацию OAuth 2.0 для доступа к API данных YouTube через приложения, работающие на таких устройствах, как телевизоры, игровые консоли и принтеры. В частности, этот процесс предназначен для устройств, которые либо не имеют доступа к браузеру, либо имеют ограниченные возможности ввода.

OAuth 2.0 позволяет пользователям делиться определёнными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую информацию в тайне. Например, телевизионное приложение может использовать OAuth 2.0 для получения разрешения на выбор файла, хранящегося на Google Диске.

Поскольку приложения, использующие этот поток, распределены по отдельным устройствам, предполагается, что они не могут хранить секреты. Они могут обращаться к API Google, пока пользователь находится в приложении или когда приложение работает в фоновом режиме.

Альтернативы

Если вы пишете приложение для такой платформы, как Android, iOS, macOS, Linux или Windows (включая универсальную платформу Windows), которая имеет доступ к браузеру и полноценные возможности ввода, используйте протокол OAuth 2.0 для мобильных и настольных приложений . (Вам следует использовать этот протокол, даже если ваше приложение представляет собой инструмент командной строки без графического интерфейса.)

Если вы хотите разрешить пользователям входить в систему только с помощью их учетных записей Google и использовать токен JWT ID для получения базовой информации о профиле пользователя, см . раздел Вход в систему на телевизорах и устройствах с ограниченными возможностями ввода .

Предпосылки

Включите API для вашего проекта

Любое приложение, которое вызывает API Google, должно включить эти API в API Console.

Чтобы включить API для вашего проекта:

1. Open the API Library в Google API Console.
2. If prompted, select a project, or create a new one.
3. Найдите и включите API данных YouTube на странице «Библиотека». Найдите другие API, которые будет использовать ваше приложение, и включите их.

Создать учетные данные авторизации

Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учётные данные авторизации, которые идентифицируют приложение на сервере OAuth 2.0 Google. Ниже описано, как создать учётные данные для вашего проекта. Затем ваши приложения смогут использовать эти учётные данные для доступа к API, которые вы включили для этого проекта.

1. Go to the Credentials page.
2. Нажмите «Создать клиента» .
3. Выберите тип приложения «Телевизоры и устройства с ограниченным вводом» .
4. Назовите своего клиента OAuth 2.0 и нажмите «Создать» .

Определить области доступа

Области действия позволяют вашему приложению запрашивать доступ только к тем ресурсам, которые ему необходимы, а также позволяют пользователям контролировать объём предоставляемого им доступа. Таким образом, между количеством запрашиваемых областей действия и вероятностью получения согласия пользователя может существовать обратная зависимость.

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

API данных YouTube v3 использует следующие области действия:

См. список разрешенных областей для установленных приложений или устройств.

Получение токенов доступа OAuth 2.0

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

1. Ваше приложение отправляет запрос на сервер авторизации Google, который определяет области, к которым ваше приложение будет запрашивать разрешение на доступ.
2. Сервер отвечает несколькими фрагментами информации, используемыми на последующих этапах, такими как код устройства и код пользователя.
3. Вы отображаете информацию, которую пользователь может ввести на отдельном устройстве для авторизации вашего приложения.
4. Ваше приложение начинает опрашивать сервер авторизации Google, чтобы определить, авторизовал ли пользователь ваше приложение.
5. Пользователь переключается на устройство с расширенными возможностями ввода, запускает веб-браузер, переходит по URL-адресу, отображенному на шаге 3, и вводит код, который также отображается на шаге 3. Затем пользователь может предоставить (или запретить) доступ к вашему приложению.
6. Следующий ответ на ваш опросный запрос содержит токены, необходимые вашему приложению для авторизации запросов от имени пользователя. (Если пользователь отказал в доступе к вашему приложению, ответ не содержит токенов.)

Изображение ниже иллюстрирует этот процесс:

В следующих разделах эти шаги подробно описаны. Учитывая разнообразие возможностей и сред выполнения устройств, в примерах, представленных в этом документе, используется утилита командной строки curl . Эти примеры легко переносить на различные языки программирования и среды выполнения.

Шаг 1: Запросите коды устройства и пользователя

На этом этапе ваше устройство отправляет HTTP-запрос POST на сервер авторизации Google по адресу https://oauth2.googleapis.com/device/code , который идентифицирует ваше приложение, а также области доступа, к которым оно хочет получить доступ от имени пользователя. Этот URL-адрес следует получить из документа Discovery , используя значение метаданных device_authorization_endpoint . Включите следующие параметры HTTP-запроса:

Примеры

В следующем фрагменте показан пример запроса:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

В этом примере показана команда curl для отправки того же запроса:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

Шаг 2: Обработка ответа сервера авторизации

Сервер авторизации вернет один из следующих ответов:

Успешный ответ

Если запрос действителен, вашим ответом будет JSON-объект, содержащий следующие свойства:

В следующем фрагменте показан пример ответа:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

Ответ о превышении квоты

Если количество запросов на код устройства превысило квоту, связанную с вашим идентификатором клиента, вы получите ответ 403, содержащий следующую ошибку:

{
  "error_code": "rate_limit_exceeded"
}

В этом случае используйте стратегию отсрочки, чтобы уменьшить частоту запросов.

Шаг 3: Отобразите код пользователя

Отобразите пользователю значения verification_url и user_code , полученные на шаге 2. Оба значения могут содержать любой печатный символ из набора символов US-ASCII. Отображаемый пользователю контент должен предлагать ему перейти по адресу verification_url на отдельном устройстве и ввести user_code .

Разрабатывайте свой пользовательский интерфейс (UI), учитывая следующие правила:

• user_code
  • user_code должен отображаться в поле, поддерживающем 15 символов размера «W». Другими словами, если код WWWWWWWWWWWWWWW отображается корректно, ваш пользовательский интерфейс корректен, и мы рекомендуем использовать это строковое значение при тестировании отображения кода user_code в вашем пользовательском интерфейсе.
  • user_code чувствителен к регистру и не должен изменяться каким-либо образом, например, путем изменения регистра или вставки других символов форматирования.
• verification_url
  • Пространство, в котором отображается verification_url должно быть достаточно широким для размещения строки URL длиной 40 символов.
  • Не изменяйте параметр verification_url каким-либо образом, за исключением случаев, когда требуется удалить схему для отображения. Если вы планируете удалить схему (например, https:// ) из URL для отображения, убедитесь, что ваше приложение поддерживает оба варианта: http и https .

Шаг 4: Опрос сервера авторизации Google

Поскольку пользователь будет использовать отдельное устройство для перехода по адресу verification_url и предоставления (или запрета) доступа, запрашивающее устройство не получает автоматического уведомления о том, что пользователь отвечает на запрос доступа. Поэтому запрашивающему устройству необходимо опрашивать сервер авторизации Google, чтобы определить, ответил ли пользователь на запрос.

Запрашивающее устройство должно продолжать отправлять запросы на опрос до тех пор, пока не получит ответ, указывающий на то, что пользователь ответил на запрос доступа, или пока не истечёт срок действия device_code и user_code полученных на шаге 2. interval , возвращаемый на шаге 2, определяет время ожидания (в секундах) между запросами.

URL-адрес опрашиваемой конечной точки: https://oauth2.googleapis.com/token . Запрос на опрос содержит следующие параметры:

Примеры

В следующем фрагменте показан пример запроса:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

В этом примере показана команда curl для отправки того же запроса:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

Шаг 5: Пользователь отвечает на запрос доступа

На следующем изображении показана страница, похожая на ту, которую видят пользователи, переходящие по адресу verification_url , который вы отобразили на шаге 3 :

После ввода user_code и входа в Google, если он еще не вошел в систему, пользователь увидит экран согласия, подобный показанному ниже:

Шаг 6: Обработка ответов на запросы опросов

Сервер авторизации Google отвечает на каждый запрос опроса одним из следующих ответов:

Доступ предоставлен

Если пользователь предоставил доступ к устройству (нажав Allow на экране согласия), ответ содержит токен доступа и токен обновления. Токены позволяют вашему устройству получать доступ к API Google от имени пользователя. (Свойство scope в ответе определяет, к каким API устройство может получить доступ.)

В этом случае ответ API содержит следующие поля:

В следующем фрагменте показан пример ответа:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Токены доступа имеют ограниченный срок действия. Если вашему приложению требуется доступ к API в течение длительного периода времени, оно может использовать токен обновления для получения нового токена доступа. Если вашему приложению необходим такой тип доступа, оно должно сохранить токен обновления для последующего использования.

Доступ запрещен

Если пользователь отказывается предоставить доступ к устройству, сервер возвращает HTTP-код статуса 403 ( Forbidden ). В ответе содержится следующая ошибка:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

Ожидается авторизация

Если пользователь ещё не завершил процесс авторизации, сервер возвращает код статуса HTTP-ответа 428 ( Precondition Required ). Ответ содержит следующую ошибку:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

Слишком частые опросы

Если устройство отправляет запросы слишком часто, сервер возвращает код статуса HTTP-ответа 403 ( Forbidden ). Ответ содержит следующую ошибку:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

Другие ошибки

Сервер авторизации также возвращает ошибки, если в запросе на опрос отсутствуют какие-либо обязательные параметры или задано неверное значение параметра. Такие запросы обычно имеют код статуса HTTP-ответа 400 ( Bad Request ) или 401 ( Unauthorized ). К таким ошибкам относятся:

Вызов API Google

После того, как ваше приложение получит токен доступа, вы сможете использовать его для вызовов API Google от имени определённой учётной записи пользователя, если API предоставило необходимые ему права доступа. Для этого включите токен доступа в запрос к API, указав либо параметр запроса access_token , либо значение Bearer HTTP-заголовка Authorization . По возможности предпочтительнее использовать HTTP-заголовок, поскольку строки запросов, как правило, отображаются в журналах сервера. В большинстве случаев для настройки вызовов API Google (например, при вызове API YouTube Live Streaming ) можно использовать клиентскую библиотеку.

Обратите внимание, что API YouTube Live Streaming не поддерживает поток учётной записи сервиса. Поскольку связать учётную запись сервиса с учётной записью YouTube невозможно, попытки авторизовать запросы с помощью этого потока приведут к ошибке NoLinkedYouTubeAccount .

Вы можете опробовать все API Google и просмотреть области их действия на площадке OAuth 2.0 .

Примеры HTTP GET

Вызов конечной точки liveBroadcasts.list (API прямой трансляции YouTube) с использованием HTTP-заголовка Authorization: Bearer может выглядеть следующим образом. Обратите внимание, что вам необходимо указать собственный токен доступа:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token :

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

примеры curl

Вы можете протестировать эти команды с помощью приложения командной строки curl . Вот пример, использующий HTTP-заголовок (рекомендуется):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

Или, в качестве альтернативы, параметр строки запроса:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

Обновление токена доступа

Токены доступа периодически истекают и становятся недействительными для соответствующего запроса API. Вы можете обновить токен доступа, не запрашивая разрешения у пользователя (даже если пользователь отсутствует), если вы запросили автономный доступ к областям, связанным с токеном.

Чтобы обновить токен доступа, ваше приложение отправляет HTTPS-запрос POST на сервер авторизации Google ( https://oauth2.googleapis.com/token ), включающий следующие параметры:

В следующем фрагменте показан пример запроса:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Пока пользователь не отозвал предоставленный приложению доступ, сервер токенов возвращает JSON-объект, содержащий новый токен доступа. Пример ответа представлен в следующем фрагменте:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Обратите внимание, что существуют ограничения на количество выдаваемых токенов обновления: один на комбинацию клиент/пользователь и ещё один на пользователя для всех клиентов. Рекомендуется сохранять токены обновления в долгосрочном хранилище и использовать их до тех пор, пока они остаются действительными. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.

Отзыв токена

В некоторых случаях пользователь может захотеть отозвать доступ, предоставленный приложению. Это можно сделать в настройках учётной записи . Дополнительную информацию см. в разделе «Удаление доступа к сайту или приложению» документа поддержки «Сторонние сайты и приложения, имеющие доступ к вашей учётной записи» .

Приложение также может программно отозвать предоставленный ему доступ. Программный отзыв важен в случаях, когда пользователь отменяет подписку, удаляет приложение или когда ресурсы API, необходимые приложению, существенно изменились. Другими словами, часть процесса удаления может включать запрос к API, чтобы гарантировать удаление ранее предоставленных приложению разрешений.

Чтобы программно отозвать токен, ваше приложение отправляет запрос на https://oauth2.googleapis.com/revoke и включает токен в качестве параметра:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Токен может быть токеном доступа или токеном обновления. Если токен является токеном доступа и у него есть соответствующий токен обновления, токен обновления также будет отозван.

Если отзыв успешно обработан, то код статуса HTTP ответа — 200 В случае возникновения ошибок возвращается код статуса HTTP 400 вместе с кодом ошибки.

Разрешенные области действия

Поток OAuth 2.0 для устройств поддерживается только для следующих областей:

Доступ по времени

Доступ с ограничением по времени позволяет пользователю предоставить вашему приложению доступ к своим данным на ограниченный период времени для выполнения действия. Доступ с ограничением по времени доступен в некоторых продуктах Google в процессе получения согласия, предоставляя пользователям возможность предоставить доступ на ограниченный период времени. Примером может служить API переносимости данных , который позволяет выполнить однократную передачу данных.

Когда пользователь предоставляет вашему приложению доступ с ограничением по времени, токен обновления истекает по истечении указанного срока. Обратите внимание, что при определённых обстоятельствах токены обновления могут быть аннулированы раньше; подробности см. в этих случаях . Поле refresh_token_expires_in возвращаемое в ответе на обмен кодами авторизации, представляет собой время, оставшееся до истечения срока действия токена обновления в таких случаях.