Использование OAuth 2.0 для доступа к API Google

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

Для начала получите учетные данные клиента OAuth 2.0 в Google API Console. Затем клиентское приложение запрашивает токен доступа у сервера авторизации Google, извлекает токен из ответа и отправляет его в API Google, к которому вы хотите получить доступ. Чтобы посмотреть интерактивную демонстрацию использования OAuth 2.0 с Google (включая возможность использовать собственные учетные данные клиента), воспользуйтесь OAuth 2.0 Playground.

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

Основные действия

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

1. Получите учетные данные OAuth 2.0 в Google API Console.

Перейдите в Google API Console и получите учетные данные OAuth 2.0, например идентификатор и секретный код клиента, которые известны как Google, так и вашему приложению. Набор значений зависит от типа создаваемого приложения. Например, для приложения JavaScript секретный ключ не требуется, а для приложения веб-сервера – требуется.

Вам нужно создать клиент OAuth, подходящий для платформы, на которой будет работать ваше приложение, например:

2. Получите токен доступа от сервера авторизации Google.

Чтобы получить доступ к личным данным с помощью API Google, приложение должно получить токен доступа, который предоставляет доступ к этому API. Один токен доступа может предоставлять разные уровни доступа к нескольким API. Переменный параметр scope управляет набором ресурсов и операций, которые разрешены токеном доступа. При запросе токена доступа приложение отправляет одно или несколько значений в параметре scope.

Это можно сделать несколькими способами в зависимости от типа приложения. Например, JavaScript-приложение может запросить токен доступа, перенаправив пользователя на страницу Google в браузере, а приложение, установленное на устройстве без браузера, – с помощью запросов к веб-сервису. Подробную информацию о том, как отправить запрос, можно найти в разделе Scenarios и подробных руководствах по внедрению для каждого типа приложений.

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

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

Рекомендуется запрашивать области постепенно, по мере необходимости, а не все сразу. Например, если приложение поддерживает сохранение мероприятий в календаре, оно не должно запрашивать доступ к Google Календарю, пока пользователь не нажмет кнопку "Добавить в календарь". Подробнее о пошаговой авторизации…

3. Проверьте области доступа, предоставленные пользователем.

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

Область, включенная в ваш запрос, может не совпадать с областью, включенной в ваш ответ, даже если пользователь предоставил все запрошенные области. Области действия, необходимые для доступа, указаны в документации по каждому API Google. API может сопоставлять несколько строковых значений области действия с одной областью доступа, возвращая одну и ту же строку области действия для всех значений, разрешенных в запросе. Пример. Google People API может вернуть область действия https://www.googleapis.com/auth/contacts, когда приложение запрашивает у пользователя авторизацию области действия https://www.google.com/m8/feeds/. Метод Google People API people.updateContact требует предоставления области действия https://www.googleapis.com/auth/contacts.

4. Отправьте токен доступа в API.

Получив токен доступа, приложение отправляет его в API Google в заголовке запроса авторизации HTTP. Токены можно отправлять в виде параметров строки запроса URI, но мы не рекомендуем это делать, поскольку параметры URI могут оказаться в файлах журналов, которые не полностью защищены. Кроме того, в REST не рекомендуется создавать лишние названия параметров URI.

Токены доступа действительны только для набора операций и ресурсов, описанных в параметре scope запроса токена. Например, если токен доступа выдан для Google Calendar API, он не предоставляет доступ к Google Contacts API. Однако вы можете отправлять этот токен доступа в Google Календарь API несколько раз для выполнения похожих операций.

5. При необходимости обновите токен доступа.

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

Сценарии

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

Приложения веб-сервера

Конечная точка Google OAuth 2.0 поддерживает веб-серверные приложения, в которых используются такие языки и фреймворки, как PHP, Java, Go, Python, Ruby и ASP.NET.

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

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

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

Подробнее об использовании OAuth 2.0 для веб-серверных приложений…

Установленные приложения

Конечная точка Google OAuth 2.0 поддерживает приложения, установленные на таких устройствах, как компьютеры, мобильные устройства и планшеты. При создании идентификатора клиента в Google API Console укажите, что это установленное приложение, а затем выберите тип приложения: Android, расширение Chrome, iOS или компьютерное приложение.

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

Процесс авторизации начинается, когда приложение перенаправляет браузер на URL Google. Этот URL содержит параметры запроса, которые указывают на тип запрашиваемого доступа. Google обрабатывает аутентификацию пользователя, выбор сеанса и согласие пользователя. В результате будет получен код авторизации, который приложение может обменять на токен доступа. Приложение должно проверить токен доступа, прежде чем включать его в запрос к API Google. Когда срок действия токена истекает, приложение повторяет процесс.

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

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

Подробные сведения приведены в статьях Авторизация доступа к пользовательским данным Google для Android, Доступ к API Google в приложении для iOS и OAuth 2.0 для компьютерных приложений.

Клиентские приложения (JavaScript)

Конечная точка Google OAuth 2.0 поддерживает приложения JavaScript, которые выполняются в браузере.

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

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

Ваше JS-приложение отправляет запрос токена на сервер авторизации Google, получает токен, проверяет его и использует для вызова конечной точки API Google.

Подробнее об использовании OAuth 2.0 для клиентских приложений…

Приложения на устройствах с ограниченными возможностями ввода

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

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

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

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

Пользователь входит в аккаунт на другом устройстве с браузером.

Подробнее о том, как использовать OAuth 2.0 для устройств…

Сервисные аккаунты

API Google, такие как Prediction API и Google Cloud Storage, могут действовать от имени вашего приложения, не получая доступ к информации о пользователях. В таких случаях приложение должно подтвердить свою личность в API, но согласие пользователя не требуется. Аналогично в корпоративных сценариях ваше приложение может запрашивать делегированный доступ к некоторым ресурсам.

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

Учетные данные сервисного аккаунта, которые вы получаете в Google API Console, включают уникальный сгенерированный адрес электронной почты, идентификатор клиента и по крайней мере одну пару открытого и закрытого ключей. Используя идентификатор клиента и один закрытый ключ, вы создаете подписанный JWT и формируете запрос токена доступа в соответствующем формате. Затем приложение отправляет запрос токена на сервер авторизации Google OAuth 2.0, который возвращает токен доступа. Приложение использует токен для доступа к API Google. Когда срок действия токена истекает, приложение повторяет процесс.

Серверное приложение использует JWT для запроса токена у сервера авторизации Google, а затем использует токен для вызова конечной точки API Google. Конечный пользователь не участвует в этом процессе.

Подробные сведения приведены в документации по сервисным аккаунтам.

Размер токена

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

  • code Коды авторизации
    256 байт
  • contextual_token Токены доступа
    2048 байт
  • restore_page Токены обновления
    512 байт

Токены доступа, возвращаемые Security Token Service API Google Cloud, структурированы аналогично токенам доступа OAuth 2.0 API Google, но имеют другие ограничения на размер. Подробную информацию вы найдете в документации по API.

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

Срок действия токена обновления

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

Для проекта Google Cloud Platform с окном запроса доступа OAuth, настроенным для внешнего типа пользователей и статусом публикации "Тестирование", выпускается токен обновления, срок действия которого истекает через 7 дней, если только единственными запрашиваемыми областями действия OAuth не являются подмножество имени, адреса электронной почты и профиля пользователя (через области действия userinfo.email, userinfo.profile, openid или их эквиваленты OpenID Connect).

В настоящее время действует ограничение: не более 100 токенов обновления на аккаунт Google для каждого идентификатора клиента OAuth 2.0. При достижении этого лимита каждый новый токен обновления будет без предупреждения заменять наиболее старый из них. Это ограничение не распространяется на сервисные аккаунты.

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

Если вам нужно авторизовать несколько программ, компьютеров или устройств, вы можете ограничить число клиентов, авторизуемых для каждого аккаунта Google, до 15–20. Если вы администратор Google Workspace, то можете создать дополнительных пользователей с правами администратора и использовать их для авторизации некоторых клиентов.

Работа с правилами управления сеансами для организаций Google Cloud Platform (GCP)

Администраторы организаций GCP могут требовать от пользователей частого прохождения повторной аутентификации при доступе к ресурсам GCP, используя функцию управления сеансами Google Cloud. Это правило влияет на доступ к консоли Google Cloud, Google Cloud SDK (также известному как gcloud CLI) и любым сторонним приложениям OAuth, которым требуется область действия Cloud Platform. Если у пользователя есть правило управления сеансами, то по истечении срока действия сеанса вызовы API будут завершаться ошибкой, как и в случае отзыва токена обновления. Вызов завершится ошибкой типа invalid_grant. Поле error_subtype можно использовать, чтобы различать отозванный токен и сбой из-за правила управления сеансами (например, "error_subtype": "invalid_rapt"). Поскольку длительность сеансов может быть очень ограниченной (от 1 до 24 часов), этот сценарий должен корректно обрабатываться путем перезапуска сеанса аутентификации.

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

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

Клиентские библиотеки

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