Guia de implementação do OAuth 2.1

Este guia descreve como autorizar com segurança a plataforma de apps conectados a acessar seus serviços. Para integrações de MCP de apps conectados, recomendamos o uso do OAuth 2.1, o padrão do setor para autorização delegada, com a Proof Key for Code Exchange (PKCE) para garantir a máxima segurança dos dados do usuário e confiabilidade em fluxos "agênticos". A plataforma de apps conectados oferece suporte ao tipo de permissão de acesso do código de autorização com parâmetros de Proof Key for Code Exchange (PKCE).

O PKCE é obrigatório para todo o OAuth 2.1 e opcional para o OAuth 2.0.

Para ativar a descoberta automática e simplificar o processo de integração, seu servidor de autorização precisa ser compatível com a extensão de metadados do servidor de autorização, também conhecida como OAuth Discovery.

Dica: para evitar uma experiência frustrante para o usuário e a necessidade de vincular as contas novamente, o detalhe mais importante é gerenciar o ciclo de vida do token de atualização usando a vinculação persistente.

Como o MCP do Gemini busca o JSON de configuração

O console do MCP do Gemini tenta buscar o JSON de configuração nos seguintes URLs, na ordem mostrada nesta seção.

Atenção: o console do MCP do Gemini usa o primeiro URL que retorna uma resposta, incluindo um erro. Verifique se o endpoint de sua preferência está acessível e retorna HTTP 200.

Se o URL do servidor de autorização estiver no nível superior do seu domínio (por exemplo, https://auth.example.com), o Gemini vai anexar diretórios padrão "conhecidos" ao seu domínio e procurar o servidor na seguinte ordem:

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

Se o URL do servidor de autorização estiver em um subdiretório ou caminho específico no seu domínio, por exemplo, https://auth.example.com/realms/master, o Gemini vai anexar os mesmos caminhos "conhecidos" diretamente a esse subdiretório, na seguinte ordem.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (suporte a caminhos aninhados)

Recursos JSON necessários

Sua resposta de metadados precisa incluir os campos a seguir. A integração falhará se os campos obrigatórios estiverem ausentes ou se os tipos válidos não forem encontrados.

authorization_endpoint

Precisa ser um URL de string válido.

token_endpoint

Precisa ser um URL de string válido.

response_types_supported

Precisa conter a string code.

registration_endpoint

Por enquanto, o Play Console depende do Dynamic Client.

Registro dinâmico de clientes (RFC 7591). É preciso fornecer um endpoint de registro nos metadados ou inserir o ID do cliente/secret diretamente na interface do Play Console.

Se o servidor de autorização não for compatível com o registro dinâmico de clientes (DCR, na sigla em inglês), implemente e preencha manualmente os campos ID do cliente e Chave secreta do cliente na interface do Play Console para concluir a integração.

Se a implementação for compatível com Proof Key for Code Exchange (PKCE) ou sessões persistentes, inclua os campos de capacidade relevantes (como Métodos de desafio e Tipos de permissão de acesso) no JSON de descoberta. Isso ajuda a garantir a compatibilidade com os padrões de segurança e conectividade do Gemini. Se você aceitar o escopo, inclua o campo scopes_supported.

Exemplo de configuração

Veja a seguir uma resposta JSON válida que atende aos requisitos do cliente.

{
  "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"
  ]
}

Para casos em que você inclui o PKCE, o snippet a seguir mostra um exemplo do que pode ser incluído no bloco JSON.

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

Para casos em que você inclui o campo scopes_supported, o snippet a seguir mostra um exemplo do que pode ser incluído no bloco JSON.

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

Fluxo do código de autorização (versão simplificada)

As etapas a seguir descrevem o fluxo do código de autorização padrão. Esta sequência ilustra exatamente como a plataforma de apps conectados recebe com segurança os tokens de acesso necessários do seu servidor para agir em nome de um usuário.

1. Solicitação de autorização: a plataforma do Google determina que precisa chamar sua função, mas o usuário ainda não está autorizado. O chatbot inicia o fluxo redirecionando o navegador do usuário (ou exibindo um link) para seu endpoint de autorização.

   Essa solicitação inclui seu ID do cliente (ou gerado automaticamente com DCR), o URI de redirecionamento do Gemini e parâmetros PKCE críticos (code_challenge e code_challenge_method).

   Adicione os seguintes URLs à lista de permissões para a configuração do 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. Consentimento do usuário: o servidor de autorização valida a solicitação, autentica o usuário (login) e pede que ele conceda permissão para que a plataforma do Google acesse os dados ou o serviço dele.

3. Concessão de código: depois que o usuário dá o consentimento, seu servidor redireciona o navegador do usuário de volta para o RedirectURI do Gemini, anexando um código de autorização temporário ao URL.

4. Troca de token: o back-end do Gemini envia uma solicitação POST ao seu endpoint de token, trocando o código de autorização por um token de acesso.

   Observação: essa solicitação precisa incluir o parâmetro PKCE (code_verifier) para provar que é o mesmo cliente que iniciou o fluxo.

5. Acesso concedido: o endpoint do token verifica o código e os parâmetros PKCE, emite um token de acesso e, opcionalmente, um token de atualização, e os retorna ao Gemini.

   Dica: embora os tokens de atualização sejam opcionais, recomendamos configurar o servidor de autorização para emiti-los. Os tokens de atualização permitem que a plataforma de apps conectados mantenha o acesso sem precisar reautenticar o usuário.

Principais requisitos do PKCE

A PKCE adiciona uma camada de segurança para evitar a interceptação não autorizada de códigos de autorização.

Atenção: cumprir esses requisitos de PKCE é fundamental para o gerenciamento adequado dos tokens de acesso e tokens de atualização, o que ajuda a proteger os dados do usuário e manter a integridade do ecossistema.

• code_verifier: uma string criptograficamente aleatória gerada pelo Gemini no início do fluxo. Essa informação é particular.
• code_challenge: uma transformação do code_verifier, geralmente o hash SHA256. Ele é enviado publicamente, conforme descrito na etapa 1 do fluxo do código de autorização.
• Validação: o endpoint do token (descrito na etapa 4 do fluxo do código de autorização) precisa validar se o code_verifier recebido, quando transformado, corresponde ao code_challenge original.

Depuração

Informações detalhadas sobre erros de vinculação estão disponíveis na Análise de registros. Para ativar e visualizar erros, siga as instruções em Monitorar erros de vinculação de contas no projeto do console do Google.

Requisitos de configuração da vinculação de Contas do Google

Leia as orientações da API a seguir para saber mais sobre a configuração da vinculação de Contas do Google.

• Vinculação da Conta do Google com OAuth
• API Your Account Linking
• API de vinculação da Conta do Google

Para registrar sua integração do OAuth, é preciso configurar detalhes específicos sobre o servidor de autorização. Verifique se você tem os seguintes endpoints, credenciais e recursos preparados.

Campo de configuração	Descrição	Responsabilidade do desenvolvedor
ID do cliente e secret	As credenciais exclusivas que seu servidor de autorização gera especificamente para a plataforma de apps conectados. A chave secreta do cliente é a credencial de segurança (senha) associada ao ID do cliente. Observação: se o desenvolvedor tiver emitido o ID do cliente, ele precisará fornecer essa informação. Se o Google emitiu o ID do cliente, o desenvolvedor pode precisar registrar ou verificar uma chave secreta.	Use o ID fornecido pela plataforma em todas as solicitações de autorização.
Endpoint de autorização	O URL para redirecionar os usuários para autenticação e consentimento	Hospede o endpoint, por exemplo, https://yourdomain.com/oauth/authorize.
Endpoint do token	O endpoint de back-end para trocar códigos de autorização por tokens de acesso/token de atualização e para atualizar tokens expirados.	Hospede esse endpoint, por exemplo, https://yourdomain.com/oauth/token
Endpoint de revogação Opcional	O URL para notificar seu sistema para invalidar um token quando um usuário se desconectar. Quando um usuário desvincular ou desconectar sua integração na plataforma de apps conectados, vamos fazer uma solicitação POST para o endpoint /revoke que contém o token de acesso ou o token de atualização. Consulte Desvincular contas para mais informações.	Hospede o endpoint, por exemplo, https://yourdomain.com/oauth/revoke. Seu servidor precisa processar essa solicitação invalidando permanentemente o token fornecido. Isso garante que qualquer tentativa subsequente da plataforma de apps conectados de usar esse token falhe, mantendo os dados do usuário seguros após a desconexão.
URI de redirecionamento	O URL de callback específico fornecido pela plataforma para onde o servidor de autorização envia o código de volta após o consentimento.	Configure o servidor de autorização para aceitar apenas o URI de redirecionamento oficial e registrado da plataforma.
Atualizar	/token com grant_type=refresh_token Um mecanismo que permite que a plataforma de apps conectados receba um novo token de acesso quando o atual expirar, mantendo a integração conectada sem que o usuário precise fazer login repetidamente. Quando um token de acesso expira, a plataforma de apps conectados faz automaticamente uma solicitação POST ao seu endpoint /token. O payload da solicitação vai incluir grant_type=refresh_token com o token de atualização que seu servidor emitiu anteriormente.	Seu servidor precisa validar o token de atualização fornecido e retornar um novo token de acesso na resposta JSON. Além disso, para implementar a vinculação persistente, evite alternar o token de atualização durante essa troca. Em vez de emitir um novo, retorne o mesmo token de atualização na resposta JSON e estenda a data de validade dele no back-end.
Tipo de resposta	Precisa ser configurado como CODE para oferecer suporte ao fluxo do código de autorização.
Escopos	O conjunto de permissões e níveis de acesso específicos que definem o que o token pode fazer. Eles precisam ser predefinidos na sua configuração para que o Google possa solicitá-los durante o handshake de autorização inicial.	Você precisa fornecer uma lista de escopos padrão (por exemplo, openid, profile, email) que a plataforma de apps conectados deve solicitar ao iniciar o fluxo. Os escopos solicitados precisam ser os menores possíveis (princípio de privilégio mínimo), mas totalmente suficientes para as jornadas ideais do usuário (CUJs, na sigla em inglês) que sua integração com o MCP oferece.
Recursos de interface: logotipo	Logotipo do desenvolvedor para mostrar nas telas de vinculação de conta e de permissão.	Precisa ser uma imagem vetorial quadrada (SVG) com aparência circular e pelo menos 500 x 500 pixels. Por exemplo, consulte https://[partner-domain]/assets/logo.svg ou o arquivo SVG bruto.
Vinculação de app nativo (vinculação no app)	Para oferecer suporte à vinculação de contas diretamente dos seus apps nativos para Android ou iOS, não é recomendável usar webviews padrão. Em vez disso, recomendamos implementar a vinculação no app para uma experiência do usuário integrada. Consulte Vinculação da Conta do Google com vinculação no app baseada em OAuth para mais informações.	Conclua a verificação da Google Play Store e da App Store e incorpore os URIs de redirecionamento do Google diretamente nos seus apps nativos para garantir uma transição segura de autorização entre apps.
Ciclo de vida do token	(Opcional) O período de validade de um token de acesso antes que uma atualização seja necessária. Útil para configurar políticas de tempo limite na GAL.	Os prazos de validade comuns variam de minutos, horas e dias, dependendo das necessidades de segurança, por exemplo, 30 days.

Erros comuns de integração

Confira uma lista de erros comuns e possíveis soluções que se aplicam ao processo de integração.

• Ausência da concessão "code": o sistema automatizado da plataforma Gemini verifica explicitamente se response_types_supported contém o valor "code".
• Endpoint de registro ausente: mesmo que seu servidor seja compatível com documentos de metadados de ID do cliente, o app do Gemini (atuando como o cliente OAuth que se conecta ao seu servidor) atualmente exige que um registration_endpoint dedicado esteja presente no JSON de descoberta.
• Erro não 200: se o mecanismo de descoberta de metadados automatizado do Gemini acessar seu URL conhecido e receber um erro 404 ou 500, ele não vai tentar adivinhar outros URLs. Verifique se o URL do Discovery está acessível publicamente.