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 autorización de OAuth de 2 segmentos eliminan la necesidad de código personalizado para controlar los flujos de autenticación.

Importante: En este documento, se muestra cómo autenticarse con la API de Agent Identity. Te recomendamos que uses la API de Agent Identity, ya que la API de IAM Connectors (versión preliminar) no estará disponible de forma general. Si usas la API de IAM Connectors, migra a la API de Agent Identity.

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 si aún no lo hiciste.

   Roles necesarios para habilitar las APIs

   Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). 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 crear proveedores de autenticación, sigue estos pasos:
  • Administrador de identidades de agentes (roles/agentidentity.admin)
  • Editor de identidad del agente (roles/agentidentity.editor)
• Para usar proveedores de autenticación, haz lo siguiente:
  • Usuario de Agent Identity (roles/agentidentity.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 Agent Identity 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 Agent Identity 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 la consola de Google Cloud o Google Cloud CLI.

Console

1. En la consola de Google Cloud , ve a la página Agent Registry.

   Ir a Agent Registry

2. Haz clic en el nombre del agente para el que deseas crear un proveedor de autenticación.
3. Haz clic en Identidad.
4. En la sección Proveedores de autenticación, haz clic en Agregar proveedor de autenticación.

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

6. En la lista OAuth Type, selecciona OAuth (2 legged).
7. Haz clic en Crear y continuar.
8. Para otorgar permiso a la identidad de tu agente para usar el proveedor de autenticación, haz clic en Otorgar acceso.

   Este proceso asigna automáticamente el rol de Usuario de identidad del agente (roles/agentidentity.user) a la identidad del agente en el recurso del proveedor de autenticación.

9. 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
10. Haz clic en Agregar configuración del proveedor.

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

gcloud CLI

1. Crea el proveedor de autenticación:

   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. Verifica que tu proveedor de autorización aparezca en la lista y que su estado sea ENABLED:

   gcloud agent-identity auth-providers 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 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. Otorga acceso a tu cuenta de usuario personal para el desarrollo y las pruebas locales (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"

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, jira-mcp-2lo-authprovider).
• 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.
• TOKEN_URL: Es la URL del servidor de tokens (por ejemplo, https://oauth2.googleapis.com/token).
• 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.

Nota: En los siguientes ejemplos, se registra el proveedor de autenticación a nivel del módulo, lo que funciona cuando ejecutas el agente de forma local o lo implementas con la CLI del agente. Si realizas la implementación con el SDK de Vertex AI para Python, registra el proveedor de autenticación en set_up() para que se ejecute en el contenedor implementado. Para obtener más información, consulta Implementa el agente.

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

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

Haz referencia al proveedor de Auth en el código de tu agente con el conjunto de herramientas del MCP del Agent Registry en el ADK.

No construyes un esquema de autenticación para este flujo. La vinculación saliente del servidor de MCP ya registra qué proveedor de autorización se debe usar.

Precaución: Usa la misma región para el proveedor de autenticación, el servidor de MCP y el cliente de Agent Registry. Los proveedores de Auth no están disponibles en la ubicación global, por lo que, si configuras location="global", la creación de la vinculación saliente fallará con el error 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],
)

  

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.

CLI del agente

Si usas el Kit de desarrollo de agentes (ADK) y la CLI del agente, haz lo siguiente para implementar tu agente con la identidad del agente habilitada:

1. En la carpeta de la aplicación del agente, crea un archivo de configuración llamado .agent_engine_config.json para habilitar la identidad del agente:

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

2. Implementa tu agente en Agent Runtime en Gemini Enterprise Agent Platform :

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

   Reemplaza lo siguiente:

   • AGENT_NAME: El nombre de la carpeta de la aplicación del agente (por ejemplo, maps_agent).
   • PROJECT_ID: ID del proyecto de Google Cloud.
   • LOCATION: Es la región admitida en la que deseas implementar el agente (por ejemplo, us-west1).

Python SDK

Si realizas la implementación de forma programática con el SDK de Vertex AI para Python, usa la marca identity_type=AGENT_IDENTITY:

Precaución: El SDK serializa el objeto de tu app, por lo que la llamada a CredentialManager.register_auth_provider() que ejecuta tu secuencia de comandos local en el momento de la importación no se ejecuta en el contenedor implementado. En su lugar, registra el proveedor de autenticación en el método set_up() de tu app, al que llama el tiempo de ejecución cuando se inicia el contenedor. De lo contrario, el agente fallará en el momento de la consulta con No auth provider registered for custom auth scheme 'gcpAuthProviderScheme'. Para obtener más información, consulta Consideraciones sobre la implementación.

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

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID de tu proyecto de Google Cloud .
• LOCATION: Es la región admitida en la que deseas implementar el agente (por ejemplo, us-west1).

¿Qué sigue?

• Descripción general de la identidad del agente
• Autenticación con OAuth de 3 segmentos con el administrador de autenticación
• Autenticación con una clave de API y el administrador de autenticación
• Administra proveedores de autenticación de Agent Identity
• Soluciona problemas del administrador de autenticación de Agent Identity