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

Console

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

   Acessar o registro de agentes

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 add Adicionar provedor de autenticação.

5. No painel Adicionar provedor de autenticação, insira um nome e uma descrição.

   O nome pode conter apenas letras minúsculas, números ou hífens, 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 (3 etapas) .
7. Clique em Criar e continuar.
8. Para conceder permissão de identidade do agente para usar o provedor de autenticação, clique em Conceder acesso.

   Isso atribui automaticamente o papel Usuário do conector (roles/iamconnectors.user) à identidade do agente no recurso do provedor de autenticação.

9. Copie o URL de callback.
10. Em outra guia, registre o URL de callback no aplicativo de terceiros.
11. No aplicativo de terceiros, receba o ID do cliente, a chave secreta do cliente, o URL do token e o URL de autorização.
12. 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
13. Clique em Adicionar configuração do provedor.

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

Google Cloud CLI

1. 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"

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

3. Registre o URI de redirecionamento no aplicativo de terceiros para receber o ID e a chave secreta do cliente.

4. 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"

5. Para conceder permissão de identidade do agente 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 do agente são referenciadas usando identificadores principais.

   Nível do projeto (gcloud)

   A concessão do papel no nível do projeto permite que o agente use qualquer provedor de autenticação nesse projeto.

   • Para conceder acesso a um único agente 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 acesso a todos os agentes em um projeto 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"

   Nível do conector (curl)

   Para conceder acesso a um único agente a um provedor de autenticação específico, use a setIamPolicy API. Esse comando substitui qualquer política de permissão existente 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 Cloud de Confiance projeto do.
   • AUTH_PROVIDER_NAME: o nome do provedor de autenticação.
   • ORGANIZATION_ID: o ID da sua Cloud de Confiance organização.
   • PROJECT_NUMBER: o número do seu projeto. Cloud de Confiance
   • LOCATION: o local do seu agente (por exemplo, us-central1).
   • ENGINE_ID: o ID do seu mecanismo de raciocínio.

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.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 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 Cloud de Confiance 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 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 Cloud de Confiance 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 Cloud de Confiance 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). 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 LRO em que os metadados contêm o auth_uri e um consent_nonce.
3. Redirecionamento de front-end: seu aplicativo precisa redirecionar o usuário para o auth_uri.
4. Conclusão: depois que o usuário concede o consentimento, chame FinalizeCredential usando o consent_nonce para concluir o fluxo e receber o token.