В этом документе объясняется, как компьютерные приложения (например, работающие в Windows, macOS или Linux, или инструменты интерфейса командной строки) используют конечные точки OAuth 2.0 от Google для авторизации доступа к API Google.
OAuth 2.0 позволяет пользователям делиться с приложениями определенными данными, не разглашая при этом имена пользователей, пароли и другую конфиденциальную информацию. Например, приложение может использовать OAuth 2.0, чтобы получить от пользователей разрешение на хранение файлов на их Google Диске.
Приложения для компьютеров устанавливаются локально на компьютере пользователя (например, автономное программное обеспечение для компьютеров, инструменты CLI для разработчиков, утилиты фоновой синхронизации или скрипты). Поскольку эти приложения распространяются на отдельные устройства, предполагается, что они не могут хранить секреты (они являются общедоступными клиентами). Они могут обращаться к API Google, когда пользователь активно взаимодействует с приложением или когда оно работает в фоновом режиме.
Этот процесс авторизации похож на тот, который используется для приложений веб-сервера. Основное отличие заключается в том, что компьютерные приложения должны открывать системный браузер и предоставлять локальный URI перенаправления (например, IP-адрес обратной связи) для обработки ответов от сервера авторизации Google.
Библиотеки и примеры
При реализации OAuth 2.0 для компьютерных приложений мы рекомендуем использовать клиентские библиотеки Google API для вашего языка программирования (например, Python, Java, Node.js, Go, .NET). Клиентские библиотеки обрабатывают авторизацию пользователей и управление токенами, что делает реализацию более простой и менее подверженной ошибкам, чем использование конечных точек HTTP/REST более низкого уровня напрямую.
Для мобильных приложений ознакомьтесь с руководствами по авторизации для Android и iOS.
Если приложение работает на устройстве, которое не поддерживает системный браузер или имеет ограниченные возможности ввода (например, на телевизоре, игровой консоли, камере или принтере), ознакомьтесь со статьей OAuth 2.0 для телевизоров и других устройств или Вход в аккаунт на телевизорах и устройствах с ограниченными возможностями ввода.
Требования
Как включить API для проекта
Любое приложение, вызывающее API Google, должно включить эти API в API Console.
Чтобы включить API для вашего проекта:
- Откройте библиотеку API в Google API Console.
- Выберите существующий проект или создайте новый.
- В библиотеке API перечислены все доступные API, сгруппированные по семейству продуктов и популярности. Если нужного API нет в списке, воспользуйтесь поиском или нажмите Показать все в семействе продуктов, к которому он относится.
- Выберите нужный API и нажмите кнопку Включить.
- Если появится запрос, включите оплату.
- При необходимости прочтите и примите Условия использования API.
Создайте учетные данные для авторизации
Любое приложение, которое использует OAuth 2.0 для доступа к API Google, должно иметь учетные данные для авторизации, которые идентифицируют приложение на сервере OAuth 2.0 Google. Ниже описано, как создать учетные данные для проекта. После этого ваши приложения смогут использовать учетные данные для доступа к API, которые вы включили для этого проекта.
- Перейдите на страницу Клиенты.
- Нажмите Создать клиент.
- Выберите тип приложения Приложение для компьютеров.
- В поле Название введите название клиента OAuth. Это название будет показываться на странице клиентов вашего проекта.
- Нажмите Создать.
Идентификатор клиента и секретный код клиента будут созданы и показаны в консоли Google Cloud. Компьютерные приложения являются общедоступными клиентами и не могут хранить секреты в тайне. При запросе кодов авторизации всегда используйте PKCE (Proof Key for Code Exchange).
Определите области доступа
Области действия позволяют приложению запрашивать доступ только к необходимым ресурсам, а пользователям – контролировать объем доступа, который они предоставляют приложению. Таким образом, между количеством запрашиваемых областей и вероятностью получения согласия пользователя может существовать обратная зависимость.
Прежде чем приступать к реализации авторизации OAuth 2.0, рекомендуем определить области действия, к которым вашему приложению потребуется доступ.
Полный список областей действия, которые можно использовать для доступа к API Google, приведен в документе Области действия API OAuth 2.0.
Получение токенов доступа 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 показывает пользователю. Области действия позволяют приложению запрашивать доступ только к необходимым ресурсам, а пользователям – контролировать объем доступа, который они предоставляют приложению. Таким образом, существует обратная зависимость между количеством запрашиваемых областей и вероятностью получения согласия пользователя. |
||||||
code_challenge |
Рекомендуется
Указывает закодированный параметр |
||||||
code_challenge_method |
Рекомендуется
Указывает, какой метод использовался для кодирования |
||||||
state |
Рекомендуется
Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между запросом авторизации и ответом сервера авторизации.
Сервер возвращает точное значение, которое вы отправляете в виде пары Этот параметр можно использовать для разных целей, например для перенаправления пользователя к нужному ресурсу в приложении, отправки одноразовых кодов и защиты от подделки межсайтовых запросов. Поскольку ваш |
||||||
login_hint |
Необязательно
Если приложение знает, какой пользователь пытается выполнить аутентификацию, оно может использовать этот параметр, чтобы предоставить подсказку серверу аутентификации Google. Сервер использует подсказку, чтобы упростить процесс входа, заполнив поле адреса электронной почты в форме входа или выбрав подходящий сеанс с несколькими входами. Задайте в качестве значения параметра адрес электронной почты или идентификатор |
||||||
Примеры URL авторизации
На вкладках ниже показаны примеры URL авторизации для разных вариантов URI перенаправления.
URL идентичны, за исключением значения параметра redirect_uri. URL также содержат обязательные параметры response_type и client_id, а также необязательный параметр state. Для удобства чтения в URL добавлены разрывы строк и пробелы.
Специальная схема URI
https://accounts.google.com/o/oauth2/v2/auth? scope=email%20profile& 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=email%20profile& 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, к которым оно запрашивает доступ, учетные данные пользователя для авторизации и сводка по областям доступа, которые будут предоставлены. Пользователь может предоставить доступ к одной или нескольким областям действия, запрошенным вашим приложением, или отклонить запрос.
На этом этапе вашему приложению не нужно ничего делать, пока оно ожидает ответа от сервера 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_challenge недействителен или отсутствует. Убедитесь, что параметр code_challenge задан правильно.
При обновлении токена доступа может оказаться, что срок его действия истек или он был аннулирован. Повторно выполните аутентификацию пользователя и запросите согласие пользователя на получение новых токенов. Если вы продолжаете видеть эту ошибку, убедитесь, что ваше приложение настроено правильно и что вы используете правильные токены и параметры в своем запросе. В противном случае аккаунт пользователя мог быть удален или отключен.
redirect_uri_mismatch
Значение redirect_uri, переданное в запросе на авторизацию, не соответствует авторизованному URI перенаправления для идентификатора клиента OAuth. Проверьте авторизованные URI перенаправления на странице клиентов в консоли Google Cloud.
Переданный параметр redirect_uri может быть недопустимым для этого типа клиента.
Параметр redirect_uri может относиться к устаревшему и больше не поддерживаемому процессу OAuth out-of-band (OOB). Чтобы обновить интеграцию, следуйте инструкциям в руководстве по переносу.
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: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiVkM5MXk5WllkZlNXYUR2OEphSTZneDVpZk93MnJuM1lkcWtBQjUxVXU2RSIsInkiOiJpa1BqT3RlYTRrN2ZXUFZyUll3YUE0V3c2aVZZM3BPT0lDb3RId3dHVjNvIn19.eyJqdGkiOiJvMjlDTjhMSVkwbF9OOGl5NS1pbG9uMWd1YWQ5TkZRSEZPZFhUenJCTmNrIiwiaHRtIjoiUE9TVCIsImh0dSI6Imh0dHBzOi8vb2F1dGgyLmdvb2dsZWFwaXMuY29tL3Rva2VuIiwiaWF0IjoxNzg0ODIyMDI1fQ.OSdQCmqTng_uZmGK5UXf8hcEMtoOu7ucmYtl5mx4901RXnj6fJRJQmIeTqfhprRBTG_RSJv2fPcWDqvQbDW7YA 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 кода авторизации, закодированным по стандарту Base64 для URL:"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/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
"refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}Шаг 6. Проверьте, какие области действия разрешили пользователи
Если вы запрашиваете несколько разрешений (областей действия), пользователи могут предоставить вашему приложению доступ не ко всем из них. Приложение должно проверять, какие области действия были разрешены, и корректно обрабатывать ситуации, когда в некоторых разрешениях отказано. Обычно для этого отключаются функции, которые зависят от запрещенных областей действия.
Однако из этого правила бывают исключения. Приложения Google Workspace Enterprise с делегированием полномочий в домене или приложения, помеченные как надежные, обходят окно запроса доступа с детализированными разрешениями. Для таких приложений пользователи не увидят окно запроса доступа с детализированными разрешениями. Вместо этого ваше приложение получит либо все запрошенные области действия, либо ни одной.
Подробную информацию можно найти в статье Как работать с детализированными разрешениями.
Чтобы проверить, предоставил ли пользователь вашему приложению доступ к определенной области действия, изучите поле scope в ответе токена доступа. Области действия, предоставленные токеном доступа access_token, в виде списка строк с учетом регистра, разделенных пробелами.
Например, в следующем примере ответа на запрос токена доступа указано, что пользователь предоставил вашему приложению доступ к разрешениям на чтение активности на Диске и мероприятий в Календаре:
{ "access_token": "1/fFAGRNJru1FTz70BzhT3Zg", "expires_in": 3920, "token_type": "Bearer", "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly", "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI" }
Вызов API Google
Получив токен доступа, приложение может использовать его для вызова Google API от имени определенного аккаунта пользователя, если предоставлены необходимые для API области доступа. Для этого включите токен доступа в запрос к API, добавив параметр запроса access_token или значение Bearer HTTP-заголовка Authorization. По возможности используйте HTTP-заголовок, поскольку строки запроса обычно видны в журналах сервера. В большинстве случаев для настройки вызовов API Google можно использовать клиентскую библиотеку (например, при вызове Drive Files API).
Вы можете попробовать все API Google и посмотреть их области действия в OAuth 2.0 Playground.
Примеры HTTP GET
Вызов конечной точки drive.files (Drive Files API) с использованием HTTP-заголовка Authorization: Bearer может выглядеть следующим образом: Обратите внимание, что вам нужно указать собственный токен доступа:
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 |
Токен обновления, возвращенный в результате обмена кодами авторизации. |
Использовать 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 https://www.googleapis.com/auth/calendar.readonly",
"token_type": "Bearer"
}Обратите внимание, что количество токенов обновления ограничено. Ограничения действуют для каждой комбинации клиента и пользователя, а также для каждого пользователя во всех клиентах. Токены обновления следует сохранять в долговременном хранилище и использовать, пока они действительны. Если ваше приложение запрашивает слишком много токенов обновления, оно может столкнуться с этими ограничениями, и в этом случае старые токены обновления перестанут работать.
Отзыв токена
В некоторых случаях пользователь может захотеть отозвать доступ, предоставленный приложению. Пользователь может отозвать доступ в настройках аккаунта. Подробную информацию вы найдете в разделе Как закрыть доступ к аккаунту для сайта или приложения статьи "Сторонние приложения и сайты с доступом к аккаунту".
Приложение также может программно отозвать предоставленный ему доступ. Программный отзыв важен в тех случаях, когда пользователь отменяет подписку, удаляет приложение или когда ресурсы API, необходимые для приложения, значительно изменились. Другими словами, в процессе удаления может выполняться запрос к API, чтобы убедиться, что разрешения, ранее предоставленные приложению, удалены.
Чтобы отозвать токен программным способом, приложение отправляет запрос на адрес https://oauth2.googleapis.com/revoke и включает токен в качестве параметра:
curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
https://oauth2.googleapis.com/revoke?token={token}Это может быть токен доступа или токен обновления. Если токен является токеном доступа и у него есть соответствующий токен обновления, токен обновления также будет отозван.
Если отзыв успешно обработан, то код статуса HTTP ответа – 200. В случае ошибки возвращается код статуса HTTP 400 и код ошибки.
Методы перенаправления в приложение
Специальная схема URI
Специальные схемы URI – это разновидность ссылок на контент, в которой для открытия приложения используется специальная схема.
Альтернатива пользовательским схемам URI в приложениях Chrome
Используйте Chrome Identity API, который передает ответ OAuth 2.0 непосредственно в приложение, устраняя необходимость в URI перенаправления.
IP-адрес обратной связи (macOS, Linux, Windows)
Чтобы получить код авторизации с помощью этого URL, ваше приложение должно прослушивать локальный веб-сервер. Это возможно на многих, но не на всех платформах. Однако если ваша платформа поддерживает этот механизм, мы рекомендуем использовать именно его.
Когда приложение получит ответ на запрос авторизации, для максимального удобства использования оно должно показать пользователю HTML-страницу с инструкцией закрыть браузер и вернуться в приложение.
| Рекомендуемое использование | Компьютерные приложения для macOS, Linux и Windows |
| Значения формы | В качестве типа приложения выберите Компьютерное приложение. |
Копирование и вставка вручную (поддержка прекращена)
Защитите свои приложения
Как подтвердить право собственности на приложение для Chrome
Вы можете подтвердить право собственности на приложение, чтобы снизить риск его имитации.
Чтобы завершить проверку, используйте аккаунт разработчика в интернет-магазине Chrome. Чтобы успешно пройти проверку, необходимо выполнить следующие требования:
- В Личном кабинете разработчика продуктов для интернет-магазина Chrome должен быть зарегистрирован продукт с тем же идентификатором товара, что и у клиента OAuth расширения Chrome, для которого вы проходите проверку.
- Вы должны быть издателем продукта в интернет-магазине Chrome. Подробнее об управлении доступом в Личном кабинете разработчика продуктов для интернет-магазина Chrome…
В разделе Verify App Ownership (Подтверждение права собственности на приложение) клиента расширения Chrome нажмите кнопку Verify Ownership (Подтвердить право собственности), чтобы завершить процесс проверки.
Примечание. После предоставления доступа к аккаунту подождите несколько минут, прежде чем завершить процедуру подтверждения.
Если проверка пройдет успешно, вы увидите уведомление об этом. В противном случае появится сообщение об ошибке.
Чтобы устранить проблему, попробуйте сделать следующее:
- Убедитесь, что в Личном кабинете разработчика продуктов для интернет-магазина Chrome зарегистрирован продукт с тем же идентификатором, что и у клиента OAuth расширения Chrome, для которого вы проходите проверку.
- Убедитесь, что вы являетесь издателем приложения, то есть его индивидуальным издателем или участником группы издателей. Подробнее об управлении доступом в Личном кабинете разработчика продуктов для интернет-магазина Chrome…
- Если вы только что обновили список издателей группы, убедитесь, что он синхронизирован с Личным кабинетом разработчика продуктов для интернет-магазина Chrome. Подробнее о синхронизации списка участников издателя…
Доступ на основе времени
Временный доступ позволяет пользователю предоставить вашему приложению доступ к своим данным на ограниченный период времени для выполнения действия. В некоторых продуктах Google при предоставлении доступа можно выбрать вариант с ограничением по времени. Пример – Data Portability API, который позволяет выполнить однократный перенос данных.
Если пользователь предоставляет вашему приложению доступ на определенное время, срок действия токена обновления истечет по окончании этого периода. Обратите внимание, что в некоторых случаях токены обновления могут быть аннулированы раньше. Подробнее об этом рассказывается в этой статье. Поле refresh_token_expires_in, возвращаемое в ответе на обмен кодами авторизации, представляет собой время, оставшееся до истечения срока действия токена обновления в таких случаях.
Дополнительные ресурсы
Многие из приведенных здесь рекомендаций основаны на документе IETF OAuth 2.0 for Native Apps.
Как реализовать защиту связанных аккаунтов
Чтобы дополнительно защитить аккаунты пользователей, включите защиту связанных аккаунтов с помощью сервиса 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
Подробную информацию о том, как реализовать защиту связанных аккаунтов, и полный список доступных событий можно найти на странице Защита аккаунтов пользователей с помощью защиты связанных аккаунтов.