В этом документе объясняется, как приложения, установленные на таких устройствах, как телефоны, планшеты и компьютеры, используют конечные точки OAuth 2.0 от Google для авторизации доступа к YouTube Data API.
OAuth 2.0 позволяет пользователям делиться определенными данными с приложением, сохраняя при этом свои имена пользователей, пароли и другую конфиденциальную информацию. Например, приложение может использовать OAuth 2.0, чтобы получить разрешение на загрузку видео на канал YouTube пользователя.
Установленные приложения распространяются на отдельные устройства, и предполагается, что эти приложения не могут хранить секреты. Они могут получать доступ к API Google, когда пользователь находится в приложении или когда оно работает в фоновом режиме.
Этот процесс авторизации похож на тот, который используется для приложений веб-сервера. Основное отличие заключается в том, что установленные приложения должны открывать системный браузер и предоставлять локальный URI перенаправления для обработки ответов от сервера авторизации Google.
Библиотеки и примеры кода
Для приложений iOS мы рекомендуем использовать последнюю версию Sign In With Google iOS SDK. SDK обрабатывает авторизацию пользователей и проще в реализации, чем описанный в этом руководстве низкоуровневый протокол.
Если приложение работает на устройстве, которое не поддерживает системный браузер или имеет ограниченные возможности ввода (например, на телевизоре, игровой консоли, камере или принтере), ознакомьтесь со статьями OAuth 2.0 для телевизоров и других устройств и Вход в аккаунт на телевизорах и устройствах с ограниченными возможностями ввода.
Требования
Как включить API для проекта
Любое приложение, вызывающее API Google, должно включить эти API в API Console.
Чтобы включить API для вашего проекта:
- Откройте библиотеку API в Google API Console.
- Выберите существующий проект или создайте новый.
- Найдите и включите YouTube Data API на странице Библиотека. Найдите другие API, которые будет использовать ваше приложение, и включите их.
Как создать учетные данные для авторизации
Любое приложение, которое использует OAuth 2.0 для доступа к API Google, должно иметь учетные данные для авторизации, которые идентифицируют приложение на сервере OAuth 2.0 Google. Ниже описано, как создать учетные данные для проекта. После этого ваши приложения смогут использовать учетные данные для доступа к API, которые вы включили для этого проекта.
- Перейдите на страницу клиентов.
- Нажмите Создать клиент.
- В следующих разделах описаны типы клиентов, которые поддерживает сервер авторизации Google. Выберите тип клиента, рекомендуемый для вашего приложения, укажите название клиента OAuth и заполните другие поля формы.
iOS
- Выберите тип приложения iOS.
- Введите название клиента OAuth. Это название будет показываться на странице клиентов вашего проекта.
- Введите идентификатор пакета приложения. Это значение ключа CFBundleIdentifier в файле списка свойств приложения (info.plist). Обычно это значение отображается на панели General (Общие) или Signing & Capabilities (Подпись и возможности) в редакторе проектов Xcode. Идентификатор пакета также можно найти в разделе "Общая информация" на странице "Информация о приложении" на сайте Apple App Store Connect.
Убедитесь, что вы используете правильный идентификатор пакета для своего приложения, так как вы не сможете изменить его, если используете функцию проверки приложений.
- (Необязательно)
Если приложение опубликовано в Apple App Store, укажите его идентификатор. Идентификатор магазина – это числовая строка, которая есть в каждом URL Apple App Store.
- Откройте приложение Apple App Store на устройстве iOS или iPadOS.
- Выполните поиск по названию своего приложения.
- Нажмите кнопку "Поделиться" (квадрат со стрелкой вверх).
- Выберите Копировать ссылку.
- Вставьте ссылку в текстовый редактор. Идентификатор магазина приложений – это последняя часть URL.
Пример:
https://apps.apple.com/app/google/id284815942
- (Необязательно)
Введите идентификатор команды. Подробную информацию можно найти в разделе Как найти идентификатор команды документации по аккаунту разработчика Apple.
Примечание. Если вы включаете проверку приложений для клиента, необходимо заполнить поле Team ID (Идентификатор команды). - (Необязательно)
Включите проверку приложений для приложения iOS. Когда вы включите проверку приложений, сервис App Attest от Apple будет использоваться для проверки того, что запросы OAuth 2.0, исходящие от вашего клиента OAuth, являются подлинными и поступают из вашего приложения. Это помогает снизить риск подмены приложения. Подробнее о том, как включить App Check для приложения iOS…
- Нажмите Создать.
UWP
- Выберите тип приложения Universal Windows Platform.
- Введите название клиента OAuth. Это название будет показываться на странице вашего проекта, чтобы идентифицировать клиента.
- Введите 12-значный идентификатор приложения в Microsoft Store. Это значение можно найти в Центре партнеров Microsoft на странице Идентификация приложения в разделе "Управление приложениями".
- Нажмите Создать.
Для приложений UWP URI переадресации формируется с использованием уникального идентификатора безопасности пакета (SID) приложения. Package SID приложения можно найти в файле Package.appxmanifest в проекте Visual Studio.
При создании идентификатора клиента в консоли Google Cloud необходимо указать URI перенаправления в следующем формате, используя значение SID пакета в нижнем регистре:
ms-app://YOUR_APP_PACKAGE_SID
Для приложений UWP длина специальной схемы URI не может превышать 39 символов, как указано в документации Microsoft.
Как определить области доступа
Области действия позволяют приложению запрашивать доступ только к тем ресурсам, которые ему нужны, а пользователям – контролировать объем доступа, который они предоставляют приложению. Таким образом, может существовать обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя.
Прежде чем приступать к реализации авторизации 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 API приведен полный список областей действия, которые можно использовать для доступа к API Google.
Получение токенов доступа OAuth 2.0
Ниже описано, как ваше приложение взаимодействует с сервером OAuth 2.0 от Google, чтобы получить согласие пользователя на выполнение запроса к API от его имени. Приложение должно получить такое согласие, прежде чем выполнять запрос к API Google, требующий авторизации пользователя.
Шаг 1. Сгенерируйте код подтверждения и запрос
Google поддерживает протокол Proof Key for Code Exchange (PKCE), который повышает безопасность установленных приложений. Для каждого запроса авторизации создается уникальный верификатор кода, а его преобразованное значение, называемое code_challenge, отправляется на сервер авторизации для получения кода авторизации.
Создайте верификатор кода
code_verifier – это криптографическая случайная строка с высокой энтропией, в которой используются незарезервированные символы [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~". Минимальная длина строки – 43 символа, максимальная – 128.
У верификатора кода должно быть достаточно энтропии, чтобы угадать значение было невозможно.
Создайте код для подтверждения
Поддерживаются два способа создания запроса кода.
| Методы генерации кода подтверждения | |
|---|---|
| S256 (рекомендуется) | Код вызова – это хеш SHA256 верификатора кода, закодированный по стандарту Base64 для URL (без заполнения).
|
| plain | Значение code_challenge совпадает со значением code_verifier, сгенерированным выше.
|
Шаг 2. Отправьте запрос на сервер OAuth 2.0 Google
Чтобы получить разрешение пользователя, отправьте запрос на сервер авторизации Google по адресу https://accounts.google.com/o/oauth2/v2/auth. Этот конечный адрес используется для поиска активного сеанса, аутентификации пользователя и получения его согласия. Конечная точка доступна только через SSL и отклоняет подключения HTTP (без SSL).
Сервер авторизации поддерживает следующие параметры строки запроса для установленных приложений:
| Параметры | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
client_id |
Обязательно
Идентификатор клиента для вашего приложения. Это значение можно найти на странице клиентов в Cloud Console. |
||||||||||||||||
redirect_uri |
Обязательно
Определяет, как сервер авторизации Google отправляет ответ вашему приложению. Для установленных приложений доступно несколько вариантов перенаправления. Вы можете настроить учетные данные авторизации с учетом определенного метода перенаправления. Значение должно точно совпадать с одним из авторизованных URI перенаправления для клиента OAuth 2.0, который вы настроили на странице клиентов в Cloud Console. Если это значение не совпадает с авторизованным URI, вы получите ошибку В таблице ниже указаны подходящие значения параметра
|
||||||||||||||||
response_type |
Обязательно
Определяет, возвращает ли конечная точка Google OAuth 2.0 код авторизации. Для установленных приложений задайте значение параметра |
||||||||||||||||
scope |
Обязательно
Список областей действия, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения используются в окне запроса согласия, которое Google показывает пользователю. Области действия позволяют приложению запрашивать доступ только к тем ресурсам, которые ему нужны, а пользователям – контролировать объем доступа, который они предоставляют приложению. Таким образом, существует обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя. YouTube Data API v3 использует следующие области действия:
В документе Области действия API OAuth 2.0 приведен полный список областей действия, которые можно использовать для доступа к API Google. |
||||||||||||||||
code_challenge |
Рекомендуется
Указывает закодированный |
||||||||||||||||
code_challenge_method |
Рекомендуется
Указывает, какой метод использовался для кодирования |
||||||||||||||||
state |
Рекомендуется
Любое строковое значение, которое ваше приложение использует для сохранения состояния между запросом авторизации и ответом сервера авторизации.
Сервер возвращает точное значение, которое вы отправили в виде пары Этот параметр можно использовать для разных целей, например чтобы направлять пользователя к нужному ресурсу в приложении, отправлять одноразовые коды и предотвращать подделку межсайтовых запросов. Поскольку |
||||||||||||||||
login_hint |
Необязательно
Если приложение знает, какой пользователь пытается выполнить аутентификацию, оно может использовать этот параметр, чтобы предоставить подсказку серверу аутентификации Google. Сервер использует подсказку, чтобы упростить процесс входа, заполнив поле адреса электронной почты в форме входа или выбрав соответствующий сеанс с несколькими входами. В качестве значения параметра укажите адрес электронной почты или идентификатор |
||||||||||||||||
Примеры URL авторизации
На вкладках ниже приведены примеры URL авторизации для разных вариантов URI переадресации.
Каждый URL запрашивает доступ к области, которая позволяет просматривать аккаунт пользователя YouTube.URL идентичны, за исключением значения параметра redirect_uri. URL также содержат обязательные параметры response_type и client_id, а также необязательный параметр state. Для удобства чтения в URL добавлены пробелы и разрывы строк.
Специальная схема URI
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
IP-адрес обратной связи
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, к которым оно запрашивает доступ с учетными данными авторизации пользователя, а также краткое описание областей действия, которые будут предоставлены. Затем пользователь может предоставить доступ к одному или нескольким областям действия, запрошенным вашим приложением, или отклонить запрос.
На этом этапе вашему приложению не нужно ничего делать, пока оно ожидает ответа от сервера OAuth 2.0 Google, указывающего, был ли предоставлен доступ. Этот ответ описан на следующем шаге.
Ошибки
Запросы к конечной точке авторизации OAuth 2.0 от Google могут приводить к показу пользовательских сообщений об ошибках вместо ожидаемых процессов аутентификации и авторизации. Ниже приведены распространенные коды ошибок и способы их устранения.
admin_policy_enforced
Аккаунт Google не может авторизовать одну или несколько запрошенных областей действия из-за правил, установленных администратором Google Workspace. Подробнее о том, как администратор может ограничить доступ ко всем областям действия или только к конфиденциальным и с ограниченным доступом, пока доступ не будет явно предоставлен вашему идентификатору клиента OAuth, рассказывается в справочной статье Справочного центра для администраторов Google Workspace Как управлять доступом сторонних и внутренних приложений к данным Google Workspace.
disallowed_useragent
Конечная точка авторизации отображается во встроенном агенте пользователя, который запрещен правилами OAuth 2.0 Google.
Разработчики iOS и macOS могут столкнуться с этой ошибкой при открытии запросов на авторизацию в WKWebView.
Вместо этого разработчикам следует использовать библиотеки iOS, такие как вход с аккаунтом Google для iOS или AppAuth для iOS от OpenID Foundation.
Веб-разработчики могут столкнуться с этой ошибкой, когда приложение для iOS или macOS открывает общую веб-ссылку во встроенном агенте пользователя, а пользователь переходит на конечную точку авторизации OAuth 2.0 Google с вашего сайта. Разработчикам следует разрешить открывать обычные ссылки в обработчике ссылок по умолчанию, который используется в операционной системе. К нему относятся обработчики универсальных ссылок и браузер по умолчанию. Также поддерживается библиотека SFSafariViewController.
org_internal
Идентификатор клиента OAuth в запросе является частью проекта, ограничивающего доступ к аккаунтам Google в определенной организации Google Cloud. Подробнее об этом параметре конфигурации см. в разделе Тип пользователя справочной статьи Настройка окна запроса доступа OAuth.
deleted_client
Клиент OAuth, используемый для выполнения запроса, был удален. Удаление может быть выполнено вручную или автоматически в случае неиспользуемых клиентов . Удаленных клиентов можно восстановить в течение 30 дней после удаления. Подробнее…
invalid_grant
Если вы используете верификатор кода и запрос, параметр code_callenge недействителен или отсутствует. Убедитесь, что параметр code_challenge задан правильно.
При обновлении токена доступа срок его действия может истечь или он может быть аннулирован. Повторно аутентифицируйте пользователя и запросите у него согласие на получение новых токенов. Если вы продолжаете видеть эту ошибку, убедитесь, что ваше приложение настроено правильно и что вы используете правильные токены и параметры в своем запросе. В противном случае аккаунт пользователя может быть удален или отключен.
redirect_uri_mismatch
Параметр redirect_uri, переданный в запросе на авторизацию, не соответствует авторизованному URI переадресации для идентификатора клиента OAuth. Проверьте авторизованные URI перенаправления на странице клиентов в консоли Google Cloud.
Переданный параметр redirect_uri может быть недопустимым для этого типа клиента.
Параметр redirect_uri может относиться к внеполосному потоку OAuth, который устарел и больше не поддерживается. Чтобы обновить интеграцию, следуйте инструкциям в руководстве по переносу.
invalid_request
При обработке запроса произошла ошибка. Это может быть связано со следующими причинами:
- Неправильный формат запроса
- В запросе отсутствовали обязательные параметры
- В запросе используется способ авторизации, который не поддерживается Google. Убедитесь, что в вашей интеграции OAuth используется рекомендуемый метод интеграции.
- Для URI переадресации использовалась неподдерживаемая специальная схема. Если вы видите сообщение об ошибке Пользовательская схема URI не поддерживается в приложениях для Android и Chrome, ознакомьтесь с альтернативными вариантами.
Шаг 4. Обработайте ответ сервера OAuth 2.0
Способ получения ответа на запрос авторизации зависит от схемы URI переадресации, используемой приложением. Независимо от схемы ответ будет содержать код авторизации (code) или ошибку (error). Например, error=access_denied означает, что пользователь отклонил запрос.
Если пользователь предоставит доступ к вашему приложению, вы сможете обменять код авторизации на токен доступа и токен обновления, как описано на следующем шаге.
Шаг 5. Обменяйте код авторизации на токены обновления и доступа
Чтобы обменять код авторизации на токен доступа, вызовите конечную точку https://oauth2.googleapis.com/token и задайте следующие параметры:
| Поля | |
|---|---|
client_id |
Идентификатор клиента, полученный на странице клиентов в Cloud Console. |
client_secret |
Необязательно
Секретный код клиента, полученный на странице клиентов в Cloud Console. |
code |
Код авторизации, возвращенный в ответ на исходный запрос. |
code_verifier |
Верификатор кода, созданный на шаге 1. |
grant_type |
Согласно спецификации OAuth 2.0, значение этого поля должно быть равно authorization_code. |
redirect_uri |
Один из URI переадресации, указанных для вашего проекта на странице клиентов в Cloud Console для client_id. |
Использовать DPoP необязательно, но рекомендуется для повышения безопасности. Безопасность DPoP зависит от того, ограничен ли закрытый ключ одним устройством. Мы рекомендуем хранить его так, чтобы его нельзя было скопировать с устройства, например с помощью TPM, Secure Enclave или других аппаратных хранилищ ключей. Чтобы использовать DPoP, ваше приложение должно генерировать новый уникальный JWT-токен подтверждения DPoP для каждого запроса к конечной точке токена и добавлять его в качестве заголовка HTTP-запроса.
| Заголовок | Обязательно | Описание |
|---|---|---|
DPoP |
Необязательно | Подтверждение DPoP – это JWT, который подтверждает владение закрытым ключом. Это заголовок, а не параметр. Если он указан, возвращаемые токены привязываются к этому ключу. Для каждого запроса необходимо генерировать новое уникальное подтверждение, которое должно включать утверждения htm (метод HTTP) и htu (URI HTTP), соответствующие запросу. |
Ниже приведен пример запроса.
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\ VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\ nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\ QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\ oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\ WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\ 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your_client_id& redirect_uri=http://127.0.0.1:9004& grant_type=authorization_code
Как создать доказательство DPoP
Ниже описано, как создать подтверждение DPoP с помощью OpenSSL в командной строке.
- Создайте пару ключей EC P-256:
openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
- Создайте заголовок DPoP:
Заголовок должен содержать утверждения
typ,algиjwk(открытый ключ). Значенияxиy– это закодированные в Base64Url координаты вашего открытого ключа EC. Закодируйте этот JSON-код с помощью Base64Url:{ "typ":"dpop+jwt", "alg":"ES256", "jwk": { "kty":"EC", "x":"YOUR_PUBLIC_KEY_X", "y":"YOUR_PUBLIC_KEY_Y", "crv":"P-256" } } - Создайте полезную нагрузку DPoP.
Полезная нагрузка должна включать
jti(уникальный идентификатор запроса),htm(метод HTTP, напримерPOST),htu(URI HTTP, напримерhttps://oauth2.googleapis.com/token) иiat(время выдачи). Если вы получили одноразовый код от сервера в заголовкеDPoP-Nonceв ответе на предыдущий запрос, вы должны включить это значение одноразового кода в утверждениеnonce. Заявление nonce является необязательным для обмена кода авторизации и используется только в том случае, если ранее был получен заголовок DPoP-Nonce. Закодируйте этот JSON-код с помощью Base64Url:{ "jti":"JTI_VALUE", "htm":"POST", "htu":"https://oauth2.googleapis.com/token", "iat":YOUR_JWT_ISSUED_TIME, "nonce":"SERVER_PROVIDED_NONCE" }Значение
jtiзависит от типа биржи:- При обмене кода авторизации параметр
jtiдолжен представлять собой хеш SHA256 кода авторизации, закодированный в Base64Url:"jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))". - Для обмена токенами обновления параметр
jtiдолжен быть уникальным идентификатором для каждого запроса:"jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
- При обмене кода авторизации параметр
- Подпишите подтверждение:
Объедините закодированный заголовок и полезную нагрузку, разделив их точкой (
.), а затем подпишите результат закрытым ключом, используя ES256. Обратите внимание, что JWS требует, чтобы подпись была в необработанном объединенном форматеR | S(64 байта для P-256). Если вы используете OpenSSL напрямую, вам нужно преобразовать подпись, закодированную по умолчанию в формате ASN.1 DER, в этот необработанный формат.
Успешный обмен обозначается ответом 200 OK, содержащим токены. Если при обмене используется действительное подтверждение DPoP, токен обновления, возвращаемый Google, будет привязан к вашему ключу с помощью DPoP, а токены доступа – нет. Токены доступа сохранят token_type Bearer вместо DPoP.
Кроме того, Google возвращает в ответе HTTP-заголовок DPoP-Nonce.
Клиент должен кешировать этот nonce и включать его в утверждение nonce подтверждения DPoP в последующих запросах (например, при обмене токена обновления на новый токен доступа или при вызове API, защищенных DPoP). Используя этот одноразовый код, вы можете избежать дополнительной ошибки (use_dpop_nonce) при следующем запросе.
Доказательства DPoP должны быть включены в запросы на обмен токенов, созданные с помощью токенов обновления, связанных с DPoP.
Сбой обмена происходит, если заголовок DPoP отсутствует, когда он ожидается, недействителен или если в подтверждении используется ключ, отличный от того, который привязан к токену. В таких случаях сервер возвращает ошибку 400 Bad Request.
Если в подтверждении DPoP есть несовпадающие утверждения htm или htu, просроченное утверждение iat, повторно использованное утверждение jti или недействительная подпись, Google возвращает код ошибки invalid_dpop_proof.
Если требуется одноразовый код DPoP, например при обмене токена обновления, а в подтверждении DPoP отсутствует утверждение nonce или значение одноразового кода неприемлемо для сервера (например, оно устарело, уже использовалось или неправильное), Google возвращает код ошибки use_dpop_nonce вместе с HTTP-заголовком DPoP-Nonce, содержащим новый одноразовый код, который можно использовать в следующем запросе.
В других случаях может возвращаться значение invalid_grant.
В ответ на этот запрос Google возвращает объект JSON, содержащий токен доступа с коротким сроком действия и токен обновления.
Ответ содержит следующие поля:
| Поля | |
|---|---|
access_token |
Токен, который приложение отправляет для авторизации запроса к API Google. |
expires_in |
Оставшееся время действия токена доступа в секундах. |
id_token |
Примечание. Это свойство возвращается, только если запрос включает область идентификации, например openid, profile или email. Значение представляет собой веб-токен JSON (JWT), который содержит информацию о пользователе с цифровой подписью. |
refresh_token |
Токен, который можно использовать для получения нового токена доступа. Токены обновления действительны, пока пользователь не отзовет доступ или не истечет срок действия токена обновления. Если использовался протокол DPoP, токен обновления будет связан с закрытым ключом, который использовался для подписи доказательства DPoP. Обратите внимание, что для установленных приложений всегда возвращаются токены обновления. |
refresh_token_expires_in |
Оставшийся срок действия токена обновления в секундах. Это значение задается только в том случае, если пользователь предоставляет временный доступ. |
scope |
Области действия, предоставленные access_token, в виде списка строк, разделенных пробелами и с учетом регистра. |
token_type |
Тип возвращенного токена. Это значение всегда равно Bearer, даже если используется DPoP. |
Ниже приведен пример заголовков и тела успешного ответа при использовании DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"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
Получив токен доступа, приложение может использовать его для вызова Google API от имени определенного аккаунта пользователя, если предоставлены необходимые для API области доступа. Для этого включите токен доступа в запрос к API, добавив параметр запроса access_token или значение заголовка HTTP Authorization Bearer. По возможности лучше использовать заголовок HTTP, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев для настройки вызовов API Google можно использовать клиентскую библиотеку (например, при вызове YouTube Data API).
Обратите внимание, что YouTube Data API поддерживает сервисные аккаунты только для владельцев контента, которые управляют несколькими каналами YouTube, например для звукозаписывающих компаний и киностудий.
Вы можете попробовать все API Google и посмотреть их области действия в OAuth 2.0 Playground.
Примеры HTTP GET
Вызов конечной точки
youtube.channels (YouTube Data API) с использованием 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), который включает в тело запроса следующие параметры:
| Название | Значение |
|---|---|
client_id |
Идентификатор клиента, полученный из API Console. |
client_secret |
Необязательно
Секретный код клиента, полученный из API Console.
(Параметр |
grant_type |
В соответствии со спецификацией OAuth 2.0 в этом поле должно быть указано значение refresh_token. |
refresh_token |
Маркер обновления, возвращенный при обмене кода авторизации. |
Использование DPoP не обязательно, но рекомендуется для повышения уровня безопасности. Чтобы использовать DPoP с токеном обновления, ваше приложение должно генерировать новый уникальный JWT-токен подтверждения DPoP для каждого запроса к конечной точке токена. Доказательство должно быть подписано тем же закрытым ключом, который использовался при первоначальном обмене кода авторизации. Приложение добавляет подтверждение в качестве заголовка HTTP-запроса.
| Заголовок | Обязательно | Описание |
|---|---|---|
DPoP |
Необязательно | Подтверждение DPoP – это JWT, который подтверждает владение закрытым ключом. Это заголовок, а не параметр. Если он указан, возвращаемые токены привязываются к этому ключу. Для каждого запроса необходимо генерировать новое уникальное подтверждение, которое должно включать утверждения htm (метод HTTP) и htu (URI HTTP), соответствующие запросу. |
Ниже приведен пример запроса.
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded DPoP: DPOP_PROOF_JWT client_id=your_client_id& refresh_token=refresh_token& grant_type=refresh_token
Чтобы использовать DPoP с токеном обновления, необходимо сгенерировать новый уникальный JWT-токен подтверждения DPoP для запроса. Пошаговые инструкции по созданию пары ключей и JWT приведены в разделе Как создать доказательство DPoP.
Успешный обмен обозначается ответом 200 OK, содержащим новый токен доступа. Если используется DPoP, значение параметра token_type – Bearer. Успешный ответ подтверждает, что доказательство DPoP для токена обновления было принято. Google также может вернуть в ответе новый HTTP-заголовок DPoP-Nonce. В этом случае ваш клиент должен кешировать этот одноразовый код и включать его в утверждение nonce подтверждения DPoP в последующих запросах.
Если заголовок DPoP отсутствует, недействителен или в нем используется неправильный ключ, обмен не выполняется. Подробнее о кодах ошибок DPoP и обработке однократно используемых номеров…
Ниже приведен пример заголовков и тела успешного ответа при использовании DPoP:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI
{
"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 и код ошибки.
Методы перенаправления в приложение
Специальная схема URI
Специальные схемы URI – это ссылки на контент, которые используют специальную схему для открытия приложения.
Альтернатива использованию пользовательских схем URI в приложениях Chrome
Используйте Chrome Identity API, который передает ответ OAuth 2.0 непосредственно в ваше приложение, устраняя необходимость в URI переадресации.
Петлевой IP-адрес (macOS, Linux, Windows)
Чтобы получить код авторизации с помощью этого URL, ваше приложение должно прослушивать локальный веб-сервер. Это возможно на многих, но не на всех платформах. Однако если ваша платформа поддерживает этот способ, мы рекомендуем использовать именно его.
Когда приложение получит ответ авторизации, для лучшего удобства использования оно должно показать HTML-страницу с инструкцией закрыть браузер и вернуться в приложение.
| Рекомендуемое использование | Приложения для macOS, Linux и Windows (кроме Universal Windows Platform) |
| Значения формы | Выберите тип приложения Компьютерное приложение. |
Копирование и вставка вручную (поддержка прекращена)
Как защитить приложения
Как подтвердить право собственности на приложение для Chrome
Вы можете подтвердить право собственности на приложение, чтобы снизить риск его подделки.
Чтобы завершить проверку, используйте аккаунт разработчика в интернет-магазине Chrome. Чтобы успешно пройти проверку, необходимо выполнить следующие требования:
- В Личном кабинете разработчика продуктов для интернет-магазина Chrome должен быть зарегистрирован продукт с тем же идентификатором товара, что и у клиента OAuth расширения Chrome, для которого вы проходите проверку.
- Вы должны быть издателем продукта в интернет-магазине Chrome. Подробнее об управлении доступом в Личном кабинете разработчика продуктов для интернет-магазина Chrome…
В разделе Verify App Ownership (Подтверждение права собственности на приложение) клиента расширения Chrome нажмите кнопку Verify Ownership (Подтвердить право собственности), чтобы завершить процесс проверки.
Примечание. После того как вы предоставите доступ к аккаунту, подождите несколько минут, прежде чем завершать процесс подтверждения.
Если проверка пройдет успешно, вы увидите уведомление об этом. В противном случае появится сообщение об ошибке.
Чтобы устранить проблему, попробуйте сделать следующее:
- Убедитесь, что в Личном кабинете разработчика продуктов для интернет-магазина Chrome зарегистрирован продукт с тем же идентификатором, что и у OAuth-клиента расширения Chrome, для которого вы проходите проверку.
- Убедитесь, что вы являетесь издателем приложения, то есть его индивидуальным издателем или членом издательской группы. Подробнее об управлении доступом в личном кабинете разработчика продуктов для интернет-магазина Chrome…
- Если вы только что обновили список издателей группы, убедитесь, что список участников группы издателей синхронизирован в Личном кабинете разработчика продуктов для интернет-магазина Chrome. Подробнее о том, как синхронизировать список спонсоров…
App Check (только для iOS)
Функция App Check помогает защитить приложения для iOS от несанкционированного использования. Она проверяет, исходят ли запросы к конечным точкам Google OAuth 2.0 из ваших приложений, с помощью сервиса App Attest от Apple. Это помогает снизить риск имитации приложения.
Как включить App Check для клиента iOS
Чтобы включить проверку приложений для клиента iOS, необходимо выполнить следующие требования:- Укажите идентификатор команды для клиента iOS.
- В идентификаторе пакета нельзя использовать подстановочный знак, поскольку он может относиться к нескольким приложениям. Это значит, что идентификатор пакета не должен содержать символ звездочки (*).
После включения Проверки приложений в режиме редактирования клиента OAuth начнут показываться показатели, связанные с запросами OAuth от вашего клиента. Запросы из непроверенных источников не будут блокироваться, пока вы не включите принудительное использование Проверки приложений. Информация на странице мониторинга показателей поможет вам определить, когда начать принудительное применение.
При включении проверки приложений для приложения iOS могут возникать ошибки, связанные с этой функцией. Чтобы устранить их, попробуйте выполнить следующие действия:
- Убедитесь, что идентификаторы пакета и команды указаны правильно.
- Убедитесь, что вы не используете подстановочный знак для идентификатора пакета.
Как включить проверку приложений для клиента iOS
Включение Проверки приложений не приводит к автоматической блокировке нераспознанных запросов. Чтобы применить эту защиту, перейдите в режим редактирования клиента iOS. Показатели проверки приложений будут в правой части страницы в разделе Google Identity для iOS. Показатели включают следующую информацию:- Количество проверенных запросов – запросы с действительным токеном App Check. После того как вы включите принудительное применение App Check, будут выполняться только запросы из этой категории.
- Количество непроверенных запросов: вероятно, устаревшие клиентские запросы – запросы, в которых отсутствует токен App Check. Такие запросы могут поступать от более старой версии вашего приложения, в которой не реализована функция App Check.
- Количество неподтвержденных запросов: запросы из неизвестных источников – запросы без токена App Check, которые, по всей видимости, не исходят из вашего приложения.
- Количество непроверенных запросов: недействительные запросы – запросы с недействительным токеном Проверки приложений, которые могут поступать от поддельного клиента, пытающегося выдать себя за ваше приложение, или из эмулированных сред.
Чтобы включить Проверку приложений, нажмите кнопку ENFORCE и подтвердите выбор. После того как принудительное применение будет включено, все неподтвержденные запросы от вашего клиента будут отклоняться.
Примечание. После включения принудительного применения может пройти до 15 минут, прежде чем изменения вступят в силу.
Как отключить проверку приложений для клиента iOS
Если вы отключите проверку приложений, принудительное применение прекратится и все запросы от вашего клиента к конечным точкам Google OAuth 2.0, включая непроверенные, будут разрешены.
Чтобы отключить проверку приложений для клиента iOS, перейдите в режим редактирования клиента iOS, нажмите кнопку Отключить и подтвердите выбор.
Примечание. После отключения App Check изменения вступят в силу в течение 15 минут.
Как отключить проверку приложений для клиента iOS
Если вы отключите проверку приложений, то мониторинг и принудительное применение будут остановлены. Вместо этого вы можете отключить принудительное применение Проверки приложений, чтобы продолжить отслеживать показатели клиента.
Чтобы отключить проверку приложений для клиента iOS, перейдите в режим редактирования клиента iOS и отключите переключатель Защитите свой клиент OAuth от злоупотреблений с помощью Firebase App Check.
Примечание. После отключения проверки приложений изменения вступят в силу в течение 15 минут.
Доступ на основе времени
Временный доступ позволяет пользователю предоставить приложению доступ к своим данным на ограниченный период времени, чтобы выполнить определенное действие. В некоторых продуктах Google во время запроса согласия пользователям предлагается предоставить доступ на ограниченный период времени. Примером может служить Data Portability API, который позволяет однократно передавать данные.
Если пользователь предоставит приложению доступ на определенный срок, токен обновления будет действителен в течение этого срока. Обратите внимание, что токены обновления могут быть аннулированы раньше при определенных обстоятельствах. Подробнее о таких случаях… В таких случаях поле refresh_token_expires_in, возвращаемое в ответе на обмен кодами авторизации, представляет собой время, оставшееся до истечения срока действия токена обновления.
Дополнительные материалы
Многие из приведенных здесь рекомендаций основаны на документе OAuth 2.0 for Native Apps (OAuth 2.0 для нативных приложений), который опубликован на сайте IETF.
Как реализовать защиту связанных аккаунтов
Чтобы дополнительно защитить аккаунты пользователей, включите защиту связанных аккаунтов с помощью сервиса 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
Дополнительную информацию о том, как реализовать защиту связанных аккаунтов, и полный список доступных событий можно найти на странице Защита аккаунтов пользователей с помощью защиты связанных аккаунтов .