Эта страница переведена с помощью Cloud Translation API.

Использование 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, соответствующий платформе, на которой будет работать ваше приложение, например:

Для веб-приложений на стороне сервера или JavaScript используйте тип клиента «веб». Не используйте этот тип клиента для любых других приложений, таких как собственные или мобильные приложения.
Для приложений Android используйте тип клиента "Android".
Для приложений iOS и macOS используйте тип клиента «iOS».
Для приложений универсальной платформы Windows используйте тип клиента «Универсальная платформа Windows».
Для ограниченных устройств ввода , таких как телевизоры или встроенные устройства, используйте тип клиента "Телевизоры и ограниченные устройства ввода".
Для межсерверных взаимодействий используйте учетные записи служб.

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

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

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

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

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

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) или настольное приложение в качестве типа приложения.

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

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

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

Дополнительные сведения см. в разделе Использование 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, который возвращает токен доступа. Приложение использует токен для доступа к Google API. По истечении срока действия токена приложение повторяет процесс.

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

Дополнительные сведения см. в документации по служебной учетной записи .

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

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

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

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

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

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

Обновить срок действия токена

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

Пользователь отозвал доступ к вашему приложению .
Токен обновления не использовался в течение шести месяцев.
Пользователь изменил пароли, а токен обновления содержит области действия Gmail.
Учетная запись пользователя превысила максимальное количество предоставленных (действующих) токенов обновления.
Если администратор установил для какой-либо из служб, запрошенных в областях вашего приложения, значение Restricted (ошибка admin_policy_enforced ).
Для API Google Cloud Platform : длина сеанса, установленная администратором, могла быть превышена.

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

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

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

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

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