Google стремится продвигать расовое равенство для чернокожих сообществ. Смотри как.

Использование 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 .

Основные шаги

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

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

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

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

Прежде чем ваше приложение сможет получить доступ к личным данным с помощью Google API, оно должно получить токен доступа, который предоставляет доступ к этому 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/ ; для метода Google People API people.updateContact требуется предоставленная область https://www.googleapis.com/auth/contacts .

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

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

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

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

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

Сценарии

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Проекту Google Cloud Platform с экраном согласия OAuth, настроенным для внешнего типа пользователя и статусом публикации «Тестирование», выдается токен обновления, срок действия которого истекает через 7 дней.

В настоящее время существует ограничение в 50 токенов обновления на учетную запись Google для каждого идентификатора клиента OAuth 2.0. Если предел достигнут, создание нового токена обновления автоматически аннулирует самый старый токен обновления без предупреждения. Это ограничение не распространяется на учетные записи служб .

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

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

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

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

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

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

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

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