Для аутентификации и авторизации в 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. Проверьте области доступа, предоставленные пользователем.
Сравните области действия, включенные в ответ токена доступа, с областями действия, необходимыми для доступа к функциям вашего приложения, которые зависят от доступа к связанному API Google. Отключите все функции приложения, которые не могут работать без доступа к соответствующему API.
Область действия, включенная в ваш запрос, может не совпадать с областью действия, включенной в ваш ответ, даже если пользователь предоставил все запрошенные области действия. Области действия, необходимые для доступа, указаны в документации по каждому API Google. API может сопоставлять несколько строковых значений области действия с одной областью доступа, возвращая одну и ту же строку области действия для всех значений, разрешенных в запросе. Пример. Google People API может вернуть область действия https://www.googleapis.com/auth/contacts, когда приложение запрашивает у пользователя авторизацию области действия https://www.google.com/m8/feeds/. Для метода people.updateContact Google People API требуется предоставленная область действия https://www.googleapis.com/auth/contacts.
4. Отправьте токен доступа в API.
Получив токен доступа, приложение отправляет его в API Google в заголовке запроса авторизации HTTP. Токены можно отправлять в качестве параметров строки запроса URI, но мы не рекомендуем этого делать, поскольку параметры URI могут оказаться в файлах журналов, которые не полностью защищены. Кроме того, в REST не рекомендуется создавать ненужные названия параметров URI.
Токены доступа действительны только для набора операций и ресурсов, описанных в scope запроса токена. Например, если токен доступа выдан для Google Календаря API, он не предоставляет доступ к Google Контактам API. Однако вы можете отправлять этот токен доступа в Google Calendar API несколько раз для выполнения аналогичных операций.
5. При необходимости обновите токен доступа.
Срок действия токенов доступа ограничен, Если вашему приложению требуется доступ к API Google в течение более длительного времени, чем срок действия одного токена доступа, оно может получить токен обновления. Токен обновления позволяет приложению получать новые токены доступа.
Сценарии
В этих сценариях описывается, как использовать OAuth 2.0 для запроса кодов авторизации и получения токенов доступа и токенов обновления для разных типов приложений.
Приложения веб-сервера
Конечная точка Google OAuth 2.0 поддерживает веб-серверные приложения, в которых используются такие языки и фреймворки, как PHP, Java, Go, Python, Ruby и ASP.NET.
Процесс авторизации начинается, когда приложение перенаправляет браузер на URL Google. Этот URL содержит параметры запроса, которые указывают на тип запрашиваемого доступа. Google выполняет аутентификацию пользователя, выбор сеанса и получение согласия пользователя. В результате будет получен код авторизации, который приложение может обменять на токен доступа и токен обновления.
Приложение должно сохранить токен обновления для дальнейшего использования и использовать токен доступа для доступа к Google API. Когда срок действия токена доступа истекает, приложение использует токен обновления, чтобы получить новый.
Подробнее об использовании OAuth 2.0 для веб-серверных приложений…
Установленные приложения
Конечная точка Google OAuth 2.0 поддерживает приложения, установленные на таких устройствах, как компьютеры, мобильные устройства и планшеты. При создании идентификатора клиента в Google API Console укажите, что это установленное приложение, а затем выберите тип приложения: Android, расширение Chrome, iOS или приложение для ПК.
В результате вы получите идентификатор клиента и, в некоторых случаях, секретный код клиента, которые нужно будет встроить в исходный код приложения. (В этом контексте секретный код клиента, очевидно, не рассматривается как секрет.)
Процесс авторизации начинается, когда приложение перенаправляет браузер на URL Google. Этот URL содержит параметры запроса, которые указывают на тип запрашиваемого доступа. Google выполняет аутентификацию пользователя, выбор сеанса и получение согласия пользователя. В результате будет получен код авторизации, который приложение может обменять на токен доступа.
Приложение должно проверить токен доступа, прежде чем включать его в запрос к API Google. Когда срок действия токена истекает, приложение повторяет процесс.
При необходимости бэкенд-сервер может обменять код авторизации на токен обновления и сохранить его в безопасном месте. Когда срок действия токена доступа истекает, бэкенд-сервер использует токен обновления, чтобы получить новый токен доступа для приложения.
Подробную информацию можно найти в статьях Авторизация доступа к пользовательским данным Google (для Android), Доступ к API Google в приложении для iOS и OAuth 2.0 для компьютерных приложений.
Клиентские приложения (JavaScript)
Конечная точка Google OAuth 2.0 поддерживает приложения JavaScript, которые выполняются в браузере.
Процесс авторизации начинается, когда приложение перенаправляет браузер на URL Google. Этот URL содержит параметры запроса, которые указывают на тип запрашиваемого доступа. 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. Когда срок действия токена истекает, приложение повторяет процесс.
Подробную информацию можно найти в документации по сервисным аккаунтам.
Размер токена
Размер токенов может быть разным, но не должен превышать следующие ограничения:
Токены доступа, возвращаемые Security Token Service API Google Cloud, структурированы аналогично токенам доступа OAuth 2.0 API Google, но имеют другие ограничения на размер токена. Подробную информацию можно найти в документации по API.
Google оставляет за собой право изменять размер токена в этих пределах, и ваше приложение должно поддерживать токены переменного размера.
Срок действия токена обновления
При написании кода необходимо учитывать, что токен обновления может перестать работать. Токен обновления может перестать работать по одной из следующих причин:
Для проекта Google Cloud Platform с окном запроса доступа OAuth, настроенным для внешних пользователей, и статусом публикации "Тестирование" выпускается токен обновления, срок действия которого истекает через семь дней, если только запрошенные области действия OAuth не являются подмножеством имени, адреса электронной почты и профиля пользователя (через области действия userinfo.email, userinfo.profile, openid или их эквиваленты OpenID Connect).
В настоящее время для каждого аккаунта Google и идентификатора клиента OAuth 2.0 действует ограничение в 100 токенов обновления. При достижении этого лимита каждый новый токен обновления будет без предупреждения заменять наиболее старый из них. Это ограничение не распространяется на сервисные аккаунты.
Также существует ограничение на общее количество токенов обновления, которые могут быть у аккаунта пользователя или сервисного аккаунта для всех клиентов. Обычные пользователи вряд ли превысят этот лимит, но это может произойти с аккаунтом разработчика, который используется для тестирования.
Если вам нужно авторизовать несколько программ, компьютеров или устройств, вы можете ограничить количество клиентов, авторизуемых для каждого аккаунта 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. Со временем в библиотеках появится больше функций.
- Библиотека Google Auth для Java
- Клиентская библиотека API Google для Python
- Клиентская библиотека API Google для Dart
- Клиентская библиотека API Google для Go
- Клиентская библиотека API Google для .NET
- Клиентская библиотека API Google для Ruby
- Клиентская библиотека API Google для PHP
- Клиентская библиотека API Google для JavaScript
- GTMAppAuth – клиентская библиотека OAuth для Mac и iOS
