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

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

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

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

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

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

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

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

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

Мы рекомендуем следующие библиотеки и примеры, которые помогут вам реализовать процесс OAuth 2.0, описанный в этом документе:

• AppAuth для библиотеки Android
• AppAuth для библиотеки iOS
• OAuth для приложений: примеры для Windows

Предпосылки

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

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

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

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

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

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

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

Получение токенов доступа 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. Отправьте запрос на сервер Google OAuth 2.0.

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

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

Шаг 4. Обработайте ответ сервера OAuth 2.0

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

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

Шаг 5. Код авторизации Exchange для токенов обновления и доступа

Чтобы обменять код авторизации на токен доступа, вызовите конечную точку 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"
}

Вызов API Google

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

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

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

Примеры HTTP-запроса

Вызов конечной точки 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 вместе с кодом ошибки.

Дальнейшее чтение

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