Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

Los proveedores de autorización de OAuth de 3 segmentos administran el redireccionamiento de usuarios y los tokens 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.

Mensaje 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 un almacén de credenciales administrado 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 indicaciones de acceso del usuario y el redireccionamiento 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 autenticación 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, 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 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, 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 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 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 (3 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.
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 Auth Providers.

Google Cloud CLI

Crea el proveedor de autenticación con URLs de autorización y de tokens:

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

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

Dado que se trata de un flujo de OAuth de varios pasos, la API devuelve 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.
Se requiere consentimiento: Si el usuario no otorgó su consentimiento, la API devuelve un LRO en el que los metadatos contienen el objeto auth_uri y un objeto consent_nonce.
Redireccionamiento de frontend: Tu aplicación debe redireccionar al usuario a auth_uri.
Finalización: Después de que el usuario otorga su consentimiento, llama a FinalizeCredential con 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 usuarios
Reanuda la conversación con el agente

Para ver un ejemplo de implementación completo, consulta el ejemplo de ValidateUserId para el frontend.

Cómo controlar el activador de autorización

Cuando un agente necesita el consentimiento del usuario, devuelve 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 proporcionado por el proveedor de autenticación. Este nonce es obligatorio para verificar al usuario durante el paso de validación. Guarda auth_config y 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 usuarios

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

Recibe user_id_validation_state y auth_provider_name como parámetros de consulta.
Recupera user_id y consent_nonce del contexto de la sesión.
Llama a la API de FinalizeCredentials del proveedor de autenticación con estos parámetros.
Cierra la ventana de autorización cuando recibas una respuesta de procesamiento correcto.

@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 con el agente

Después de que el usuario otorgue su consentimiento y se cierre la ventana de autorización, recupera auth_config y auth_request_function_call_id de los datos de tu sesión. Para continuar la conversación, incluye estos detalles en una nueva solicitud al agente como un objeto 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 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]"],
    },
)