В этом документе рассказывается, как реализовать авторизацию OAuth 2.0 для доступа к YouTube Data API с помощью приложений, работающих на таких устройствах, как телевизоры, игровые консоли и принтеры. В частности, этот процесс предназначен для устройств, на которых нет браузера или возможности ввода ограничены.
OAuth 2.0 позволяет пользователям делиться определенными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую конфиденциальную информацию. Например, приложение для телевизора может использовать OAuth 2.0, чтобы получить разрешение на выбор файла, хранящегося на Google Диске.
Поскольку приложения, использующие этот процесс, распределяются по отдельным устройствам, предполагается, что приложения не могут хранить секреты. Они могут обращаться к API Google, когда пользователь работает с приложением или когда оно запущено в фоновом режиме.
Альтернативные варианты
Если вы разрабатываете приложение для платформы, у которой есть доступ к браузеру и полные возможности ввода, например Android, iOS, macOS, Linux или Windows (включая универсальную платформу Windows), используйте процесс OAuth 2.0 для мобильных и компьютерных приложений. (Этот процесс следует использовать, даже если ваше приложение представляет собой инструмент командной строки без графического интерфейса.)
Если вы только хотите, чтобы пользователи входили в аккаунт Google и использовали токен идентификатора JWT для получения основной информации профиля, ознакомьтесь со статьей Вход в аккаунт на телевизорах и устройствах с ограниченными возможностями ввода.
Требования
Как включить API для проекта
Приложения, которые вызывают Google API, должны включить эти API в API Console.
Чтобы включить API для вашего проекта:
- Откройте библиотеку API в Google API Console.
- Выберите существующий проект или создайте новый.
- Найдите и включите YouTube Data API на странице "Библиотека". Найдите и включите другие API, которые будут использоваться в вашем приложении.
Как создать учетные данные для авторизации
Любое приложение, использующее OAuth 2.0 для доступа к API Google, должно иметь учетные данные для авторизации, которые идентифицируют приложение на сервере OAuth 2.0 Google. Ниже описано, как создать учетные данные для проекта. Затем ваши приложения смогут использовать эти учетные данные для доступа к API, которые вы включили для этого проекта.
- Перейдите на страницу Клиенты.
- Нажмите Create Client (Создать клиента).
- Выберите тип приложения Телевизоры и устройства с ограниченными возможностями ввода.
- Укажите название клиента OAuth 2.0 и нажмите Создать.
Как определить области доступа
Области действия позволяют приложению запрашивать доступ только к необходимым ресурсам, а пользователям – контролировать объем доступа, предоставляемого приложению. Таким образом, может существовать обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя.
Прежде чем приступать к реализации авторизации OAuth 2.0, рекомендуем определить области действия, к которым вашему приложению потребуется доступ.
YouTube Data API v3 использует следующие области действия:
| Объем | Описание |
|---|---|
https://www. googleapis. com/ auth/ youtube | Управляйте своим аккаунтом YouTube |
https://www. googleapis. com/ auth/ youtube. channel-memberships. creator | Посмотрите список текущих активных участников канала, их текущий уровень и дату, когда они стали участниками. |
https://www. googleapis. com/ auth/ youtube. force-ssl | Просмотр, редактирование и окончательное удаление ваших видео, оценок, комментариев и субтитров на YouTube. |
https://www. googleapis. com/ auth/ youtube. readonly | Просмотр вашего аккаунта YouTube |
https://www. googleapis. com/ auth/ youtube. upload | Управляйте своими видео на YouTube |
https://www. googleapis. com/ auth/ youtubepartner | Просмотр и управление вашими активами и связанным с ними контентом на YouTube |
https://www. googleapis. com/ auth/ youtubepartner-channel-audit | Просмотр конфиденциальной информации вашего канала YouTube, актуальной во время процесса аудита с партнером YouTube |
Посмотрите список Разрешенные области действия для установленных приложений или устройств.
Как получить токены доступа OAuth 2.0
Хотя ваше приложение работает на устройстве с ограниченными возможностями ввода, для завершения авторизации пользователям потребуется доступ к устройству с более широкими возможностями ввода. Процесс состоит из следующих этапов:
- Приложение отправляет запрос на сервер авторизации Google, в котором указаны области, к которым приложению требуется доступ.
- Сервер возвращает несколько фрагментов информации, которые используются на последующих этапах, например код устройства и код пользователя.
- Вы показываете информацию, которую пользователь может ввести на другом устройстве, чтобы авторизовать ваше приложение.
- Ваше приложение начинает опрашивать сервер авторизации Google, чтобы определить, предоставил ли пользователь приложению доступ.
- Пользователь переходит на устройство с более широкими возможностями ввода, запускает браузер, переходит по URL, показанному на шаге 3, и вводит код, также показанный на шаге 3. Пользователь может разрешить или запретить доступ к приложению.
- Следующий ответ на запрос опроса содержит токены, необходимые вашему приложению для авторизации запросов от имени пользователя. Если пользователь отказался предоставить доступ к вашему приложению, ответ не будет содержать токенов.
На изображении показан этот процесс:
Ниже вы найдете подробное описание этих шагов. Учитывая разнообразие возможностей и сред выполнения, которые могут быть у устройств, в примерах, приведенных в этом документе, используется утилита командной строки curl. Эти примеры можно перенести на различные языки и среды выполнения.
Шаг 1. Запросите коды устройства и пользователя
На этом этапе устройство отправляет HTTP-запрос POST на сервер авторизации Google по адресу https://oauth2.googleapis.com/device/code. В запросе указывается ваше приложение и области доступа, к которым оно хочет получить доступ от имени пользователя.
Этот URL необходимо получить из документа Discovery, используя значение метаданных device_authorization_endpoint. Включите следующие параметры HTTP-запроса:
| Параметры | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Обязательно
Идентификатор клиента для вашего приложения. Это значение можно найти на странице клиентов в Cloud Console. |
||||||||||||||||
scope |
Обязательно
Список областей действия, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения используются в окне запроса согласия, которое Google показывает пользователю. Ознакомьтесь со списком разрешенных областей действия для установленных приложений или устройств. Области действия позволяют приложению запрашивать доступ только к тем ресурсам, которые ему нужны, а пользователям – контролировать объем доступа, предоставляемого приложению. Таким образом, существует обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя. YouTube Data API v3 использует следующие области действия:
Полный список областей действия, которые можно использовать для доступа к API Google, приведен в документе Области действия API OAuth 2.0. |
||||||||||||||||
Примеры
Ниже приведен пример запроса.
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 |
Значение, которое Google уникальным образом присваивает устройству, на котором запущено приложение, запрашивающее авторизацию. Пользователь авторизует устройство с помощью другого устройства с более широкими возможностями ввода. Например, пользователь может авторизовать приложение, запущенное на телевизоре, с помощью ноутбука или мобильного телефона. В этом случае device_code идентифицирует телевизор.
Этот код позволяет устройству, на котором запущено приложение, безопасно определить, предоставил ли пользователь доступ. |
expires_in |
Продолжительность времени в секундах, в течение которого действительны device_code и user_code. Если за это время пользователь не завершит авторизацию, а ваше устройство не отправит запрос на получение информации о решении пользователя, вам может потребоваться перезапустить этот процесс с шага 1. |
interval |
Время в секундах, которое устройство должно ждать между запросами на опрос. Например, если значение равно 5, устройство должно отправлять запрос на опрос серверу авторизации Google каждые пять секунд. Подробную информацию можно найти на шаге 3. |
user_code |
Значение с учетом регистра, которое указывает Google, к каким областям действия приложение запрашивает доступ. В пользовательском интерфейсе пользователю будет предложено ввести это значение на другом устройстве с более широкими возможностями ввода. Затем Google использует это значение, чтобы показывать правильный набор областей при запросе доступа к приложению. |
verification_url |
URL, по которому пользователь должен перейти на другом устройстве, чтобы ввести код user_code и предоставить или запретить доступ к приложению. Это значение также будет показано в пользовательском интерфейсе. |
Ниже приведен пример ответа.
{ "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.
При разработке пользовательского интерфейса учитывайте следующие правила:
user_code- Значение
user_codeдолжно быть указано в поле, которое может вместить 15 символов размера "Ш". Другими словами, если вы можете правильно отобразить код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. Запрос на опрос содержит следующие параметры:
| Параметры | |
|---|---|
client_id |
Идентификатор клиента для вашего приложения. Это значение можно найти на странице клиентов в Cloud Console. |
client_secret |
Секретный код клиента для указанного client_id. Это значение можно найти на странице клиентов в Cloud Console. |
device_code |
device_code, возвращенный сервером авторизации на шаге 2. |
grant_type |
Установите значение urn:ietf:params:oauth:grant-type:device_code. |
Примеры
Ниже приведен пример запроса.
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 |
Токен, который ваше приложение отправляет для авторизации запроса к API Google. |
expires_in |
Оставшееся время действия токена доступа в секундах. |
refresh_token |
Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны, пока пользователь не отзовет доступ или не истечет срок действия токена обновления. Обратите внимание, что токены обновления всегда возвращаются для устройств. |
scope |
Области действия доступа, предоставленные access_token, в виде списка строк, разделенных пробелами, с учетом регистра. |
token_type |
Тип возвращенного токена. Это значение всегда равно Bearer. |
Ниже приведен пример ответа:
{ "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). К ним относятся:
| Ошибка | Код статуса HTTP | Описание |
|---|---|---|
admin_policy_enforced |
400 |
Аккаунт Google не может авторизовать одну или несколько запрошенных областей действия из-за правил, установленных администратором Google Workspace. Подробнее о том, как администратор может ограничить доступ к областям действия, пока он не будет явно предоставлен вашему идентификатору клиента OAuth, рассказывается в статье Справочного центра для администраторов Google Workspace Как управлять доступом сторонних и внутренних приложений к данным Google Workspace. |
invalid_client |
401 |
Клиент OAuth не найден. Например, эта ошибка возникает, если значение параметра Неверный тип клиента OAuth. Убедитесь, что для типа приложения в идентификаторе клиента задано значение Телевизоры и устройства с ограниченными возможностями ввода. |
invalid_grant |
400 |
Значение параметра code недействительно, уже заявлено или не может быть проанализировано. |
unsupported_grant_type |
400 |
Недопустимое значение параметра grant_type. |
org_internal |
403 |
Идентификатор клиента OAuth в запросе относится к проекту, который ограничивает доступ к аккаунтам Google в определенной организации Google Cloud. Проверьте тип пользователя в настройках приложения OAuth. |
Как вызывать API Google
Получив токен доступа, приложение может использовать его для вызова Google API от имени определенного аккаунта пользователя, если предоставлены необходимые для API области доступа. Для этого включите токен доступа в запрос к API, добавив параметр запроса access_token или значение заголовка HTTP Authorization Bearer. По возможности лучше использовать заголовок HTTP, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев для настройки вызовов API Google можно использовать клиентскую библиотеку (например, при вызове YouTube Live Streaming API).
Обратите внимание, что YouTube Live Streaming API не поддерживает поток аккаунта сервиса. Поскольку связать сервисный аккаунт с аккаунтом YouTube невозможно, попытки авторизовать запросы с помощью этого процесса приведут к ошибке NoLinkedYouTubeAccount.
Вы можете попробовать все API Google и посмотреть их области действия в OAuth 2.0 Playground.
Примеры запросов HTTP GET
Вызов конечной точки
liveBroadcasts.list (YouTube Live Streaming API) с использованием 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), который включает следующие параметры в теле запроса:
| Название | Значение |
|---|---|
client_id |
Идентификатор клиента, полученный из API Console. |
client_secret |
Необязательно
Секретный код клиента, полученный из API Console. |
grant_type |
В соответствии со спецификацией OAuth 2.0 в этом поле должно быть указано значение refresh_token. |
refresh_token |
Токен обновления, возвращенный в результате обмена кодами авторизации. |
Ниже приведен пример запроса.
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Если пользователь не отозвал доступ, предоставленный приложению, сервер токенов возвращает объект JSON, содержащий новый токен доступа. Ниже приведен пример ответа:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "scope": "https://www.googleapis.com/auth/youtube.force-ssl 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 для устройств поддерживается только для следующих областей действия:
OpenID Connect, Вход с аккаунтом Google
emailopenidprofile
Drive API
https://www.googleapis.com/auth/drive.appdatahttps://www.googleapis.com/auth/drive.file
YouTube API
https://www.googleapis.com/auth/youtubehttps://www.googleapis.com/auth/youtube.readonly
Доступ на основе времени
Временный доступ позволяет пользователю предоставить приложению доступ к своим данным на ограниченный период времени, чтобы выполнить определенное действие. В некоторых продуктах Google при запросе разрешений пользователи могут предоставить доступ на ограниченное время. Пример – Data Portability API, который позволяет выполнить однократный перенос данных.
Если пользователь предоставляет вашему приложению доступ на определенный период времени, токен обновления станет недействительным по истечении этого периода. Обратите внимание, что в некоторых случаях токены обновления могут быть аннулированы раньше. Подробнее об этом рассказывается в этой статье. В таких случаях поле refresh_token_expires_in, возвращаемое в ответе на обмен кодами авторизации, представляет собой время, оставшееся до истечения срока действия токена обновления.
Как включить защиту связанных аккаунтов
Чтобы дополнительно защитить аккаунты пользователей, реализуйте защиту связанных аккаунтов с помощью сервиса защиты связанных аккаунтов Google. Этот сервис позволяет подписаться на уведомления о событиях безопасности, которые предоставляют вашему приложению информацию о важных изменениях в аккаунте пользователя. Затем вы можете использовать эту информацию, чтобы предпринять действия в зависимости от того, как вы решите реагировать на события.
Вот некоторые примеры типов событий, которые сервис защиты связанных аккаунтов Google отправляет в ваше приложение:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Подробнее о том, как реализовать защиту связанных аккаунтов и какие события доступны, рассказывается на странице Защита аккаунтов пользователей с помощью функции "Защита связанных аккаунтов" .