Autenticar usando o OAuth de três etapas com o gerenciador de autenticação

Para conceder ao agente acesso a ferramentas e serviços externos (como tarefas do Jira ou repositórios do GitHub) em nome de um usuário final específico, configure um provedor de autenticação OAuth de três etapas no gerenciador de autenticação de identidade do agente.

Ao gerenciar credenciais e tokens, os provedores de autenticação OAuth de três etapas eliminam a necessidade de código personalizado para processar fluxos de autenticação.

Fluxo de trabalho do OAuth de três etapas

Os provedores de autenticação OAuth de três etapas exigem o consentimento do usuário porque o agente acessa recursos em nome dele.

  1. Solicitação e redirecionamento: a interface de chat pede que o usuário faça login e o redireciona para a página de consentimento do aplicativo de terceiros.
  2. Consentimento e armazenamento: depois que o usuário concede permissão, o gerenciador de autenticação de identidade do agente armazena os tokens OAuth resultantes em um cofre de credenciais gerenciado pelo Google.
  3. Injeção: quando você usa o Kit de Desenvolvimento de Agente (ADK), o agente recupera automaticamente o token do provedor de autenticação e o injeta nos cabeçalhos de invocação da ferramenta.

Antes de começar

  1. Verifique se você escolheu o método de autenticação correto.

  2. Ative a API Agent Identity.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

  3. Crie e implante um agente.
  4. Verifique se você tem um aplicativo de front-end para processar solicitações de login do usuário e redirecionamento para páginas de consentimento de terceiros.
  5. Verifique se você tem os papéis necessários para concluir essa tarefa.

Funções exigidas

Para receber as permissões necessárias para criar e usar um provedor de autenticação de três etapas, peça que o administrador conceda a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para criar e usar um provedor de autenticação de três etapas. Para acessar as permissões exatas que são necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para criar e usar um provedor de autenticação de três etapas:

  • Para criar provedores de autenticação: agentidentity.authProviders.create
  • Para usar provedores de autenticação:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Criar um provedor de autenticação de três etapas

Crie um provedor de autenticação para definir a configuração e as credenciais de aplicativos de terceiros.

Para criar um provedor de autenticação de três etapas, use a CLI gcloud:

  1. Configure seu aplicativo cliente OAuth para registrar o cliente e receber um ID do cliente e uma chave secreta do cliente. Especifique o URI de redirecionamento usando o modelo nessa seção.

  2. Crie o provedor de autenticação usando as credenciais do cliente:

    gcloud alpha agent-identity authProviders create AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"
  3. Verifique se o provedor de autenticação aparece na lista e se o estado dele é ENABLED: 
    gcloud alpha agent-identity authProviders list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  4. Conceda permissões de acesso para permitir que o agente e o ambiente de desenvolvimento local ambiente recuperem credenciais do provedor de autenticação. Para permitir que o agente implantado e sua conta de usuário pessoal acessem o provedor de autenticação, conceda o papel de Usuário de identidade do agente (roles/agentidentity.user) no recurso do provedor de autenticação:

    1. Conceda acesso ao ID SPIFFE do agente implantado (identidade do agente):

      gcloud alpha agent-identity authProviders add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"

    2. Conceda acesso à sua conta de usuário pessoal para desenvolvimento e testes locais (adk web):

      gcloud alpha agent-identity authProviders add-iam-policy-binding AUTH_PROVIDER_NAME \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --role="roles/agentidentity.user" \
    --member="user:USER_EMAIL"

Substitua:

  • PROJECT_ID: o ID do Google Cloud projeto do.
  • LOCATION: o local em que o provedor de autenticação e o agente estão implantados (por exemplo, us-west1).
  • AUTH_PROVIDER_NAME: o nome do provedor de autenticação (por exemplo, bigquery-mcp-3lo-authprovider).
  • AUTHORIZATION_URL: o URL do servidor de autorização (por exemplo, https://accounts.google.com/o/oauth2/v2/auth).
  • TOKEN_URL: o URL do servidor de tokens (por exemplo, https://oauth2.googleapis.com/token).
  • CLIENT_ID: o ID do cliente OAuth gerado pelo serviço de terceiros.
  • CLIENT_SECRET: a chave secreta do cliente OAuth gerada pelo serviço de terceiros.
  • ORGANIZATION_ID: o Google Cloud ID da organização.
  • PROJECT_NUMBER: o Google Cloud número do projeto.
  • ENGINE_ID: o ID do agente do mecanismo de raciocínio implantado.
  • USER_EMAIL: o endereço de e-mail da sua conta de usuário pessoal.

Configurar o aplicativo cliente OAuth

Antes de registrar as credenciais do cliente OAuth, receba um ID e uma chave secreta do cliente do servidor de autorização de terceiros (por exemplo, Google, GitHub ou Jira).

Se você estiver se conectando a um serviço de terceiros fora do Google Cloud, receba as credenciais do cliente OAuth no portal do desenvolvedor desse serviço e pule as etapas desta seção.

Registrar o URI de redirecionamento

Ao configurar as credenciais do cliente OAuth, é necessário registrar o URI de redirecionamento de callback dedicado do provedor de autenticação.

  1. Construa o URI de redirecionamento usando o modelo a seguir:

    https://agentidentitycredentials.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/oauthcallback

    Substitua:

    • PROJECT_ID: o ID do Google Cloud projeto do.
    • LOCATION: a região em que o provedor de autenticação será implantado (por exemplo, us-west1).
    • AUTH_PROVIDER_NAME: o nome do provedor de autenticação.

    Por exemplo: https://agentidentitycredentials.googleapis.com/v1alpha/projects/my-project/locations/us-west1/authProviders/bigquery-mcp-3lo-authprovider/oauthcallback

  2. Se você estiver se conectando aos Google Cloud serviços (como o BigQuery), poderá configurar a tela de permissão e criar credenciais de cliente OAuth no Google Cloud console:

    1. Configurar a tela de permissão OAuth:

      1. No Google Cloud console, acesse a página APIs e serviços >Tela de permissão OAuth.

        Acessar APIs e serviços >Tela de permissão OAuth

      2. Na seção Informações do app, insira um nome de aplicativo (como "Aplicativo do gerenciador do BigQuery") e um e-mail de suporte.
      3. Na seção Público-alvo, selecione Interno ou Externo.
      4. Insira suas dados de contato para receber notificações.
      5. Leia e aceite a Política de dados do usuário dos serviços de API do Google.
      6. Clique em Concluir.

    2. Crie as credenciais de cliente OAuth:

      1. No Google Cloud console, acesse a página APIs e serviços > Tela de permissão OAuth  > Clientes.

        Acessar APIs e serviços >Tela de permissão OAuth >Clientes

      2. Clique em Criar credenciais >ID do cliente OAuth ID.
      3. Selecione a opção Aplicativo da Web na lista.
      4. Insira um nome reconhecível para o cliente OAuth.
      5. Na seção URIs de redirecionamento autorizados, clique em Adicionar URI e insira o URI de redirecionamento construído.
      6. Clique em Criar. Na caixa de diálogo Cliente OAuth criado, copie os valores gerados de ID do cliente e Chave secreta do cliente.

Autenticar no código do agente

Para autenticar o agente, você pode usar o ADK ou chamar a API Agent Identity diretamente.

ADK

Faça referência ao provedor de autenticação no código do agente usando o conjunto de ferramentas MCP no ADK.

from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create auth provider scheme
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Configure an MCP tool with the authentication scheme.
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="https://YOUR_MCP_SERVER_URL"),
    auth_scheme=auth_scheme,
)

# Initialize the agent with the authenticated tools.
agent = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Exemplo: como se conectar ao BigQuery MCP

O exemplo a seguir mostra uma configuração agent.py que conecta um agente ao servidor MCP do BigQuery:

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
import google.auth
from google.genai import types

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME"
bigquery_mcp_endpoint = os.environ.get(
    "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp"
)

# Register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# URI to redirect user to after consent is granted.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/authProviders/{bigquery_mcp_auth_provider_id}",
    scopes=["https://www.googleapis.com/auth/bigquery"],
    continue_uri=CONTINUE_URI,
)

bigquery_mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url=bigquery_mcp_endpoint),
    auth_scheme=bigquery_mcp_auth_scheme,
    errlog=None,
)

root_agent = Agent(
    name="root_agent",
    model=Gemini(
        model="gemini-2.5-flash",
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    instruction=(
        "You are a helpful AI assistant designed to provide accurate and useful"
        " information. You can also use your BigQuery MCP tools to look up"
        " BigQuery data."
    ),
    tools=[bigquery_mcp_tools],
)

app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

ADK

Faça referência ao provedor de autenticação no código do agente usando uma ferramenta de função autenticada no ADK.

import httpx
from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.apps import App
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
from vertexai import agent_engines

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# Use the Auth Config in Authenticated Function Tool
spotify_search_track_tool = AuthenticatedFunctionTool(
    func=spotify_search_track, auth_config=spotify_auth_config
)

# Sample function tool
async def spotify_search_track(credential: AuthCredential, query: str) -> str | list:
    token = None
    if credential.http and credential.http.credentials:
        token = credential.http.credentials.token

    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://api.spotify.com/v1/search",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query, "type": "track", "limit": 1},
        )
        # Add your own logic here

agent = LlmAgent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

Faça referência ao provedor de autenticação no código do agente usando o conjunto de ferramentas MCP do registro de agentes no ADK.

from google.adk.agents.llm_agent import LlmAgent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_identity import GcpAuthProviderScheme
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.auth.auth_tool import AuthConfig
from google.adk.integrations.agent_registry import AgentRegistry

# First, register Google Cloud auth provider
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider scheme
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    continue_uri=CONTINUE_URI
)

# Set Agent Registry
registry = AgentRegistry(project_id="PROJECT_ID", location="global")

toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "global/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
    auth_scheme=auth_scheme,
)

# Example MCP tool
toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url="MCP_URL"),
    auth_scheme=auth_scheme,
)

agent = LlmAgent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Chamar a API diretamente

Se você não estiver usando o ADK, o agente precisará chamar a API agentidentitycredentials.retrieveCredentials para receber o token.

Como esse é um fluxo OAuth de várias etapas, o agente precisa processar o ciclo de vida da operação:

  1. Solicitação inicial: o agente chama retrieveCredentials.
  2. Consentimento necessário: se o usuário não tiver concedido o consentimento, a API retornará uma resposta contendo o resultado como uri_consent_required. Isto vai conter authorization_uri e um consent_nonce.
  3. Redirecionamento de front-end: seu aplicativo precisa redirecionar o usuário para o authorization_uri.
  4. Conclusão: depois que o usuário concede o consentimento, chame FinalizeCredentials usando o consent_nonce para concluir o fluxo e receber o token.

Atualizar o aplicativo do lado do cliente

Para processar o login e o redirecionamento do usuário para o OAuth de três etapas, o aplicativo do lado do cliente precisa implementar as etapas a seguir para gerenciar o consentimento do usuário e retomar a conversa:

Servidor de interface de amostra

Você pode fazer o download e executar um servidor UI de amostra completo que usa uvicorn. Antes de começar, verifique se você tem uma conta do GitHub e o pip instalado.

Para configurar e executar o servidor UI de amostra, faça o seguinte:

  1. Clone o repositório do GitHub adk-python:

    git clone https://github.com/google/adk-python.git

  2. Navegue até o repositório e ative um ambiente virtual Python:

    cd adk-python
python3 -m venv .venv
source .venv/bin/activate

  3. Navegue até o diretório do cliente UI de amostra:

    cd contributing/samples/integrations/gcp_auth/client

  4. Instale as dependências do cliente:

    pip install -r requirements.txt

  5. Antes de iniciar o servidor, defina a variável de ambiente AGENT_PROJECT_DIR para especificar o diretório em que o código do agente está localizado. Caso contrário, o aplicativo vai procurar agentes em a pasta mãe do diretório do cliente.

    Inicie o servidor UI de amostra usando uvicorn. Verifique se a porta corresponde ao URI de redirecionamento configurado no cliente OAuth:

    export AGENT_PROJECT_DIR="/path/to/your/agent_project"
uvicorn main:app --port 8501 --reload

  6. Abra http://localhost:8501 no navegador. Observação: é necessário usar localhost e não 127.0.0.1, porque o URL de redirecionamento OAuth exige especificamente o nome do host localhost. Especifique as configurações, clique Salvar e aplicar configurações e interaja com o agente.

Aplicativo de interface personalizada

Para implementar esses recursos diretamente em um aplicativo UI personalizada, siga estas etapas:

Processar o acionador de autorização

Quando um agente precisa do consentimento do usuário, ele retorna uma chamada de função adk_request_credential. Seu aplicativo precisa interceptar essa chamada para iniciar uma caixa de diálogo ou redirecionamento de autorização do usuário.

Gerencie o contexto da sessão gravando o consent_nonce fornecido pelo provedor de autenticação. Esse nonce é necessário para verificar o usuário durante a etapa de validação. Salve os valores auth_config e auth_request_function_call_id na sessão para facilitar a retomada do fluxo depois que o usuário concede o consentimento.

if (fc := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(fc)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, AUTH_PROVIDER_NAME, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = (
                fc.get('id') if isinstance(fc, dict)
                else getattr(fc, 'id', None)
            )
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    ec = auth_config.exchanged_auth_credential
    if ec and ec.oauth2:
        oauth2 = ec.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Implementar um endpoint de validação do usuário

Implemente um endpoint de validação no servidor da Web (o mesmo URI fornecido como continue_uri durante a configuração). Esse endpoint precisa fazer o seguinte:

  1. Receber user_id_validation_state, auth_provider_name, e uuid como parâmetros de consulta.
  2. Recuperar os valores user_id e consent_nonce do armazenamento de sessão. Se vários fluxos de autorização forem executados simultaneamente, use o uuid para corresponder à sessão correta.
  3. Chame a API FinalizeCredentials do provedor de autenticação com esses parâmetros.
  4. Feche a janela de autorização ao receber uma resposta de sucesso.
Exemplo: endpoint de validação do FastAPI (main.py)

O exemplo a seguir mostra um endpoint de validação do FastAPI completo que processa o callback OAuth e finaliza as credenciais do usuário:

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
    auth_provider_name = request.query_params.get("auth_provider_name")
    session_id = request.cookies.get("session_id")
    session = consent_sessions.get(session_id, {})

    payload = {
        "userId": session.get("user_id"),
        "userIdValidationState": request.query_params.get(
            "user_id_validation_state"
        ),
        "consentNonce": session.get("consent_nonce"),
    }

    base_url = "https://agentidentitycredentials.googleapis.com/v1alpha"
    finalize_url = f"{base_url}/{auth_provider_name}/credentials:finalize"

    try:
        async with httpx.AsyncClient(timeout=30.0) as client:
            resp = await client.post(finalize_url, json=payload)
            resp.raise_for_status()
    except httpx.HTTPError as e:
        err_text = e.response.text if hasattr(e, "response") else str(e)
        status = e.response.status_code if hasattr(e, "response") else 500
        return HTMLResponse(err_text, status_code=status)

    return HTMLResponse("""
        <script>
            window.close();
        </script>
        <p>Success. You can close this window.</p>
    """)

Retomar a conversa do agente

Depois que o usuário concede o consentimento e a janela de autorização é fechada, recupere os valores auth_config e auth_request_function_call_id dos dados da sessão. Para continuar a conversa, inclua esses detalhes em uma nova solicitação ao agente como uma function_response.

if (request.is_auth_resume and session.auth_request_function_call_id
    and session.auth_config):
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

Implantar o agente

Ao implantar o agente no Google Cloud, verifique se a identidade do agente está ativada.

Se você estiver implantando no Agent Runtime na Gemini Enterprise Agent Platform , use a identity_type=AGENT_IDENTITY flag:

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp

# Initialize the Vertex AI client with v1beta1 API for Agent Identity support
client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=dict(api_version="v1beta1")
)

# Use the proper wrapper class for your Agent Framework (e.g., AdkApp)
app = AdkApp(agent=agent)

# Deploy the agent with Agent Identity enabled
remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": [
            "google-cloud-aiplatform[agent_engines,adk]",
            "google-adk[agent-identity]"
        ],
    },
)

A seguir