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 identidad del agente.

Los proveedores de autenticación de OAuth de 2 segmentos administran las credenciales y los tokens por ti. Esto elimina la necesidad de escribir 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 inyecta automáticamente los tokens de acceso resultantes en los encabezados de invocación de la herramienta.

Antes de comenzar

Verifica que hayas elegido el método de autenticación correcto.
Habilita la API de Agent Identity Connector.
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
Crea e implementa un agente.
Obtén el ID de cliente y el secreto del cliente de la aplicación de terceros a la que deseas conectarte.
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 crear proveedores de autenticación, haz lo siguiente:
- Administrador del conector de IAM (roles/iamconnectors.admin)
- Editor de conectores de IAM (roles/iamconnectors.editor)
Para usar proveedores de autenticación, haz lo siguiente:
- Usuario del conector de IAM (roles/iamconnectors.user)
- Acceso predeterminado del agente (roles/aiplatform.agentDefaultAccess)
- Editor de contexto del agente (roles/aiplatform.agentContextEditor)
- Usuario de Vertex AI (roles/aiplatform.user)
- Consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer)

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: iamconnectors.connectors.create
Para usar proveedores de autenticación, haz lo siguiente:
- iamconnectors.connectors.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 la consola de Google Cloud o Google Cloud CLI.

Console

En la consola de Google Cloud , ve a la página Agent Registry.
Ir a Agent Registry
Haz clic en el nombre del agente para el que deseas crear un proveedor de autenticación.
Haz clic en Identidad.
En la sección Proveedores de autenticación, haz clic en Agregar proveedor de autenticación.
En el panel Agregar proveedor de autenticación, ingresa un nombre y una descripción.

El nombre solo puede contener letras minúsculas, números o guiones, no puede terminar con un guion y debe comenzar con una letra minúscula.
En la lista OAuth Type, selecciona OAuth (2 legged).
Haz clic en Crear y continuar.
Para otorgar permiso a la identidad de tu agente para usar el proveedor de autenticación, haz clic en Otorgar acceso.
Esto asigna automáticamente el rol de Usuario del conector (roles/iamconnectors.user) a la identidad del agente en el recurso del proveedor de autenticación.
En la sección Credenciales del proveedor de autenticación, ingresa la siguiente información:
- Client ID (ID de cliente)
- Client Secret (Secreto del cliente)
- URL del token
Haz clic en Agregar configuración del proveedor.

El proveedor de autenticación recién creado aparecerá en la lista Auth Providers.

Google Cloud CLI

Crea el proveedor de autenticación:

gcloud alpha agent-identity connectors 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"

Para otorgar permiso de identidad del agente para usar proveedores de Auth, actualiza la política de IAM de permiso para el proyecto o el proveedor de Auth específico, y otorga el rol de Usuario del conector (roles/iamconnectors.user) al principal del agente.

La identidad del agente se basa en el formato de ID de SPIFFE estándar de la industria. En las políticas de permisos de IAM, se hace referencia a las identidades de los agentes con identificadores de principal.
A nivel del proyecto (gcloud)

Si se otorga el rol a nivel del proyecto, el agente podrá usar cualquier proveedor de autenticación en ese proyecto.
- Para otorgar acceso a un solo agente a los proveedores de autenticación en un proyecto, ejecuta el siguiente 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 otorgar a todos los agentes de un proyecto acceso a los proveedores de autenticación, ejecuta el siguiente 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"
A nivel del conector (curl)

Para otorgar acceso a un solo agente a un proveedor de autorización específico, usa la API de setIamPolicy. Este comando reemplaza cualquier política de permisos existente en el 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"
```
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto de Google Cloud .
- AUTH_PROVIDER_NAME: Es el nombre del proveedor de autenticación.
- ORGANIZATION_ID: Es el ID de tu organización Google Cloud .
- PROJECT_NUMBER: Es el número de tu proyecto de Google Cloud .
- LOCATION: Es la ubicación de tu agente (por ejemplo, us-central1).
- ENGINE_ID: Es el ID de tu motor de razonamiento.

Autentícate en el código de tu agente

Para autenticar tu agente, puedes usar el ADK.

ADK

Haz referencia al proveedor de autenticación en el código de tu agente con el conjunto de herramientas de 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 using the auth provider's full resource name.
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_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
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/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="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

Haz referencia al proveedor de autenticación en el código de tu agente con el conjunto de herramientas de MCP del registro de agentes 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 by providing Auth Provider full resource name
auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/connectors/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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_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:

Crea y activa un entorno virtual:

python3 -m venv env
source env/bin/activate

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 realizas la implementación en Agent Runtime, 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]"],
    },
)