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

Si quieres que tu agente acceda a herramientas y servicios externos (por ejemplo, tareas de Jira o repositorios de GitHub) en nombre de un usuario específico, debes configurar un proveedor de autenticación de OAuth de 3 segmentos en el administrador de autenticación de Agent Identity.

Los proveedores de autenticación de OAuth de 3 segmentos administran la redirección y los tokens de los usuarios por ti. Esto elimina la necesidad de escribir código personalizado para controlar flujos complejos de OAuth 2.0.

Flujo de trabajo de OAuth de 3 segmentos

Los proveedores de autenticación de OAuth de 3 segmentos requieren el consentimiento del usuario porque el agente accede a los recursos en nombre del usuario.

Solicitud y redireccionamiento: La interfaz de chat le solicita al usuario que acceda y, luego, lo redirecciona a la página de consentimiento de la aplicación de terceros.
Consentimiento y almacenamiento: Después de que el usuario otorga permiso, los tokens de OAuth resultantes se almacenan en una bóveda de credenciales administrada por Google.
Inyección: Cuando usas el Kit de desarrollo de agentes (ADK), el agente recupera automáticamente el token del proveedor de autenticación y lo inyecta en los encabezados de invocación de la herramienta.

Antes de comenzar

[Verifica que hayas elegido el método de autenticación correcto](/iam/docs/agent-identity-overview#auth-models).
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.
Asegúrate de tener una aplicación de frontend para controlar las solicitudes de acceso del usuario y la redirección a las páginas de consentimiento de terceros.
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 Auth de 3 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 IAM Connector (roles/iamconnectors.admin)
- Editor de IAM Connector (roles/iamconnectors.editor)
Para usar proveedores de autenticación:
- Usuario de IAM Connector (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 3 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 3 segmentos:

Para crear proveedores de autenticación: iamconnectors.connectors.create
Para usar proveedores de autenticación:
- iamconnectors.connectors.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 3 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 3 segmentos, usa la Google Cloud consola o Google Cloud CLI.

Console

En la Google Cloud consola, ve a la página Agent Registry.
Ir al registro de agentes
Haz clic en el nombre del agente para el que deseas crear un proveedor de autenticación.
Haz clic en Identity.
En la sección Auth Providers, 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 Tipo de OAuth, selecciona OAuth (3 segmentos) .
Haz clic en Crear y continuar.
Para otorgar permiso de identidad de agente para usar el proveedor de autenticación, haz clic en Otorgar acceso.
Esto asigna automáticamente el rol Usuario de conector (roles/iamconnectors.user) a la identidad del agente en el recurso del proveedor de autenticación.
Copia la URL de devolución de llamada.
En otra pestaña, registra la URL de devolución de llamada en tu aplicación de terceros.
Desde tu aplicación de terceros, obtén el ID de cliente, el secreto del cliente, la URL del token y la URL de autorizació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
- URL de autorización
Haz clic en Agregar configuración del proveedor.

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

Google Cloud CLI

Crea el proveedor de autenticación con las URLs de autorización y 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"

Recupera el URI de redireccionamiento de los detalles del proveedor de autenticación:
```
gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"
```
El comando muestra el URI de redireccionamiento en el campo redirectUrl.
Registra el URI de redireccionamiento con tu aplicación de terceros para obtener el ID de cliente y el secreto del cliente.

Actualiza el proveedor de autenticación con el ID de cliente y el secreto del 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"

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

Agent Identity se basa en el formato de ID SPIFFE estándar de la industria. En las políticas de permisos de IAM, se hace referencia a las identidades de agente con identificadores principales.
Nivel de proyecto (gcloud)

Si otorgas el rol a nivel de 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 acceso a todos los agentes de un proyecto 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"
Nivel de conector (curl)

Para otorgar acceso a un solo agente a un proveedor de autenticación específico, usa la setIamPolicy API. 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 Google Cloud proyecto.
- AUTH_PROVIDER_NAME: Es el nombre del proveedor de autenticación.
- ORGANIZATION_ID: Es el ID de tu Google Cloud organización.
- PROJECT_NUMBER: Es el número del proyecto de Google Cloud .
- LOCATION: Es la ubicación de tu agente (por ejemplo, us-central1).
- ENGINE_ID: Es el ID del motor de razonamiento.

Autentícate en el código de tu agente

Para autenticar tu agente, puedes usar el ADK o llamar directamente a la API de Agent Identity.

ADK

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

# 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

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

# 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

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

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

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

Llama a la API directamente

Si no usas el ADK, tu agente debe llamar a la API de iamconnectorcredentials.retrieveCredentials para obtener el token.

Como se trata de un flujo de OAuth de varios pasos, la API muestra una operación de larga duración (LRO). Tu agente debe controlar el ciclo de vida de la operación:

Solicitud inicial: El agente llama a retrieveCredentials.
Consentimiento obligatorio: Si el usuario no otorgó el consentimiento, la API muestra una LRO en la que los metadatos contienen el auth_uri y un consent_nonce.
Redireccionamiento de frontend: Tu aplicación debe redireccionar al usuario al auth_uri.
Finalización: Después de que el usuario otorgue el consentimiento, llama a FinalizeCredential con el consent_nonce para completar el flujo y obtener el token.

Actualiza tu aplicación del cliente

Para controlar el acceso y el redireccionamiento del usuario para OAuth de 3 segmentos, tu aplicación del cliente debe implementar los siguientes pasos para administrar el consentimiento del usuario y reanudar la conversación:

Controla el activador de autorización.
Implementa un extremo de validación de usuario.
Reanuda la conversación del agente.

Para obtener un ejemplo de implementación completo, consulta la muestra de frontend ValidateUserId.

Controla el activador de autorización

Cuando un agente necesita el consentimiento del usuario, muestra una llamada a función adk_request_credential. Tu aplicación debe interceptar esta llamada para iniciar un diálogo o redireccionamiento de autorización del usuario.

Administra el contexto de la sesión registrando el consent_nonce que proporciona el proveedor de autenticación. Este nonce es necesario para verificar al usuario durante el paso de validación. Guarda el auth_config y el auth_request_function_call_id dentro de la sesión para facilitar la reanudación del flujo después de que se otorgue el consentimiento.

if (auth_request_function_call := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(auth_request_function_call)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, auth_provider_name, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = auth_request_function_call.get('id') if isinstance(auth_request_function_call, dict) else getattr(auth_request_function_call, 'id', None)
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    if auth_config.exchanged_auth_credential and auth_config.exchanged_auth_credential.oauth2:
        oauth2 = auth_config.exchanged_auth_credential.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Implementa un extremo de validación de usuario

Implementa un extremo de validación en tu servidor web (el mismo URI que se proporciona como continue_uri durante la configuración). Este extremo debe hacer lo siguiente:

Recibir user_id_validation_state y auth_provider_name como parámetros de consulta.
Recuperar el user_id y el consent_nonce del contexto de la sesión.
Llamar a la API de FinalizeCredentials del proveedor de autenticación con estos parámetros.
Cerrar la ventana de autorización cuando se reciba una respuesta exitosa.

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
  auth_provider_name = request.query_params.get("auth_provider_name")
  session_id = request.cookies.get("session_id")
  session = consent_sessions.get(session_id, {})

  payload = {
      "userId": session.get("user_id"),
      "userIdValidationState": request.query_params.get(
          "user_id_validation_state"
      ),
      "consentNonce": session.get("consent_nonce"),
  }

  finalize_url = f"https://iamconnectorcredentials.googleapis.com/v1alpha/{auth_provider_name}/credentials:finalize"

  try:
    async with httpx.AsyncClient(timeout=30.0) as client:
      resp = await client.post(finalize_url, json=payload)
      resp.raise_for_status()
  except httpx.HTTPError as e:
    err_text = e.response.text if hasattr(e, "response") else str(e)
    status = e.response.status_code if hasattr(e, "response") else 500
    return HTMLResponse(err_text, status_code=status)

  return HTMLResponse("""
      <script>
          window.close();
      </script>
      <p>Success. You can close this window.</p>
  """)

Reanuda la conversación del agente

Después de que el usuario otorgue el consentimiento y se cierre la ventana de autorización, recupera el auth_config y el auth_request_function_call_id de los datos de tu sesión. Para continuar la conversación, incluye estos detalles en una solicitud nueva al agente como un function_response.

if request.is_auth_resume and session.auth_request_function_call_id and session.auth_config:
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

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