OAuth 2.0 для мобильных и настольных приложений

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

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

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

Этот процесс авторизации аналогичен процессу, используемому для приложений веб-сервера . Основное отличие заключается в том, что установленные приложения должны открывать системный браузер и предоставлять локальный URI перенаправления для обработки ответов сервера авторизации Google.

Библиотеки и образцы

Для мобильных приложений мы рекомендуем использовать последнюю версию нативной библиотеки Google Identity Services для Android и нативную библиотеку Google Sign-In для iOS . Эти библиотеки обрабатывают авторизацию пользователей и проще в реализации, чем описанный здесь протокол более низкого уровня.

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

Предпосылки

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

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

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

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

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

Документ «Области действия API OAuth 2.0» содержит полный список областей действия, которые можно использовать для доступа к API Google.

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

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

Шаг 1: Создайте верификатор кода и задайте вопрос

Google поддерживает протокол Proof Key for Code Exchange (PKCE) для повышения безопасности процесса установки приложения. Для каждого запроса авторизации создаётся уникальный код-верификатор, и его преобразованное значение, называемое «code_challenge», отправляется на сервер авторизации для получения кода авторизации.

Создайте верификатор кода

code_verifier — это высокоэнтропийная криптографическая случайная строка, использующая незарезервированные символы [AZ] / [az] / [0-9] / "-" / "." / "_" / "~", минимальной длиной 43 символа и максимальной длиной 128 символов.

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

Создайте кодовое задание

Поддерживаются два метода создания задания по коду.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Шаг 2: Отправьте запрос на сервер OAuth 2.0 Google.

Чтобы получить авторизацию пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth . Эта конечная точка обрабатывает поиск активных сеансов, аутентифицирует пользователя и получает его согласие. Доступ к конечной точке возможен только по протоколу SSL, и она отклоняет HTTP-подключения (не SSL).

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

Примеры URL-адресов авторизации

На вкладках ниже показаны примеры URL-адресов авторизации для различных вариантов URI перенаправления.

URL-адреса идентичны, за исключением значения параметра redirect_uri . URL-адреса также содержат обязательные параметры response_type и client_id , а также необязательный параметр state . Каждый URL-адрес содержит переносы строк и пробелы для удобства чтения.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Шаг 3: Google запрашивает согласие пользователя

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

На этом этапе вашему приложению не нужно ничего делать, так как оно ожидает ответа от сервера Google OAuth 2.0 о предоставлении доступа. Этот ответ поясняется на следующем шаге.

Шаг 4: Обработка ответа сервера OAuth 2.0

Способ получения вашим приложением ответа на запрос авторизации зависит от используемой им схемы URI перенаправления . Независимо от схемы, ответ будет содержать либо код авторизации ( code ), либо ошибку ( error ). Например, error=access_denied означает, что пользователь отклонил запрос.

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

Шаг 5: Обмен кода авторизации на токены обновления и доступа

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

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

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

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google отвечает на этот запрос, возвращая JSON-объект, содержащий кратковременный токен доступа и токен обновления.

Ответ содержит следующие поля:

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Шаг 6: Проверьте, какие области действия предоставлены пользователями

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

Однако есть исключения. Приложения Google Workspace Enterprise с делегированием полномочий на уровне домена или приложения, помеченные как «Доверенные» , обходят экран согласия на детализированные разрешения. В таких приложениях пользователи не увидят экран согласия на детализированные разрешения. Вместо этого ваше приложение либо получит все запрошенные области действия, либо не получит ни одной.

Более подробную информацию см. в разделе Как обрабатывать детализированные разрешения .

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

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

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Вызов API Google

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

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

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

Примеры HTTP GET

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

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

примеры curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

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

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&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",
  "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 вместе с кодом ошибки.

Методы перенаправления приложений

Защитите свои приложения

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

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

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

Дополнительное чтение

В документе IETF Best Current Practice OAuth 2.0 для нативных приложений изложены многие из описанных здесь передовых практик.