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

Для приложений Android Android тип клиента.
Для приложений iOS и macOS используйте iOS тип клиента.
Для серверных или JavaScript веб-приложений используйте следующий код : Веб-приложение Тип клиента. Не используйте этот тип клиента для других приложений, таких как нативные или мобильные приложения.
Для приложений универсальной платформы Windows используйте Универсальная платформа Windows (UWP) тип клиента.
Для расширений Chrome используйте тип клиента «Расширение Chrome» .
Для устройств с ограниченным набором входных сигналов , таких как телевизоры или встроенные устройства, используйте следующее: Телевизоры и устройства с ограниченным набором входных данных тип клиента.
Для взаимодействия между серверами используйте учетные записи служб. Идентификатор клиента OAuth не требуется.

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-запроса Authorization . Можно отправлять токены в качестве параметров URI-запроса, но мы не рекомендуем этого делать, поскольку параметры URI могут попадать в небезопасные файлы журналов. Кроме того, в REST-практике рекомендуется избегать создания ненужных имен параметров URI.

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

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, универсальную платформу Windows (UWP) или настольное приложение.

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

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

Подробности см. в разделах «Авторизация доступа к пользовательским данным Google» для Android и «OAuth 2.0» для iOS и настольных приложений .

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

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

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

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

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

Более подробную информацию см. в разделе «Использование OAuth 2.0 для клиентских приложений» .

Применение на устройствах с ограниченным количеством входных сигналов

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

Процесс авторизации начинается с того, что приложение отправляет запрос к веб-сервису 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 Web Tokens (JWT). Мы настоятельно рекомендуем использовать библиотеку для выполнения этих задач. Если вы напишете этот код без использования библиотеки, которая абстрагирует создание и подписание токенов, вы можете допустить ошибки, которые серьезно повлияют на безопасность вашего приложения. Список библиотек, поддерживающих этот сценарий, см. в документации по учетным записям служб .

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

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

Более подробную информацию см. в документации по учетным записям служб .

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

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

Размер токенов может варьироваться в пределах следующих лимитов:

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

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

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

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

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

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

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

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

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

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