API Google используют протокол OAuth 2.0 для аутентификации и авторизации. Google поддерживает распространённые сценарии OAuth 2.0, например, для веб-серверов, клиентских приложений, устанавливаемых приложений и приложений с ограниченным вводом.
Для начала получите учетные данные клиента OAuth 2.0 от Затем ваше клиентское приложение запрашивает токен доступа у сервера авторизации 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 от .
Посетите для получения учётных данных OAuth 2.0, таких как идентификатор клиента и секретный ключ клиента, которые известны как Google, так и вашему приложению. Набор значений зависит от типа создаваемого приложения. Например, для приложения JavaScript секретный ключ не требуется, а для приложения веб-сервера — требуется.
Вам необходимо создать OAuth-клиент, соответствующий платформе, на которой будет работать ваше приложение, например:
- Для серверных веб-приложений или веб-приложений JavaScript используйте тип клиента «web». Не используйте этот тип клиента для других приложений, например, для нативных или мобильных.
- Для приложений Android используйте тип клиента «Android».
Для приложений iOS и macOS используйте тип клиента «iOS».
- Для приложений универсальной платформы Windows используйте тип клиента «Универсальная платформа Windows».
- тв Для устройств с ограниченным вводом , таких как телевизоры или встроенные устройства, используйте тип клиента «Телевизоры и устройства с ограниченным вводом».
- хост Для взаимодействия сервер-сервер используйте учетные записи служб.
2. Получите токен доступа от сервера авторизации Google.
Прежде чем ваше приложение сможет получить доступ к приватным данным через API Google, оно должно получить токен доступа, предоставляющий доступ к этому API. Один токен доступа может предоставлять различные уровни доступа к нескольким API. Переменный параметр, называемый scope управляет набором ресурсов и операций, которые разрешает токен доступа. При запросе токена доступа ваше приложение отправляет одно или несколько значений в параметре scope .
Существует несколько способов сделать этот запрос, и они различаются в зависимости от типа создаваемого приложения. Например, приложение JavaScript может запросить токен доступа, используя перенаправление браузера на Google, в то время как приложение, установленное на устройстве без браузера, использует запросы к веб-сервисам.
Для некоторых запросов требуется этап аутентификации, на котором пользователь входит в свою учётную запись Google. После входа пользователю предлагается предоставить одно или несколько разрешений, запрашиваемых вашим приложением. Этот процесс называется согласием пользователя .
Если пользователь предоставляет хотя бы одно разрешение, сервер авторизации Google отправляет вашему приложению токен доступа (или код авторизации, который ваше приложение может использовать для получения токена доступа) и список областей доступа, предоставляемых этим токеном. Если пользователь не предоставляет разрешение, сервер возвращает ошибку.
Как правило, рекомендуется запрашивать области действия поэтапно, в момент необходимости доступа, а не заранее. Например, приложение, которое хочет поддерживать сохранение события в календаре, не должно запрашивать доступ к Google Календарю, пока пользователь не нажмёт кнопку «Добавить в календарь»; см. раздел «Поэтапная авторизация» .
3. Изучите области доступа, предоставленные пользователем.
Сравните области действия, указанные в ответе на запрос токена доступа, с областями действия, необходимыми для доступа к функциям и функционалу вашего приложения, зависящим от доступа к соответствующему API Google. Отключите все функции вашего приложения, которые не могут работать без доступа к соответствующему API.
Область действия, указанная в запросе, может не совпадать с областью действия, указанной в ответе, даже если пользователь предоставил все запрошенные области действия. Сведения о областях действия, необходимых для доступа, см. в документации по каждому API Google. API может сопоставлять несколько значений строк области действия с одной областью действия, возвращая одну и ту же строку области действия для всех разрешенных в запросе значений. Пример: API Google People может возвращать область действия 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. По истечении срока действия токена доступа приложение использует его для получения нового токена обновления.
Подробную информацию см. в разделе Использование OAuth 2.0 для приложений веб-сервера .
Установленные приложения
Конечная точка Google OAuth 2.0 поддерживает приложения, установленные на таких устройствах, как компьютеры, мобильные устройства и планшеты. При создании идентификатора клиента через , укажите, что это установленное приложение, затем выберите Android, приложение Chrome, iOS, универсальную платформу Windows (UWP) или настольное приложение в качестве типа приложения.
Результатом этого процесса является идентификатор клиента и, в некоторых случаях, секретный ключ клиента, который вы встраиваете в исходный код своего приложения. (В этом контексте секретный ключ клиента, очевидно, не рассматривается как секрет.)
Последовательность авторизации начинается с того, что ваше приложение перенаправляет браузер на URL-адрес Google; URL-адрес включает параметры запроса, указывающие тип запрашиваемого доступа. Google отвечает за аутентификацию пользователя, выбор сеанса и получение согласия пользователя. Результатом является код авторизации, который приложение может обменять на токен доступа и токен обновления.
Приложение должно сохранить токен обновления для дальнейшего использования и использовать его для доступа к API Google. По истечении срока действия токена доступа приложение использует его для получения нового токена обновления.
Подробности см. в разделе Использование OAuth 2.0 для установленных приложений .
Клиентские приложения (JavaScript)
Конечная точка Google OAuth 2.0 поддерживает приложения JavaScript, работающие в браузере.
Последовательность авторизации начинается, когда ваше приложение перенаправляет браузер на URL-адрес Google; URL-адрес включает параметры запроса, указывающие тип запрашиваемого доступа. Google отвечает за аутентификацию пользователя, выбор сеанса и получение его согласия.
Результатом является токен доступа, который клиент должен проверить перед включением в запрос к API Google. По истечении срока действия токена приложение повторяет процесс.
Подробности см. в разделе Использование OAuth 2.0 для клиентских приложений .
Приложения на устройствах с ограниченными возможностями ввода
Конечная точка Google OAuth 2.0 поддерживает приложения, работающие на устройствах с ограниченными возможностями ввода, таких как игровые консоли, видеокамеры и принтеры.
Последовательность авторизации начинается с того, что приложение отправляет запрос к веб-сервису Google по URL-адресу для получения кода авторизации. Ответ содержит несколько параметров, включая URL-адрес и код, которые приложение показывает пользователю.
Пользователь получает URL-адрес и код с устройства, затем переключается на другое устройство или компьютер с расширенными возможностями ввода. Пользователь запускает браузер, переходит по указанному URL-адресу, входит в систему и вводит код.
Тем временем приложение опрашивает URL-адрес Google с заданным интервалом. После того, как пользователь подтверждает доступ, ответ сервера Google содержит токен доступа и токен обновления. Приложение должно сохранить токен обновления для дальнейшего использования и использовать его для доступа к API Google. По истечении срока действия токена доступа приложение использует токен обновления для получения нового токена.
Подробности см. в разделе Использование OAuth 2.0 для устройств .
Учетные записи служб
API Google, такие как Prediction API и Google Cloud Storage, могут действовать от имени вашего приложения, не обращаясь к пользовательской информации. В таких ситуациях вашему приложению необходимо подтвердить свою подлинность API, но согласие пользователя не требуется. Аналогично, в корпоративных сценариях ваше приложение может запрашивать делегированный доступ к некоторым ресурсам.
Для такого взаимодействия между серверами вам потребуется учётная запись службы , которая принадлежит вашему приложению, а не отдельному конечному пользователю. Ваше приложение обращается к API Google от имени учётной записи службы, и согласие пользователя не требуется. (В сценариях без учётной записи службы ваше приложение обращается к API Google от имени конечных пользователей, и согласие пользователя иногда требуется.)
Учетные данные учетной записи службы, которые вы получаете от , укажите сгенерированный уникальный адрес электронной почты, идентификатор клиента и как минимум одну пару открытого и закрытого ключей. Вы используете идентификатор клиента и один закрытый ключ для создания подписанного JWT и формирования запроса на получение токена доступа в соответствующем формате. Затем ваше приложение отправляет запрос на получение токена на сервер авторизации Google OAuth 2.0, который возвращает токен доступа. Приложение использует токен для доступа к API Google. По истечении срока действия токена приложение повторяет процесс.
Подробную информацию смотрите в документации по учетной записи службы .
Размер токена
Размер токенов может варьироваться до следующих пределов:
Токены доступа, возвращаемые API Security Token Service 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. Со временем в библиотеки будут добавлены новые функции.
- Клиентская библиотека Google API для Java
- Клиентская библиотека Google API для Python
- Клиентская библиотека Google API для Go
- Клиентская библиотека Google API для .NET
- Клиентская библиотека Google API для Ruby
- Клиентская библиотека Google API для PHP
- Клиентская библиотека Google API для JavaScript
- GTMAppAuth — клиентская библиотека OAuth для Mac и iOS