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

Se você quiser que o agente acesse ferramentas e serviços externos (por exemplo, tarefas do Jira ou repositórios do GitHub) em nome de um usuário específico, configure um provedor de autenticação OAuth de três pernas no gerenciador de autenticação de identidade do agente.

Os provedores de autenticação OAuth de três etapas gerenciam o redirecionamento de usuários e os tokens para você. Isso elimina a necessidade de escrever código personalizado para processar fluxos complexos do OAuth 2.0.

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.

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.
Consentimento e armazenamento: depois que o usuário concede permissão, os tokens OAuth resultantes são armazenados em um cofre de credenciais gerenciado pelo Google.
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

[Verifique se você escolheu o método de autenticação correto](/iam/docs/agent-identity-overview#auth-models).
Ative a API Agent Identity Connector.
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
Crie e implante um agente.
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.
Verifique se você tem os papéis necessários para concluir esta tarefa.

Funções exigidas

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

Para criar provedores de autenticação:
- Administrador do conector do IAM (roles/iamconnectors.admin)
- Editor do conector do IAM (roles/iamconnectors.editor)
Para usar provedores de autenticação:
- Usuário do conector do IAM (roles/iamconnectors.user)
- Acesso padrão do agente (roles/aiplatform.agentDefaultAccess)
- Editor de contexto do agente (roles/aiplatform.agentContextEditor)
- Usuário da Vertex AI (roles/aiplatform.user)
- Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)

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 necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

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

Para criar provedores de autenticação: iamconnectors.connectors.create
Para usar provedores de autenticação:
- iamconnectors.connectors.retrieveCredentials
- aiplatform.endpoints.predict
- aiplatform.sessions.create

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

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

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 pernas, use o console Google Cloud ou a Google Cloud CLI.

Console

No console Google Cloud , acesse a página Registro de agentes.
Acessar o Agent Registry
Clique no nome do agente para o qual você quer criar um provedor de autenticação.
Clique em Identidade.
Na seção Provedores de autenticação, clique em Adicionar provedor de autenticação.
No painel Adicionar provedor de autenticação, insira um nome e uma descrição.

O nome só pode conter letras minúsculas, números ou hifens, não pode terminar com um hífen e precisa começar com uma letra minúscula.
Na lista Tipo de OAuth, selecione OAuth (3 etapas) .
Clique em Criar e continuar.
Para conceder à identidade do agente permissão para usar o provedor de autenticação, clique em Conceder acesso.
Isso atribui automaticamente a função Usuário do conector (roles/iamconnectors.user) à identidade do agente no recurso do provedor de autenticação.
Copie o URL de callback.
Em outra guia, registre o URL de callback no aplicativo de terceiros.
No aplicativo de terceiros, obtenha o ID do cliente, a chave secreta do cliente, o URL do token e o URL de autorização.
Na seção Credenciais do provedor de autenticação, insira as seguintes informações:
- ID do cliente
- Client Secret
- URL do token
- URL de autorização
Clique em Adicionar configuração de provedor.

O provedor de autenticação recém-criado aparece na lista Provedores de autenticação.

CLI do Google Cloud

Crie o provedor de autenticação com URLs de autorização e token:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"

Recupere o URI de redirecionamento dos detalhes do provedor de autenticação:
```
gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"
```
O comando retorna o URI de redirecionamento no campo redirectUrl.
Registre o URI de redirecionamento com seu aplicativo de terceiros para receber o ID e a chave secreta do cliente.

Atualize o provedor de autenticação com o ID e a chave secreta do cliente:

gcloud alpha agent-identity connectors update AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET"

Para conceder à identidade do agente permissão para usar provedores de autenticação, atualize a política de permissão do IAM para o projeto ou o provedor de autenticação específico e conceda o papel Usuário do conector (roles/iamconnectors.user) ao principal do agente.

A identidade do agente é baseada no formato de ID SPIFFE padrão do setor. Nas políticas de permissão do IAM, as identidades de agente são referenciadas usando identificadores principais.
Nível do projeto (gcloud)

Conceder a função no nível do projeto permite que o agente use qualquer provedor de autenticação nesse projeto.
- Para conceder a um único agente acesso aos provedores de autenticação em um projeto, execute o seguinte comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- Para conceder a todos os agentes em um projeto acesso aos provedores de autenticação, execute o seguinte comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
No nível do conector (curl)

Para conceder a um único agente acesso a um provedor de autenticação específico, use a API setIamPolicy. Esse comando substitui qualquer política de permissão atual no recurso.
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
Substitua:
- PROJECT_ID: o ID do projeto do Google Cloud .
- AUTH_PROVIDER_NAME: o nome do provedor de autenticação.
- ORGANIZATION_ID: o ID da sua organização Google Cloud .
- PROJECT_NUMBER: o número do projeto do Google Cloud .
- LOCATION: o local do seu agente (por exemplo, us-central1).
- ENGINE_ID: o ID do mecanismo de raciocínio.

Fazer a autenticação no código do agente

Para autenticar seu agente, use o ADK ou chame a API Agent Identity diretamente.

ADK

Faça referência ao provedor de autenticação no código do seu agente usando o conjunto de ferramentas do 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 the Google Cloud Auth Provider so the CredentialManager can use it.
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the
# callback is received by the auth provider.
CONTINUE_URI = "https://YOUR_FRONTEND_URL/validateUserId"

# Create the Auth Provider scheme using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

ADK

Faça referência ao provedor de autenticação no código do seu 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/connectors/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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="YOUR_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 seu agente usando o conjunto de ferramentas do 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 by providing auth provider full resource name
auth_scheme=GcpAuthProviderScheme(
name="projects/GOOGLE_PROJECT/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
continue_uri=CONTINUE_URI)

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

toolset = registry.get_mcp_toolset(mcp_server_name="projects/GOOGLE_PROJECT/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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Chamar a API diretamente

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

Como esse é um fluxo OAuth de várias etapas, a API retorna uma operação de longa duração (LRO, na sigla em inglês). Seu agente precisa processar o ciclo de vida da operação:

Solicitação inicial: o agente liga para retrieveCredentials.
Consentimento necessário: se o usuário não tiver concedido consentimento, a API vai retornar um LRO em que os metadados contêm o auth_uri e um consent_nonce.
Redirecionamento de front-end: seu aplicativo precisa redirecionar o usuário para o auth_uri.
Conclusão: depois que o usuário der consentimento, chame FinalizeCredential 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 no OAuth de três etapas, o aplicativo do lado do cliente precisa implementar as seguintes etapas para gerenciar o consentimento do usuário e retomar a conversa:

Processar o gatilho de autorização
Implementar um endpoint de validação de usuário
Retomar a conversa com o agente

Para um exemplo completo de implementação, consulte a amostra de front-end ValidateUserId.

Processar o gatilho 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 um redirecionamento de autorização do usuário.

Gerencie o contexto da sessão gravando o consent_nonce fornecido pelo provedor de autenticação. Este valor de uso único é necessário para verificar o usuário durante a etapa de validação. Salve a auth_config e a auth_request_function_call_id na sessão para facilitar a retomada do fluxo depois que o consentimento for concedido.

if (auth_request_function_call := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(auth_request_function_call)
        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 = auth_request_function_call.get('id') if isinstance(auth_request_function_call, dict) else getattr(auth_request_function_call, '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):
    if auth_config.exchanged_auth_credential and auth_config.exchanged_auth_credential.oauth2:
        oauth2 = auth_config.exchanged_auth_credential.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

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

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

Receba user_id_validation_state e auth_provider_name como parâmetros de consulta.
Recupere o user_id e o consent_nonce do contexto da sessão.
Chame a API FinalizeCredentials do provedor de autenticação com estes parâmetros.
Feche a janela de autorização ao receber uma resposta de sucesso.

@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"),
  }

  finalize_url = f"https://iamconnectorcredentials.googleapis.com/v1alpha/{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 com o agente

Depois que o usuário der consentimento e a janela de autorização for fechada, recupere o auth_config e o 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 um 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, use a flag identity_type=AGENT_IDENTITY:

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]"],
    },
)