Руководство по внедрению OAuth 2.1

В этом руководстве рассказывается, как безопасно разрешить платформе подключенных приложений доступ к вашим сервисам. Для интеграции подключенных приложений с MCP мы настоятельно рекомендуем использовать OAuth 2.1 – отраслевой стандарт делегированной авторизации – с Proof Key for Code Exchange (PKCE). Это обеспечит максимальную безопасность пользовательских данных и надежность агентных процессов. Платформа подключенных приложений поддерживает тип предоставления доступа с кодом авторизации с параметрами Proof Key for Code Exchange (PKCE).

PKCE является обязательным для всех OAuth 2.1 и необязательным для OAuth 2.0.

Чтобы включить автоматическое обнаружение и упростить процесс интеграции, ваш сервер авторизации должен поддерживать расширение метаданных сервера авторизации, также известное как OAuth Discovery.

Совет. Чтобы пользователям не приходилось повторно связывать аккаунты, управляйте сроком действия токена обновления с помощью постоянного связывания.

Как Gemini MCP получает JSON-файл конфигурации

Консоль Gemini MCP пытается получить JSON-файл конфигурации по следующим URL в указанном порядке.

Внимание! Консоль Gemini MCP использует первый URL, который возвращает ответ, в том числе ошибку. Убедитесь, что нужная конечная точка доступна и возвращает код HTTP 200.

Если URL сервера авторизации находится на верхнем уровне домена (например, https://auth.example.com), Gemini добавляет к домену стандартные каталоги well-known и ищет сервер в следующем порядке:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

Если URL сервера авторизации находится в определенном подкаталоге или пути в вашем домене, например https://auth.example.com/realms/master, Gemini добавляет те же общеизвестные пути непосредственно к этому подкаталогу в следующем порядке:

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (поддержка вложенных путей)

Обязательные возможности JSON

Ответ с метаданными должен содержать следующие поля: Если обязательные поля отсутствуют или не найдены допустимые типы, интеграция не выполняется.

authorization_endpoint

Должен быть действительным URL.

token_endpoint

Должен быть действительным URL.

response_types_supported

Должен содержать строку code.

registration_endpoint

Пока Play Console использует Dynamic Client.

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

Если ваш сервер авторизации не поддерживает Dynamic Client Registration (DCR), вам нужно вручную реализовать и заполнить поля Идентификатор клиента и Секретный код клиента в Play Console, чтобы завершить интеграцию.

Если ваша реализация поддерживает Proof Key for Code Exchange (PKCE) или постоянные сеансы, вы должны включить соответствующие поля возможностей (такие как Challenge Methods и типы предоставления доступа) в JSON обнаружения. Это необходимо для обеспечения совместимости со стандартами безопасности и подключения Gemini. Если вы поддерживаете область действия, необходимо включить поле scopes_supported.

Пример конфигурации

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

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

Если вы используете PKCE, в блок JSON можно включить фрагмент, показанный ниже.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

Если вы используете поле scopes_supported, то в блоке JSON можно указать, например, следующее:

"scopes_supported": ["mcp", "cart.order"],

Обработка кода авторизации (упрощенная версия)

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

1. Запрос авторизации. Сервис Google определяет, что ему нужно вызвать вашу функцию, но пользователь ещё не авторизован. Чат-бот перенаправляет браузер пользователя на вашу конечную точку авторизации или показывает ссылку на нее.

   Этот запрос включает идентификатор клиента (или автоматически сгенерированный с помощью DCR), URI перенаправления Gemini и важные параметры PKCE (code_challenge и code_challenge_method).

   Добавьте в белый список следующие URL для настройки OAuth:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. Согласие пользователя. Сервер авторизации проверяет запрос, выполняет аутентификацию пользователя (вход) и просит его разрешить платформе Google доступ к данным или сервису.

3. Предоставление кода. После того как пользователь даст согласие, ваш сервер перенаправит его браузер обратно на RedirectURI Gemini, добавив к URL временный код авторизации.

4. Обмен токенами. Серверная часть Gemini отправляет запрос POST на вашу конечную точку токена, обменивая код авторизации на токен доступа.

   Примечание. Этот запрос должен включать параметр PKCE (code_verifier), чтобы подтвердить, что это тот же клиент, который запустил процесс.

5. Доступ предоставлен. Конечная точка токена проверяет код и параметры PKCE, выдает токен доступа и, при необходимости, токен обновления, а затем возвращает их Gemini.

   Совет. Хотя токены обновления необязательны, мы настоятельно рекомендуем настроить сервер авторизации так, чтобы он их выдавал. Токены обновления позволяют платформе Connected Apps Platform сохранять доступ без повторной аутентификации пользователя.

Основные требования к PKCE

PKCE добавляет уровень безопасности, предотвращающий несанкционированный перехват кодов авторизации.

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

• code_verifier – криптографически случайная строка, генерируемая Gemini в начале процесса. Эта информация конфиденциальна.
• code_challenge – преобразование code_verifier, обычно хеширование SHA256. Он отправляется в открытом виде, как описано на шаге 1 обработки кода авторизации.
• Проверка. Ваша конечная точка токена (описанная на шаге 4 обработки кода авторизации) должна подтвердить, что полученный параметр code_verifier после преобразования соответствует исходному параметру code_challenge.

Отладка

Подробная информация об ошибках при связывании аккаунтов доступна в Logs Explorer. Чтобы включить и посмотреть ошибки, следуйте инструкциям в статье Как отслеживать ошибки при связывании аккаунтов в проекте Google Console.

Требования к настройке связывания аккаунтов Google

Ознакомьтесь с приведенными ниже рекомендациями по настройке связывания аккаунтов Google.

• Связывание аккаунтов Google с помощью OAuth
• Ваш Account Linking API
• Google Account Linking API

Чтобы успешно зарегистрировать интеграцию OAuth, необходимо настроить определенные сведения о сервере авторизации. Убедитесь, что у вас есть следующие конечные точки, учетные данные и объекты.

Поле конфигурации	Описание	Ответственность разработчика
Идентификатор клиента и секретный код клиента	Уникальные учетные данные, которые сервер авторизации генерирует специально для платформы подключенных приложений. Секретный код клиента – это защищенные учетные данные (пароль), связанные с идентификатором клиента. Примечание. Если идентификатор клиента был выдан разработчиком, он должен предоставить его. Если идентификатор клиента был выдан Google, разработчику может потребоваться зарегистрировать или подтвердить секретный код.	Используйте идентификатор, предоставленный платформой, во всех запросах на авторизацию.
Конечная точка авторизации	URL, на который перенаправляются пользователи для аутентификации и предоставления согласия.	Разместите конечную точку, например https://yourdomain.com/oauth/authorize.
Конечная точка токена	Конечная точка бэкенда для обмена кодов авторизации на токены доступа/обновления и для обновления токенов с истекшим сроком действия.	Разместите эту конечную точку, например https://yourdomain.com/oauth/token.
Конечная точка отзыва Необязательно	URL, по которому ваша система получает уведомление о том, что токен нужно аннулировать, когда пользователь отключает аккаунт. Когда пользователь отменяет связь с вашей интеграцией на платформе Connected Apps Platform, мы отправляем запрос POST к конечной точке /revoke, содержащей токен доступа или токен обновления. Подробнее об отмене связи между аккаунтами…	Разместите конечную точку, например https://yourdomain.com/oauth/revoke. Ваш сервер должен обработать этот запрос, навсегда аннулировав предоставленный токен. Это гарантирует, что любые последующие попытки платформы Connected Apps Platform использовать этот токен будут неудачными, что обеспечит защиту данных пользователя после отключения.
Redirect URI (URI перенаправления)	Специальный URL обратного вызова, предоставленный платформой, на который сервер авторизации отправляет код после получения согласия.	Настройте сервер авторизации так, чтобы он принимал только официальный зарегистрированный URI перенаправления от платформы.
Как обновить данные	/token и grant_type=refresh_token Механизм, который позволяет платформе подключенных приложений получать новый токен доступа, когда срок действия текущего истекает. Это обеспечивает бесперебойную работу интеграции и избавляет пользователя от необходимости повторно входить в систему. Когда срок действия токена доступа истекает, платформа подключенных приложений автоматически отправляет запрос POST на вашу конечную точку /token. Полезная нагрузка запроса будет включать grant_type=refresh_token вместе с токеном обновления, который ранее выдал ваш сервер.	Ваш сервер должен проверить предоставленный токен обновления и вернуть новый токен доступа в ответе JSON. Кроме того, чтобы реализовать постоянную связь, не меняйте токен обновления во время этого обмена. Вместо того чтобы выпускать новый токен, верните тот же токен обновления в ответе JSON и продлите срок его действия на сервере.
Тип ответа	Чтобы поддерживать обработку кода авторизации, необходимо задать значение CODE.
Области действия	Набор разрешений и уровней доступа, определяющих, что разрешено делать токену. Они должны быть предварительно определены в вашей конфигурации, чтобы Google мог запросить их во время первоначального подтверждения авторизации.	Вам нужно будет предоставить список областей действия по умолчанию (например, openid, profile, email), которые платформа подключенных приложений должна запрашивать при запуске процесса. Запрашиваемые области действия должны быть как можно более ограниченными (принцип минимальных привилегий), но достаточными для алгоритмов достижения цели, которые поддерживает ваша интеграция с MCP.
Объекты интерфейса: логотип	Логотип разработчика, который будет показываться на экранах связывания аккаунтов и окна запроса доступа.	Квадратное векторное изображение (SVG) с круглым элементом. Минимальный размер – 500 x 500 пикселей. Примеры можно посмотреть в https://[partner-domain]/assets/logo.svg или в исходном SVG-файле.
Связывание нативных приложений (App Flip)	Чтобы поддерживать связь аккаунтов непосредственно из нативных приложений Android или iOS, настоятельно не рекомендуется полагаться на стандартные компоненты webview. Вместо этого настоятельно рекомендуется использовать переключение аккаунтов, чтобы обеспечить удобство для пользователей. Дополнительную информацию можно найти в статье Связывание аккаунта Google с помощью переключения аккаунтов на основе OAuth.	Пройдите проверку в Google Play и магазине приложений, и встройте URI перенаправления Google в нативные приложения, чтобы обеспечить безопасную авторизацию между приложениями.
Срок действия токена	(Необязательно.) Срок действия токена доступа до того, как потребуется его обновление. Полезно для настройки правил тайм-аута в GAL.	Обычно срок действия составляет от нескольких минут до нескольких дней в зависимости от требований безопасности (например, 30 days).

Распространенные ошибки интеграции

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

• Отсутствует разрешение code. Автоматическая система платформы Gemini проверяет, есть ли в response_types_supported значение code.
• Отсутствует конечная точка регистрации. Даже если ваш сервер поддерживает Client ID Metadata Documents, приложению Gemini (которое действует как клиент OAuth, подключающийся к вашему серверу) требуется, чтобы в JSON обнаружения была указана конечная точка registration_endpoint.
• Ошибка, отличная от 200. Если автоматический механизм обнаружения метаданных Gemini обращается к вашему well-known URL и получает ошибку 404 или 500, он не будет пытаться угадать другие URL. Убедитесь, что URL обнаружения общедоступен.