Система Google OAuth 2.0 поддерживает межсерверное взаимодействие, например, между веб-приложением и сервисом Google. Для этого сценария вам потребуется учётная запись сервиса , принадлежащая вашему приложению, а не отдельному конечному пользователю. Ваше приложение обращается к API Google от имени учётной записи сервиса, поэтому пользователи не участвуют в этом напрямую. Этот сценарий иногда называют «двухсторонним OAuth» или «2LO». (Сопутствующий термин «трёхсторонний OAuth» относится к сценариям, в которых ваше приложение обращается к API Google от имени конечных пользователей, и в которых иногда требуется согласие пользователя.)
Обычно приложение использует учётную запись службы, когда оно использует API Google для работы со своими собственными данными, а не с данными пользователя. Например, приложение, использующее Google Cloud Datastore для сохранения данных, будет использовать учётную запись службы для аутентификации своих вызовов к API Google Cloud Datastore.
Администраторы домена Google Workspace также могут предоставлять учетным записям служб полномочия на уровне всего домена для доступа к пользовательским данным от имени пользователей в домене.
В этом документе описывается, как приложение может завершить межсерверный поток OAuth 2.0, используя клиентскую библиотеку API Google (рекомендуется) или HTTP.
Обзор
Для поддержки взаимодействия сервер-сервер сначала создайте учетную запись службы для вашего проекта в API ConsoleЕсли вы хотите получить доступ к данным пользователей в своей учетной записи Google Workspace, делегируйте доступ ко всему домену учетной записи службы.
Затем ваше приложение готовится к выполнению авторизованных вызовов API, используя учетные данные учетной записи службы для запроса токена доступа с сервера аутентификации OAuth 2.0.
Наконец, ваше приложение может использовать токен доступа для вызова API Google.
Создание учетной записи службы
Учётные данные сервисной учётной записи включают сгенерированный уникальный адрес электронной почты и как минимум одну пару открытого и закрытого ключей. Если включено делегирование на уровне домена, идентификатор клиента также является частью учётных данных сервисной учётной записи.
Если ваше приложение работает на Google App Engine, учетная запись службы настраивается автоматически при создании проекта.
Если ваше приложение работает на базе Google Compute Engine, учётная запись службы также автоматически настраивается при создании проекта, но при создании экземпляра Google Compute Engine необходимо указать области действия, к которым вашему приложению необходим доступ. Подробнее см. в разделе «Подготовка экземпляра к использованию учётных записей служб» .
Если ваше приложение не работает на Google App Engine или Google Compute Engine, вам необходимо получить эти учетные данные в Google API ConsoleЧтобы создать учетные данные сервисной учетной записи или просмотреть уже созданные вами общедоступные учетные данные, выполните следующие действия:
Сначала создайте учетную запись службы:
- Откройте Service accounts page.
- If prompted, select a project, or create a new one.
- Нажмите Создать сервисный аккаунт .
- В разделе « Сведения об учетной записи службы » введите имя, идентификатор и описание учетной записи службы, затем нажмите « Создать и продолжить ».
- Необязательно: в разделе « Предоставить этой учетной записи службы доступ к проекту » выберите роли IAM, которые необходимо предоставить учетной записи службы.
- Нажмите Продолжить .
- Необязательно: в разделе « Предоставить пользователям доступ к этой учетной записи службы » добавьте пользователей или группы, которым разрешено использовать учетную запись службы и управлять ею.
- Щелкните Готово .
Затем создайте ключ сервисной учетной записи:
- Щелкните адрес электронной почты созданной учетной записи службы.
- Перейдите на вкладку Ключи .
- В раскрывающемся списке Добавить ключ выберите Создать новый ключ .
- Щелкните Создать .
Ваша новая пара открытый/закрытый ключ будет сгенерирована и загружена на ваш компьютер; он служит единственной копией закрытого ключа. Вы несете ответственность за его безопасное хранение. Если вы потеряете эту пару ключей, вам нужно будет сгенерировать новую.
Вы можете вернуться к API Console В любое время можно просмотреть адрес электронной почты, отпечатки открытых ключей и другую информацию, а также сгенерировать дополнительные пары открытого и закрытого ключей. Подробнее об учетных данных сервисной учетной записи см. API Console, см. Учетные записи служб в API Consoleфайл справки.
Запишите адрес электронной почты учётной записи сервиса и сохраните файл её закрытого ключа в месте, доступном вашему приложению. Он необходим вашему приложению для выполнения авторизованных вызовов API.
Делегирование полномочий на уровне домена учетной записи службы
Используя учётную запись Google Workspace, администратор Workspace организации может разрешить приложению доступ к данным пользователей Workspace от имени пользователей в домене Google Workspace. Например, приложение, использующее API Google Календаря для добавления мероприятий в календари всех пользователей в домене Google Workspace, будет использовать учётную запись службы для доступа к API Google Календаря от имени пользователей. Разрешение учётной записи службы на доступ к данным от имени пользователей в домене иногда называется «делегированием полномочий на уровне домена» учётной записи службы.
Чтобы делегировать полномочия на уровне всего домена учетной записи службы, суперадминистратор домена Google Workspace должен выполнить следующие действия:
- В консоли администратора домена Google Workspace перейдите в Главное > Безопасность > Управление доступом и данными > Элементы управления API .
- На панели «Делегирование на уровне домена» выберите «Управление делегированием на уровне домена» .
- Нажмите Добавить новый .
- В поле «Идентификатор клиента» введите идентификатор клиента вашей учетной записи. Идентификатор клиента вашей учетной записи можно найти в Service accounts page.
- В поле «Области действия OAuth (через запятую)» введите список областей действия OAuth, к которым вашему приложению должен быть предоставлен доступ. Например, если вашему приложению требуется полный доступ к API Google Диска и API Google Календаря на уровне домена, введите: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar .
- Нажмите «Авторизовать» .
Теперь ваше приложение имеет право выполнять вызовы API от имени пользователей в вашем домене Workspace (выступать от имени пользователей). При подготовке к выполнению этих делегированных вызовов API вам необходимо явно указать пользователя, от имени которого будет выполняться эта функция.
Подготовка к выполнению делегированного вызова API
Ява
После того, как вы получите адрес электронной почты клиента и закрытый ключ от API ConsoleИспользуйте библиотеку Google Auth Library для Java , чтобы создать объект GoogleCredentials на основе учётных данных учётной записи службы и областей действия, к которым вашему приложению необходим доступ. Например:
import com.google.auth.oauth2.GoogleCredentials; import com.google.api.services.sqladmin.SQLAdminScopes; // ... GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json")) .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));
Если вы разрабатываете приложение на платформе Google Cloud Platform, вы можете использовать учетные данные приложения по умолчанию , что может упростить процесс.
Делегировать полномочия на уровне всего домена
Если у вас делегирован доступ к учетной записи службы на уровне всего домена и вы хотите выдать себя за пользователя, укажите адрес электронной почты пользователя с помощью метода createDelegated объекта GoogleCredentials . Например:
GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json")) .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN)) .createDelegated("workspace-user@example.com");
В приведенном выше коде объект GoogleCredentials используется для вызова метода createDelegated() . Аргументом метода createDelegated() должен быть пользователь, принадлежащий вашей учетной записи Workspace. Код, выполняющий запрос, будет использовать эти учетные данные для вызова API Google с использованием вашей учетной записи службы.
Питон
После того, как вы получите адрес электронной почты клиента и закрытый ключ от API Console, используйте клиентскую библиотеку Google API для Python , чтобы выполнить следующие шаги:
- Создайте объект
Credentialsна основе учетных данных учетной записи службы и областей действия, к которым вашему приложению необходим доступ. Например:from google.oauth2 import service_account SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin'] SERVICE_ACCOUNT_FILE = '/path/to/service.json' credentials = service_account.Credentials.from_service_account_file( SERVICE_ACCOUNT_FILE, scopes=SCOPES)
Если вы разрабатываете приложение на платформе Google Cloud Platform, вы можете использовать учетные данные приложения по умолчанию , что может упростить процесс.
- Делегировать полномочия на уровне всего домена
Если у вас делегирован доступ к учётной записи службы на уровне всего домена и вы хотите выдать себя за учётную запись пользователя, используйте метод
with_subjectсуществующего объектаServiceAccountCredentials. Например:delegated_credentials = credentials.with_subject('user@example.org')
Используйте объект Credentials для вызова API Google в вашем приложении.
HTTP/REST
После того, как вы получите идентификатор клиента и закрытый ключ от API Console, ваше заявление должно выполнить следующие шаги:
- Создайте JSON Web Token (JWT, произносится как «джот»), который включает заголовок, набор утверждений и подпись.
- Запросите токен доступа у сервера авторизации Google OAuth 2.0.
- Обрабатывать JSON-ответ, возвращаемый сервером авторизации.
В следующих разделах описывается, как выполнить эти шаги.
Если ответ содержит токен доступа, вы можете использовать его для вызова API Google . (Если ответ не содержит токен доступа, ваш запрос JWT и токена может быть неправильно сформирован или у учетной записи службы может не быть разрешения на доступ к запрошенным областям.)
По истечении срока действия токена доступа ваше приложение генерирует еще один JWT, подписывает его и запрашивает еще один токен доступа.
Оставшаяся часть этого раздела описывает особенности создания JWT, подписания JWT, формирования запроса на токен доступа и обработки ответа.
Создание JWT
JWT состоит из трёх частей: заголовка, набора утверждений и подписи. Заголовок и набор утверждений представляют собой JSON-объекты. Эти JSON-объекты сериализуются в байты UTF-8, а затем кодируются с использованием кодировки Base64url. Эта кодировка обеспечивает устойчивость к изменениям кодировки, возникающим при многократном кодировании. Заголовок, набор утверждений и подпись объединяются символом точки ( . ).
JWT состоит из следующих элементов:
{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}Базовая строка подписи выглядит следующим образом:
{Base64url encoded header}.{Base64url encoded claim set}Формирование заголовка JWT
Заголовок состоит из трёх полей, которые указывают алгоритм подписи, формат утверждения и [идентификатор ключа учётной записи сервиса] (https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys), использованный для подписи JWT. Алгоритм и формат являются обязательными, и каждое поле может иметь только одно значение. По мере появления дополнительных алгоритмов и форматов этот заголовок будет соответствующим образом изменяться. Идентификатор ключа необязателен, и если указан неверный идентификатор ключа, GCP попробует проверить токен со всеми ключами, связанными с учётной записью сервиса, и отклонит его, если не будет найден действительный ключ. Google оставляет за собой право отклонять токены с неверными идентификаторами ключей в будущем.
Учетные записи сервисов используют алгоритм RSA SHA-256 и формат токена JWT. В результате JSON-представление заголовка выглядит следующим образом:
{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}
Представление Base64url выглядит следующим образом:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=Формирование набора заявок JWT
Набор утверждений JWT содержит информацию о JWT, включая запрашиваемые разрешения (области действия), цель токена, эмитента, время выпуска токена и срок его действия. Большинство полей являются обязательными. Как и заголовок JWT, набор утверждений JWT представляет собой JSON-объект и используется при расчёте подписи.
Требуемые претензии
Обязательные утверждения в наборе утверждений JWT показаны ниже. Они могут располагаться в любом порядке.
| Имя | Описание |
|---|---|
iss | Адрес электронной почты учетной записи службы. |
scope | Разделенный пробелами список разрешений, которые запрашивает приложение. |
aud | Дескриптор предполагаемой цели утверждения. При запросе токена доступа это значение всегда равно https://oauth2.googleapis.com/token . |
exp | Время истечения срока действия утверждения, указанное в секундах с 00:00:00 UTC 1 января 1970 года. Это значение имеет максимум 1 час после выданного времени. |
iat | Время выдачи утверждения, указанное в секундах с 00:00:00 UTC, 1 января 1970 года. |
JSON-представление обязательных полей в наборе заявок JWT показано ниже:
{ "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "scope": "https://www.googleapis.com/auth/devstorage.read_only", "aud": "https://oauth2.googleapis.com/token", "exp": 1328554385, "iat": 1328550785 }
Дополнительные претензии
В некоторых корпоративных приложениях приложение может использовать делегирование на уровне домена для действий от имени конкретного пользователя в организации. Разрешение на выполнение такого типа олицетворения должно быть предоставлено до того, как приложение сможет олицетворять пользователя, и обычно этим занимается суперадминистратор. Подробнее см. в разделе Управление доступом к API с помощью делегирования на уровне домена .
Чтобы получить токен доступа, предоставляющий приложению делегированный доступ к ресурсу, включите адрес электронной почты пользователя в набор утверждений JWT в качестве значения sub .
| Имя | Описание |
|---|---|
sub | Адрес электронной почты пользователя, для которого приложение запрашивает делегированный доступ. |
Если у приложения нет разрешения выдавать себя за пользователя, ответом на запрос токена доступа, включающий sub , будет ошибка .
Пример набора утверждений JWT, включающего sub , показан ниже:
{ "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "sub": "some.user@example.com", "scope": "https://www.googleapis.com/auth/prediction", "aud": "https://oauth2.googleapis.com/token", "exp": 1328554385, "iat": 1328550785 }
Кодирование набора заявок JWT
Как и заголовок JWT, набор утверждений JWT должен быть сериализован в UTF-8 и закодирован в формате Base64url-safe. Ниже приведён пример JSON-представления набора утверждений JWT:
{ "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "scope": "https://www.googleapis.com/auth/prediction", "aud": "https://oauth2.googleapis.com/token", "exp": 1328554385, "iat": 1328550785 }
Вычисление подписи
JSON Web Signature (JWS) — это спецификация, определяющая механизм генерации подписи для JWT. Входными данными для подписи является массив байтов следующего содержания:
{Base64url encoded header}.{Base64url encoded claim set}При вычислении подписи необходимо использовать алгоритм подписи, указанный в заголовке JWT. Сервер авторизации Google OAuth 2.0 поддерживает только один алгоритм подписи — RSA с алгоритмом хеширования SHA-256. Это отображается как RS256 в поле alg заголовка JWT.
Подпишите представление входных данных в кодировке UTF-8 с помощью SHA256withRSA (также известного как RSASSA-PKCS1-V1_5-SIGN с хэш-функцией SHA-256) с помощью закрытого ключа, полученного из Google API Console. На выходе будет массив байтов.
Подпись должна быть закодирована в формате Base64url. Заголовок, набор утверждений и подпись объединяются символом точки ( . ). Результатом является JWT. Он должен выглядеть следующим образом (разрывы строк добавлены для ясности):
{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}Ниже приведен пример JWT до кодирования Base64url:
{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]Ниже приведен пример JWT, который подписан и готов к передаче:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ
Выполнение запроса на токен доступа
После создания подписанного JWT приложение может использовать его для запроса токена доступа. Этот запрос представляет собой HTTPS-запрос POST , а тело запроса закодировано в URL. URL-адрес показан ниже:
https://oauth2.googleapis.com/token
В HTTPS POST запросе обязательны следующие параметры:
| Имя | Описание |
|---|---|
grant_type | Используйте следующую строку, при необходимости закодированную в URL: urn:ietf:params:oauth:grant-type:jwt-bearer |
assertion | JWT, включая подпись. |
Ниже представлен необработанный дамп HTTPS-запроса POST , используемого в запросе токена доступа:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ
Ниже представлен тот же запрос с использованием curl :
curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU ' https://oauth2.googleapis.com/token
Обработка ответа
Если запрос на JWT и токен доступа сформирован правильно, а у учётной записи сервиса есть разрешение на выполнение операции, то JSON-ответ от сервера авторизации будет содержать токен доступа. Ниже приведён пример ответа:
{ "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M", "scope": "https://www.googleapis.com/auth/prediction" "token_type": "Bearer", "expires_in": 3600 }
Токены доступа можно использовать повторно в течение периода времени, указанного значением expires_in .
Вызов API Google
Ява
Используйте объект GoogleCredentials для вызова API Google, выполнив следующие шаги:
- Создайте объект службы для API, который вы хотите вызывать, используя объект
GoogleCredentials. Например:SQLAdmin sqladmin = new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credentials).build();
- Выполняйте запросы к API-сервису, используя интерфейс, предоставляемый объектом сервиса . Например, чтобы получить список экземпляров баз данных Cloud SQL в проекте exciting-example-123:
SQLAdmin.Instances.List instances = sqladmin.instances().list("exciting-example-123").execute();
Питон
Используйте авторизованный объект Credentials для вызова API Google, выполнив следующие шаги:
- Создайте объект службы для API, который вы хотите вызвать. Для создания объекта службы вызовите функцию
build, указав имя и версию API, а также авторизованный объектCredentials. Например, чтобы вызвать версию 1beta3 API администрирования Cloud SQL:import googleapiclient.discovery sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
- Выполняйте запросы к API-сервису, используя интерфейс, предоставляемый объектом сервиса . Например, чтобы получить список экземпляров баз данных Cloud SQL в проекте exciting-example-123:
response = sqladmin.instances().list(project='exciting-example-123').execute()
HTTP/REST
После того, как ваше приложение получит токен доступа, вы сможете использовать его для вызовов API Google от имени заданной учётной записи сервиса или учётной записи пользователя, если предоставлены требуемые API области доступа. Для этого включите токен доступа в запрос к API, указав либо параметр запроса access_token , либо значение Bearer HTTP-заголовка Authorization . По возможности предпочтительнее использовать HTTP-заголовок, поскольку строки запросов, как правило, отображаются в журналах сервера. В большинстве случаев для настройки вызовов API Google (например, при вызове API «Файлы на Диске ») можно использовать клиентскую библиотеку.
Вы можете опробовать все API Google и просмотреть области их действия на площадке OAuth 2.0 .
Примеры HTTP GET
Вызов конечной точки drive.files (API Drive Files) с использованием HTTP-заголовка Authorization: Bearer может выглядеть следующим образом. Обратите внимание, что вам необходимо указать собственный токен доступа:
GET /drive/v2/files HTTP/1.1 Host: www.googleapis.com Authorization: Bearer access_token
Вот вызов того же API для аутентифицированного пользователя с использованием параметра строки запроса access_token :
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
примеры curl
Вы можете протестировать эти команды с помощью приложения командной строки curl . Вот пример, использующий HTTP-заголовок (рекомендуется):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Или, в качестве альтернативы, параметр строки запроса:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Когда истекает срок действия токенов доступа
Срок действия токенов доступа, выданных сервером авторизации Google OAuth 2.0, истекает по истечении времени, указанного в значении expires_in . По истечении срока действия токена доступа приложение должно сгенерировать новый JWT, подписать его и запросить новый токен доступа.
Коды ошибок JWT
поле error | поле error_description | Значение | Как решить |
|---|---|---|---|
unauthorized_client | Unauthorized client or scope in request. | Если вы пытаетесь использовать делегирование на уровне всего домена, учетная запись службы не авторизована в консоли администратора домена пользователя. | Убедитесь, что учетная запись службы авторизована на странице делегирования на уровне домена в консоли администратора для пользователя в Хотя обычно это занимает несколько минут, для распространения авторизации на всех пользователей вашей учетной записи Google может потребоваться до 24 часов. |
unauthorized_client | Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested. | Учетная запись службы была авторизована с использованием адреса электронной почты клиента, а не идентификатора клиента (числового) в консоли администратора. | На странице делегирования на уровне домена в консоли администратора удалите клиент и добавьте его заново с числовым идентификатором. |
access_denied | (любое значение) | Если вы используете делегирование на уровне домена, одна или несколько запрошенных областей не авторизованы в консоли администратора. | Убедитесь, что учетная запись службы авторизована на странице делегирования на уровне домена консоли администратора для пользователя в Хотя обычно это занимает несколько минут, для распространения авторизации на всех пользователей вашей учетной записи Google может потребоваться до 24 часов. |
admin_policy_enforced | (любое значение) | Учетная запись Google не может авторизовать одну или несколько запрошенных областей из-за политик администратора Google Workspace. | Дополнительную информацию о том, как администратор может ограничить доступ ко всем областям или конфиденциальным и ограниченным областям до тех пор, пока доступ не будет явно предоставлен вашему идентификатору клиента OAuth, см. в справочной статье Google Workspace Управление доступом сторонних и внутренних приложений к данным Google Workspace . |
invalid_client | (любое значение) | Клиент OAuth или токен JWT недействителен или неправильно настроен. Подробности смотрите в описании ошибки. | Убедитесь, что токен JWT действителен и содержит правильные утверждения. Проверьте правильность настройки клиента OAuth и учетной записи службы , а также использование правильного адреса электронной почты. Проверьте, что токен JWT правильный и был выдан для идентификатора клиента в запросе. |
deleted_client | (любое значение) | Клиент OAuth, использованный для выполнения запроса, был удалён. Удаление может быть выполнено вручную или автоматически в случае неиспользуемых клиентов . Удалённые клиенты могут быть восстановлены в течение 30 дней с момента удаления. Подробнее . | Используйте идентификатор клиента, который все еще активен. |
invalid_grant | Not a valid email. | Пользователь не существует. | Проверьте правильность адреса электронной почты в sub (поле). |
invalid_grant | | Обычно это означает, что локальное системное время неверно. Это также может произойти, если значение exp отстоит от значения iat более чем на 65 минут, или значение exp меньше значения iat . | Убедитесь, что часы в системе, где сгенерирован JWT, установлены правильно. При необходимости синхронизируйте время с Google NTP . |
invalid_grant | Invalid JWT Signature. | Утверждение JWT подписано закрытым ключом, не связанным с учетной записью службы, указанной в адресе электронной почты клиента, или использованный ключ был удален, отключен или истек срок его действия. Альтернативно, утверждение JWT может быть закодировано неправильно — оно должно быть закодировано в формате Base64, без переносов строк или дополнительных знаков равенства. | Расшифруйте набор утверждений JWT и проверьте, что ключ, подписавший утверждение, связан с учетной записью службы. Попробуйте использовать библиотеку OAuth, предоставленную Google, чтобы убедиться, что JWT генерируется правильно. |
invalid_scope | Invalid OAuth scope or ID token audience provided. | Области действия не были запрошены (пустой список областей действия), или одна из запрошенных областей действия не существует (т.е. недействительна). | Убедитесь, что поле Обратите внимание, что список областей в заявлении об |
disabled_client | The OAuth client was disabled. | Ключ, используемый для подписи утверждения JWT, отключен. | Перейти к Google API Consoleи в разделе IAM и администрирование > Учетные записи служб включите учетную запись службы, которая содержит «Идентификатор ключа», используемый для подписи утверждения. |
org_internal | This client is restricted to users within its organization. | Идентификатор клиента OAuth в запросе является частью проекта, ограничивающего доступ к аккаунтам Google в определенной организации Google Cloud . | Используйте для аутентификации учетную запись службы организации. Подтвердите конфигурацию типа пользователя для вашего приложения OAuth. |
Приложение: Авторизация учетной записи сервиса без OAuth
Некоторые API Google позволяют выполнять авторизованные API-вызовы, используя подписанный JWT в качестве токена-предъявителя, а не токены доступа OAuth 2.0. Если это возможно, вам не придётся отправлять сетевой запрос на сервер авторизации Google перед выполнением API-вызова.
Если API, к которому вы хотите обратиться, имеет определение сервиса, опубликованное в репозитории Google API GitHub , вы можете выполнять авторизованные вызовы API, используя JWT вместо токена доступа. Для этого:
- Создайте учётную запись сервиса, как описано выше. Обязательно сохраните JSON-файл, полученный при создании учётной записи.
- Используя любую стандартную библиотеку JWT, например, найденную на jwt.io , создайте JWT с заголовком и полезной нагрузкой, как в следующем примере:
{ "alg": "RS256", "typ": "JWT", "kid": "abcdef1234567890" } . { "iss": "123456-compute@developer.gserviceaccount.com", "sub": "123456-compute@developer.gserviceaccount.com", "aud": "https://firestore.googleapis.com/", "iat": 1511900000, "exp": 1511903600 }
- Для поля
kidв заголовке укажите идентификатор закрытого ключа вашей учётной записи сервиса. Это значение можно найти в полеprivate_key_idJSON-файла вашей учётной записи сервиса. - В полях
issиsubукажите адрес электронной почты вашей учётной записи сервиса. Это значение можно найти в полеclient_emailJSON-файла вашей учётной записи сервиса. - Для поля
audукажите конечную точку API. Например:https:// SERVICE .googleapis.com/. - Для поля
iatукажите текущее время Unix, а для поляexpукажите время точно через 3600 секунд, когда истечет срок действия JWT.
Подпишите JWT с помощью RSA-256, используя закрытый ключ, найденный в JSON-файле вашей учетной записи службы.
Например:
Ява
Использование google-auth-library-java и java-jwt :
import com.google.auth.oauth2.ServiceAccountCredentials; ... GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json")); PrivateKey privateKey = ((ServiceAccountCredentials) credentials).getPrivateKey(); String privateKeyId = ((ServiceAccountCredentials) credentials).getPrivateKeyId(); long now = System.currentTimeMillis(); try { Algorithm algorithm = Algorithm.RSA256(null, privateKey); String signedJwt = JWT.create() .withKeyId(privateKeyId) .withIssuer("123456-compute@developer.gserviceaccount.com") .withSubject("123456-compute@developer.gserviceaccount.com") .withAudience("https://firestore.googleapis.com/") .withIssuedAt(new Date(now)) .withExpiresAt(new Date(now + 3600 * 1000L)) .sign(algorithm); } catch ...
Питон
Использование PyJWT :
iat = time.time() exp = iat + 3600 payload = {'iss': '123456-compute@developer.gserviceaccount.com', 'sub': '123456-compute@developer.gserviceaccount.com', 'aud': 'https://firestore.googleapis.com/', 'iat': iat, 'exp': exp} additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON} signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers, algorithm='RS256')
- Вызовите API, используя подписанный JWT в качестве токена-предъявителя:
GET /v1/projects/abc/databases/123/indexes HTTP/1.1 Authorization: Bearer SIGNED_JWT Host: firestore.googleapis.com
Реализация защиты между аккаунтами
Дополнительным шагом для защиты аккаунтов пользователей является реализация Cross-Account Protection с помощью сервиса Cross-Account Protection от Google. Этот сервис позволяет подписаться на уведомления о событиях безопасности, которые предоставляют вашему приложению информацию о важных изменениях в аккаунте пользователя. Затем вы можете использовать эту информацию для принятия мер в зависимости от того, как вы решите реагировать на события.
Вот некоторые примеры типов событий, отправляемых в ваше приложение службой Cross-Account Protection от Google:
-
https://schemas.openid.net/secevent/risc/event-type/sessions-revoked -
https://schemas.openid.net/secevent/oauth/event-type/token-revoked -
https://schemas.openid.net/secevent/risc/event-type/account-disabled
Дополнительную информацию о реализации защиты перекрестных учетных записей и полный список доступных событий см. на странице Защита учетных записей пользователей с помощью защиты перекрестных учетных записей.