Чтобы переводить контент на ваш предпочитаемый язык, 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 для аутентификации…

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

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

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

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

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

Для приложений Android используйте тип приложения Android.
Для приложений iOS используйте тип приложения iOS.
desktop_windows Для компьютерных приложений (например, для Windows, macOS, Linux или инструментов CLI) используйте тип Приложение для компьютеров.
code Для серверных или веб-приложений JavaScript используйте тип приложения Веб-приложение. Не используйте этот тип для других приложений, например нативных или мобильных.
chrome_extension Для расширений Chrome используйте тип приложения Расширение Chrome.
tv Для устройств с ограниченными возможностями ввода, таких как телевизоры или встроенные устройства, используйте тип приложения Телевизоры и устройства с ограниченными возможностями ввода.
host Для межсерверного взаимодействия используйте сервисные аккаунты. Идентификатор клиента OAuth не требуется.

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

Чтобы получить доступ к закрытым данным через API Google, приложению нужен токен доступа. Один токен доступа может предоставлять разные уровни доступа к нескольким 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/. Метод Google People API people.updateContact требует предоставления области действия 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 выполняет аутентификацию пользователя, выбор сеанса и получение согласия пользователя. В результате будет получен код авторизации, который приложение может обменять на токен доступа и токен обновления.

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

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

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

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

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

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

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

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

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

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

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

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

Примечание. В этих сценариях сервисных аккаунтов приложения должны создавать и криптографически подписывать веб-токены JSON (JWT). Мы настоятельно рекомендуем использовать для выполнения этих задач библиотеку. Если вы напишете этот код без использования библиотеки, которая абстрагирует создание и подписание токенов, вы можете допустить ошибки, которые серьезно повлияют на безопасность вашего приложения. Список библиотек, поддерживающих этот сценарий, можно найти в документации по сервисным аккаунтам.

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

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

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

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

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

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

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

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

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

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

shield_locked Пользователь отозвал доступ приложения.
Токен обновления не использовался в течение шести месяцев.
Пользователь сменил пароль, а токен обновления содержит области действия Gmail.
В аккаунте пользователя превышено максимальное количество предоставленных (активных) токенов обновления.
Пользователь предоставил вашему приложению доступ на определенное время, и срок действия этого доступа истек.
Если администратор установил для любого из сервисов, запрашиваемых в областях действия вашего приложения, статус "Ограничено" (ошибка admin_policy_enforced).
cloud_lock Для Google Cloud Platform API – возможно, превышена длительность сеанса, заданная администратором.

Для проекта Google Cloud Platform с окном запроса доступа OAuth, настроенным для внешнего типа пользователей, и статусом публикации "Тестирование" выпускается токен обновления, срок действия которого истекает через 7 дней, если только единственные запрошенные области действия 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. Со временем в библиотеки будут добавлены дополнительные функции.