Autenticar usando o OAuth de duas etapas com o gerenciador de autenticação

Para permitir que seus agentes se autentiquem em ferramentas externas, como ServiceNow ou Salesforce, usando a própria autoridade, configure a autenticação de saída usando provedores de autenticação OAuth de duas pernas (credenciais do cliente) no gerenciador de autenticação de identidade do agente.

Ao gerenciar credenciais e tokens, os provedores de autenticação OAuth de duas etapas eliminam a necessidade de código personalizado para lidar com fluxos de autenticação.

Importante:este documento mostra como autenticar usando a API Identidade do Agente. Recomendamos usar a API Identidade do Agente porque a API IAM Connectors (Pré-lançamento) não estará disponibilidade geral. Se você estiver usando a API IAM Connectors, migre para a API Identidade do Agente.

Fluxo de trabalho do OAuth de duas etapas

Os provedores de autenticação OAuth de duas pernas usam a identidade do agente e não exigem consentimento do usuário. O Google gerencia o armazenamento das credenciais do cliente. Quando você usa o Kit de Desenvolvimento de Agente (ADK), ele recupera e injeta automaticamente os tokens de acesso resultantes 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 Identidade do Agente.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

3. Crie e implante um agente.

4. Receba o ID do cliente e a chave secreta do cliente do aplicativo de terceiros que você quer conectar.

5. Verifique se você tem os papéis necessários para concluir esta tarefa.

Funções exigidas

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

• Para criar provedores de autenticação:
  • Administrador de identidade do agente (roles/agentidentity.admin)
  • Editor de identidade do agente (roles/agentidentity.editor)
• Para usar provedores de autenticação:
  • Usuário de identidade do agente (roles/agentidentity.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 identidade do agente de duas pernas. 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 identidade do agente de duas pernas:

• 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 funções personalizadas ou outros papéis predefinidos.

Criar um provedor de autenticação de duas 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 duas etapas, use o console Google Cloud ou a Google Cloud CLI.

Console

1. No console Google Cloud , acesse a página Registro de agentes.

   Acessar o Agent Registry

2. Clique no nome do agente para o qual você quer criar um provedor de autenticação.
3. Clique em Identidade.
4. Na seção Provedores de autenticação, clique em Adicionar provedor de autenticação.

5. 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.

6. Na lista Tipo de OAuth, selecione OAuth (2 pernas) .
7. Clique em Criar e continuar.
8. Para conceder à identidade do agente permissão para usar o provedor de autenticação, clique em Conceder acesso.

   Esse processo atribui automaticamente a função Usuário da identidade do agente (roles/agentidentity.user) à identidade do agente no recurso do provedor de autenticação.

9. Na seção Credenciais do provedor de autenticação, insira as seguintes informações:
   • ID do cliente
   • Client Secret
   • URL do token
10. Clique em Adicionar configuração de provedor.

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

CLI da gcloud

1. Crie o provedor de autenticação:

   gcloud agent-identity auth-providers create AUTH_PROVIDER_NAME \
       --location="LOCATION" \
       --two-legged-oauth-client-id="CLIENT_ID" \
       --two-legged-oauth-client-secret="CLIENT_SECRET" \
       --two-legged-oauth-token-url="TOKEN_URL"

2. Verifique se o provedor de autenticação aparece na lista e se o estado dele é ENABLED:

   gcloud agent-identity auth-providers list \
      --project="PROJECT_ID" \
      --location="LOCATION"

3. Conceda permissões de acesso para permitir que seu agente e o ambiente de desenvolvimento local 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 Usuário da identidade do agente (roles/agentidentity.user) no recurso do provedor de autenticação:

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

      gcloud agent-identity auth-providers 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 agent-identity auth-providers 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 projeto do Google Cloud .
• LOCATION: o local em que seu provedor de autenticação e agente são implantados (por exemplo, us-west1).
• AUTH_PROVIDER_NAME: o nome do provedor de autenticação (por exemplo, jira-mcp-2lo-authprovider).
• 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.
• TOKEN_URL: o URL do servidor de token (por exemplo, https://oauth2.googleapis.com/token).
• ORGANIZATION_ID: o ID da organização Google Cloud .
• PROJECT_NUMBER: o número do projeto do Google Cloud .
• 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.

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

Para autenticar seu agente, use o ADK.

Observação:os exemplos a seguir registram o provedor de autenticação no nível do módulo, o que funciona quando você executa o agente localmente ou o implanta com a CLI do agente. Se você fizer a implantação com o SDK da Vertex AI para Python, registre o provedor de autenticação em set_up() para que ele seja executado no contêiner implantado. Para mais informações, consulte Implantar o agente.

ADK

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

from google.adk.agents import Agent
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())

# Create the Google Cloud 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"
)

# 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 = Agent(
    name="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

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 import Agent
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())

# Create Auth Config
# Note: If using the legacy V1 API, the resource name uses 'connectors'
# instead of 'authProviders': projects/.../connectors/...
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name=(
            "projects/PROJECT_ID/locations/"
            "LOCATION/authProviders/"
            "AUTH_PROVIDER_NAME"
        )
    )
)

# 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 = Agent(
    name="AGENT_NAME",
    model="MODEL_NAME",
    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 Agent Registry no ADK.

Você não cria um esquema de autenticação para esse fluxo. A vinculação de saída do servidor MCP já registra qual provedor de autenticação usar.

Atenção:use a mesma região para o provedor de autenticação, o servidor MCP e o cliente do Agent Registry. Os provedores de autenticação não estão disponíveis no local global. Portanto, se você definir location="global", a criação da vinculação de saída vai falhar com o erro Location of auth provider does not match location of binding.

from google.adk.agents import Agent
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider
from google.adk.integrations.agent_registry import AgentRegistry

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

# Set Agent Registry. LOCATION must be the same region as the auth provider.
registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")

# The auth provider is resolved from the MCP server's outbound binding.
toolset = registry.get_mcp_toolset(
    mcp_server_name=(
        "projects/PROJECT_ID/locations/"
        "LOCATION/mcpServers/"
        "agentregistry-00000000-0000-0000-0000-000000000000"
    ),
)

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

  

Instalar dependências para testes locais

Para testar o agente localmente em um ambiente virtual, instale as seguintes dependências necessárias:

1. Crie e ative um ambiente virtual:

   python3 -m venv env
   source env/bin/activate

2. Instale os pacotes necessários.

   pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

Implantar o agente

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

CLI do agente

Se você estiver usando o Kit de Desenvolvimento de Agente (ADK) e a CLI do agente, faça o seguinte para implantar seu agente com a identidade do agente ativada:

1. Na pasta do aplicativo do agente, crie um arquivo de configuração chamado .agent_engine_config.json para ativar a identidade do agente:

   echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

2. Implante seu agente no Agent Runtime na Gemini Enterprise Agent Platform :

   uv run adk deploy agent_engine AGENT_NAME \
       --project="PROJECT_ID" \
       --region="LOCATION"

   Substitua:

   • AGENT_NAME: o nome da pasta do aplicativo do seu agente (por exemplo, maps_agent).
   • PROJECT_ID: o ID do projeto do Google Cloud.
   • LOCATION: a região com disponibilidade em que você quer implantar o agente (por exemplo, us-west1).

SDK do Python

Se você estiver fazendo a implantação de forma programática usando o SDK da Vertex AI para Python, use a flag identity_type=AGENT_IDENTITY:

Atenção:o SDK serializa o objeto do app. Portanto, a chamada CredentialManager.register_auth_provider() que o script local executa durante a importação não é executada no contêiner implantado. Em vez disso, registre o provedor de autenticação no método set_up() do seu app, que o tempo de execução chama quando o contêiner é iniciado. Caso contrário, o agente vai falhar no momento da consulta com No auth provider registered for custom auth scheme 'gcpAuthProviderScheme'. Para mais informações, consulte Considerações sobre a implantação.

import vertexai
from vertexai import types
from vertexai.agent_engines import AdkApp
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider

# 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")
)

# Register the auth provider in set_up() so that it runs in the deployed
# container. Use the proper wrapper class for your Agent Framework (for example, AdkApp).
class AuthenticatedAdkApp(AdkApp):
    def set_up(self):
        CredentialManager.register_auth_provider(GcpAuthProvider())
        super().set_up()

app = AuthenticatedAdkApp(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,mcp]>=2.7.1",
        ],
    },
)

Substitua:

• PROJECT_ID: o ID do projeto do Google Cloud .
• LOCATION: a região com disponibilidade em que você quer implantar o agente (por exemplo, us-west1).

A seguir

• Visão geral da identidade do agente
• Autenticar usando o OAuth de três etapas com o gerenciador de autenticação
• Autenticar usando a chave de API com o gerenciador de autenticação
• Gerenciar provedores de autenticação de identidade do agente
• Resolver problemas do gerenciador de autenticação de identidade do agente