Использование 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, в то время как приложение, установленное на устройстве без браузера, использует запросы веб-службы.

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

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

Обычно рекомендуется запрашивать области постепенно, в тот момент, когда требуется доступ, а не заранее. Например, приложение, которое хочет поддерживать сохранение события в календаре, не должно запрашивать доступ к Календарю Google, пока пользователь не нажмет кнопку «Добавить в календарь»; см. Дополнительная авторизация .

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

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

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

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

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

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

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

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

Сценарии

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

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

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

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

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

Подробности см. в разделе «Использование OAuth 2.0 для приложений веб-сервера» .

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

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

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

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

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

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

Подробности см. в разделе «Использование OAuth 2.0 для установленных приложений» .

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

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

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

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

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

Подробности см. в разделе «Использование 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. Конечный пользователь не участвует.

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

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

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

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

Токены доступа, возвращаемые API службы токенов безопасности Google Cloud, структурированы аналогично токенам доступа Google API OAuth 2.0, но имеют другие ограничения на размер токена. Подробности смотрите в документации 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 Console, Google Cloud SDK (также известному как gcloud CLI) и любому стороннему приложению OAuth, которому требуется область действия Cloud Platform. Если у пользователя действует политика управления сеансом, то по истечении продолжительности сеанса ваши вызовы API выдадут ошибку, аналогичную тому, что произошло бы, если бы токен обновления был отозван — вызов завершится с ошибкой типа invalid_grant ; поле error_subtype можно использовать, чтобы отличить отозванный токен от сбоя из-за политики управления сеансом (например, "error_subtype": "invalid_rapt" ). Поскольку продолжительность сеанса может быть очень ограничена (от 1 часа до 24 часов), этот сценарий необходимо корректно обработать, перезапустив сеанс аутентификации.

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

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

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

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