OAuth 2.0 для компьютерных приложений

В этом документе объясняется, как компьютерные приложения (например, работающие в 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 для вашего проекта:

  1. Откройте библиотеку API в Google API Console.
  2. Выберите существующий проект или создайте новый.
  3. В библиотеке API перечислены все доступные API, сгруппированные по семейству продуктов и популярности. Если нужного API нет в списке, воспользуйтесь поиском или нажмите Показать все в семействе продуктов, к которому он относится.
  4. Выберите нужный API и нажмите кнопку Включить.
  5. Если появится запрос, включите оплату.
  6. При необходимости прочтите и примите Условия использования API.

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

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

  1. Перейдите на страницу Клиенты.
  2. Нажмите Создать клиент.
  3. Выберите тип приложения Компьютерное приложение.
  4. В поле Название введите название клиента OAuth. Это название будет показываться на странице клиентов вашего проекта.
  5. Нажмите Создать.

Идентификатор клиента и секретный код клиента будут созданы и показаны в консоли Google Cloud. Компьютерные приложения являются общедоступными клиентами и не могут хранить секреты в тайне. При запросе кодов авторизации всегда используйте PKCE (Proof Key for Code Exchange).

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

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

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

Полный список областей действия, которые можно использовать для доступа к API Google, приведен в документе Области действия OAuth 2.0 для 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 (без заполнителей).
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain Значение code_challenge совпадает со значением code_verifier, сгенерированным выше.
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, вы получите ошибку redirect_uri_mismatch.

В таблице ниже приведены значения параметра redirect_uri для каждого метода.

Значения атрибута redirect_uri
Специальная схема URI com.example.app:redirect_uri_path

или

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app – это обратная запись DNS домена, который находится под вашим контролем. Специальная схема должна содержать точку.
  • com.googleusercontent.apps.123 – идентификатор клиента в формате обратного DNS.
  • redirect_uri_path – необязательный компонент пути, например /oauth2redirect. Обратите внимание, что путь должен начинаться с одной косой черты, в отличие от обычных URL с протоколом HTTP.
IP-адрес loopback-интерфейса http://127.0.0.1:port или http://[::1]:port

Запросите у платформы соответствующий IP-адрес обратной связи и запустите прослушиватель HTTP на случайном доступном порте. Замените port на номер порта, который прослушивает ваше приложение.

Обратите внимание, что поддержка перенаправления на IP-адрес обратной связи в мобильных приложениях ПРЕКРАЩЕНА.
response_type Обязательно

Определяет, возвращает ли конечная точка Google OAuth 2.0 код авторизации.

Для установленных приложений задайте значение параметра code.
scope Обязательно

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

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

Указывает закодированный параметр code_verifier, который будет использоваться в качестве запроса на стороне сервера при обмене кодами авторизации. Подробнее о том, как создать код-вызов…
code_challenge_method Рекомендуется

Указывает, какой метод использовался для кодирования code_verifier, который будет использоваться при обмене кодами авторизации. Этот параметр необходимо использовать вместе с параметром code_challenge. Если в запросе, содержащем code_challenge, нет значения code_challenge_method, по умолчанию используется plain. Допустимые значения: S256 или plain.
state Рекомендуется

Любая строка, которую ваше приложение использует для сохранения состояния между запросом авторизации и ответом сервера авторизации. Сервер возвращает точное значение, которое вы отправляете в виде пары name=value в идентификаторе фрагмента URL (#) в redirect_uri после того, как пользователь разрешает или запрещает доступ вашему приложению.

Этот параметр можно использовать для разных целей, например для перенаправления пользователя к нужному ресурсу в приложении, отправки одноразовых кодов и защиты от подделки межсайтовых запросов. Поскольку ваш redirect_uri можно угадать, использование значения state может повысить вашу уверенность в том, что входящее подключение является результатом запроса на аутентификацию. Если вы создадите случайную строку или закодируете хеш файла cookie или другое значение, которое фиксирует состояние клиента, вы сможете проверить ответ, чтобы дополнительно убедиться, что запрос и ответ поступили из одного браузера. Это обеспечит защиту от таких атак, как межсайтовая подделка запроса. Пример создания и подтверждения токена state можно найти в документации по OpenID Connect.
login_hint Необязательно

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

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

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

Ошибки

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

admin_policy_enforced

Аккаунт Google не может авторизовать одну или несколько запрошенных областей действия из-за правил, установленных администратором Google Workspace. В справочной статье Справочного центра для администраторов Google Workspace Как управлять доступом сторонних и внутренних приложений к данным Google Workspace рассказывается, как администратор может ограничить доступ ко всем областям действия или только к конфиденциальным и с ограниченным доступом, пока доступ не будет явно предоставлен вашему идентификатору клиента OAuth.

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 Идентификатор клиента, полученный на странице Clients (Клиенты) в 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 в командной строке.

  1. Создайте пару ключей EC P-256: 
    openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
openssl ec -in dpop_private.pem -pubout -out dpop_public.pem
  2. Создайте заголовок DPoP:

    Заголовок должен содержать утверждения typ, alg и jwk (открытый ключ). Значения x и y – это координаты открытого ключа EC, закодированные в Base64Url. Закодируйте этот JSON-объект с помощью Base64Url:

    {
  "typ":"dpop+jwt",
  "alg":"ES256",
  "jwk": {
    "kty":"EC",
    "x":"YOUR_PUBLIC_KEY_X",
    "y":"YOUR_PUBLIC_KEY_Y",
    "crv":"P-256"
  }
}
  3. Создайте полезную нагрузку 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".
  4. Подпишите доказательство:

    Объедините закодированный заголовок и полезную нагрузку, разделив их точкой (.), а затем подпишите результат закрытым ключом с помощью ES256. Обратите внимание, что JWS требует, чтобы подпись была в необработанном объединенном формате R | S (64 байта для P-256). Если вы используете OpenSSL напрямую, вам необходимо преобразовать подпись, закодированную по умолчанию в формате ASN.1 DER, в этот необработанный формат.

Успешный обмен подтверждается ответом 200 OK, содержащим токены. Если при обмене используется действительное подтверждение DPoP, токен обновления, возвращаемый Google, будет привязан к вашему ключу, а токены доступа – нет. Токены доступа сохранят 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": "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. (Параметр client_secret неприменим к запросам от клиентов, зарегистрированных как приложения Android, iOS или Chrome.)

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. Чтобы успешно пройти проверку, необходимо выполнить следующие требования:

В разделе Verify App Ownership (Подтверждение права собственности на приложение) клиента расширения Chrome нажмите кнопку Verify Ownership (Подтвердить право собственности), чтобы завершить процесс подтверждения.

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

Если проверка пройдет успешно, вы увидите уведомление об этом. В противном случае появится сообщение об ошибке.

Чтобы устранить проблему, попробуйте сделать следующее:

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

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

Подробную информацию о том, как реализовать защиту связанных аккаунтов, и полный список доступных событий вы найдете на странице Защита аккаунтов пользователей с помощью защиты связанных аккаунтов .