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

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "tal como están" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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

Al administrar las credenciales y los 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.

Advertencia:La API de IAM Connectors no estará disponible de forma general. Te recomendamos usar la API de Agent Identity. Para obtener la documentación de la API de IAM Connectors, consulta Usa la API de IAM Connectors para autenticarte con OAuth de 2 segmentos con el administrador 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 del cliente. Cuando usas el Kit de desarrollo de agentes (ADK), recupera e inserta automáticamente los tokens de acceso resultantes en los encabezados de invocación de herramientas.

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 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 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 Agent Identity de 2 segmentos, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

• Para crear proveedores de autenticación:
  • Administrador de Agent Identity (roles/agentidentity.admin)
  • Editor de Agent Identity (roles/agentidentity.editor)
• Para usar proveedores de autenticación:
  • 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 segmentos. 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 segmentos:

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

También puedes obtener estos permisos con roles personalizados o 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 autenticació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 Agent Identity (roles/agentidentity.user) en el recurso del proveedor de autenticación:

   1. Otorga acceso al ID de SPIFFE de tu agente implementado (Agent Identity):

      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 Google Cloud proyecto de.
• 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 Google Cloud organización.
• PROJECT_NUMBER: Es el número de tu Google Cloud proyecto.
• ENGINE_ID: Es el ID de tu agente de 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 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 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 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 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 Agent Identity esté habilitado.

Si realizas la implementación en Agent Runtime en Gemini Enterprise Agent Platform , usa la identity_type=AGENT_IDENTITY marca:

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?

• Descripción general de Agent Identity
• Autentica con OAuth de 3 segmentos con el administrador de autenticación
• Autentica con la clave de API con el administrador de autenticación
• Administra proveedores de autenticación de Agent Identity
• Soluciona problemas del administrador de autenticación de Agent Identity