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

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

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

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

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

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

Предпосылки

Включите 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 Library перечислены все доступные API, сгруппированных по семейству продуктов и популярности. Если API вы хотите включить не отображается в списке, воспользуйтесь поиском , чтобы найти его, или нажмите Просмотреть все в семействе продуктов он принадлежит.
  4. Выберите API , который вы хотите включить, а затем нажмите кнопку Включить.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

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

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

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

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

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

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

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

Получение токенов доступа 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-запроса:

Параметры
client_id Необходимый

Идентификатор клиента для вашего приложения. Вы можете найти это значение в API ConsoleCredentials page.

scope Необходимый

Список областей, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения информируют экран согласия, который Google отображает пользователю. См Разрешенные SCOPES список для установленных приложений или устройств.

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

Примеры

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

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

client_id=client_id&scope=email%20profile

Этот пример показывает curl команду отправить тот же запрос:

curl -d "client_id=client_id&scope=email%20profile" \
     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 .

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

  • user_code
    • user_code должен отображаться в поле , которое может обрабатывать 15 символов размера «W». Другими словами, если вы можете отобразить код WWWWWWWWWWWWWWW правильно, ваш UI является действительным, и мы рекомендуем использовать эту строковое значение при тестировании на пути к 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 Идентификатор клиента для вашего приложения. Вы можете найти это значение в API ConsoleCredentials page.
client_secret Клиент секрет предоставленного client_id . Вы можете найти это значение в API ConsoleCredentials page.
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" \
         /token

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

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

Подключите устройство, введя код

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

Пример экрана согласия для клиента устройства

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

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

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

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

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

Поля
access_token Токен, который ваше приложение отправляет для авторизации запроса Google API.
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 в течение длительного периода времени, он может использовать токен обновление для получения нового маркеров доступа. Если вашему приложению нужен этот тип доступа, оно должно сохранить токен обновления для последующего использования.

В доступе отказано

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

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

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

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

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

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

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

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

Прочие ошибки

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

Ошибка Код состояния HTTP Описание
invalid_client 401 Клиент OAuth не найден. Например, эта ошибка возникает , если client_id значение параметра является недействительным.
invalid_grant 400 code Значение параметра является недействительным.
unsupported_grant_type 400 grant_type значение параметра является недействительным.

Вызов API Google

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

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

Примеры HTTP GET

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

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl примеры

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

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

Срок действия токенов доступа периодически истекает, и они становятся недействительными учетными данными для соответствующего запроса 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&
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",
  "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 Вход в систему

  • email
  • openid
  • profile

Drive API

  • https://www.googleapis.com/auth/drive.appdata
  • https://www.googleapis.com/auth/drive.file

YouTube API

  • https://www.googleapis.com/auth/youtube
  • https://www.googleapis.com/auth/youtube.readonly