Autentica con OAuth de 2 segmentos con el administrador de autenticación

Para permitir que tus agentes se autentiquen en herramientas externas, como ServiceNow o Salesforce, con su propia autoridad, configura la autenticación saliente con proveedores de autenticación de OAuth de 2 segmentos (credenciales de cliente) en el administrador de autenticación de Agent Identity.

Al administrar credenciales y tokens, los proveedores de autenticación de OAuth de 2 segmentos eliminan la necesidad de código personalizado para controlar los flujos de autenticación.

Flujo de trabajo de OAuth de 2 segmentos

Los proveedores de autenticación de OAuth de 2 segmentos usan la identidad del agente y no requieren el consentimiento del usuario. Google administra el almacenamiento de las credenciales de cliente. Cuando usas el Kit de desarrollo de agentes (ADK), este recupera e inserta automáticamente los tokens de acceso resultantes en los encabezados de invocación de la herramienta.

Antes de comenzar

  1. Verifica que hayas elegido el método de autenticación correcto.

  2. Habilita la API de Agent Identity.

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar la API

  3. Crea e implementa un agente.

  4. Obtén el ID de cliente y el secreto del cliente de la aplicación de terceros a la que deseas conectarte.

  5. Verifica que tengas los roles necesarios para completar esta tarea.

Roles obligatorios

Para obtener los permisos que necesitas para crear y usar un proveedor de autenticación de identidad del agente de 2 patas, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para crear y usar un proveedor de autenticación de identidad del agente de 2 patas. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear y usar un proveedor de autenticación de identidad del agente de 2 patas:

  • Para crear proveedores de autenticación, haz lo siguiente: agentidentity.authProviders.create
  • Para usar proveedores de autenticación, haz lo siguiente:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Crea un proveedor de autenticación de 2 segmentos

Crea un proveedor de autenticación para definir la configuración y las credenciales de las aplicaciones de terceros.

Para crear un proveedor de autenticación de 2 segmentos, usa gcloud CLI:

  1. Crea el proveedor de autenticación:

    gcloud alpha agent-identity authProviders create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --two-legged-oauth-client-id="CLIENT_ID" \
    --two-legged-oauth-client-secret="CLIENT_SECRET" \
    --two-legged-oauth-token-endpoint="TOKEN_ENDPOINT"
  2. Verifica que tu proveedor de autorización aparezca en la lista y que su estado sea ENABLED: 
    gcloud alpha agent-identity authProviders list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  3. Otorga permisos de acceso para permitir que tu agente y el entorno de desarrollo local recuperen credenciales del proveedor de autenticación. Para permitir que tu agente implementado y tu cuenta de usuario personal accedan al proveedor de autenticación, otorga el rol de Usuario de identidad del agente (roles/agentidentity.user) en el recurso del proveedor de autenticación:

    1. Otorga acceso al ID de SPIFFE del agente implementado (identidad del 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. Otorga acceso a tu cuenta de usuario personal para el desarrollo y las pruebas locales (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"

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • LOCATION: Es la ubicación en la que se implementan tu proveedor de autenticación y tu agente (por ejemplo, us-west1).
  • AUTH_PROVIDER_NAME: Es el nombre de tu proveedor de autenticación (por ejemplo, bigquery-mcp-3lo-authprovider).
  • AUTHORIZATION_URL: Es la URL del servidor de autorización (por ejemplo, https://accounts.google.com/o/oauth2/v2/auth).
  • TOKEN_URL: Es la URL del servidor de tokens (por ejemplo, https://oauth2.googleapis.com/token).
  • CLIENT_ID: Es el ID de cliente de OAuth que generaste desde el servicio de terceros.
  • CLIENT_SECRET: Es el secreto del cliente de OAuth que generaste desde el servicio de terceros.
  • ORGANIZATION_ID: Es el ID de tu organización Google Cloud .
  • PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
  • ENGINE_ID: Es el ID del agente del motor de razonamiento implementado.
  • USER_EMAIL: Es la dirección de correo electrónico de tu cuenta de usuario personal.

Autentícate en el código del agente

Para autenticar tu agente, puedes usar el ADK.

ADK

Haz referencia al proveedor de autenticación en el código de tu agente usando el conjunto de herramientas del MCP en el 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())

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

ADK

Haz referencia al proveedor de autenticación en el código de tu agente con una herramienta de función autenticada en el 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())

# 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 = LlmAgent(
    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

Haz referencia al proveedor de autenticación en el código de tu agente con el conjunto de herramientas del MCP de Agent Registry en el 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())

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

# 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],
)

Instala dependencias para las pruebas locales

Para probar tu agente de forma local en un entorno virtual, instala las siguientes dependencias necesarias:

  1. Crea y activa un entorno virtual: 
    python3 -m venv env
source env/bin/activate
  2. Instale los paquetes necesarios: 
    pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

Implementa el agente

Cuando implementes tu agente en Google Cloud, asegúrate de que la identidad del agente esté habilitada.

Si implementas en Agent Runtime en Gemini Enterprise Agent Platform, usa la marca 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]"],
    },
)

¿Qué sigue?