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

Para otorgar a tu agente acceso a herramientas y servicios externos (como tareas de Jira o repositorios de GitHub) en nombre de un usuario final específico, configura 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 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.

1. 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.
2. Consentimiento y almacenamiento: Después de que el usuario otorga permiso, el administrador de autenticación de Agent Identity almacena los tokens de OAuth resultantes en un almacén de credenciales administrado por Google.
3. 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

1. Verifica que hayas elegido el método de autenticación correcto.

2. Habilita la API de Agent Identity Connector.

   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. 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.
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 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)
  • 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:

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 la Google Cloud CLI.

Configura tu aplicación cliente de OAuth

Antes de registrar tus credenciales de cliente de OAuth, obtén un ID de cliente y un secreto del cliente del servidor de autorización de terceros (por ejemplo, Google, GitHub o Jira).

Si te conectas a un servicio de terceros fuera de Google Cloud, obtén las credenciales de cliente de OAuth del portal para desarrolladores de ese servicio y omite los pasos de esta sección.

Registra el URI de redireccionamiento

Cuando configures tus credenciales de cliente de OAuth, debes registrar el URI de redireccionamiento de devolución de llamada dedicado del proveedor de autenticación.

1. Construye el URI de redireccionamiento con la siguiente plantilla:

   https://iamconnectorcredentials.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/connectors/CONNECTOR_NAME/oauthcallback

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del Google Cloud proyecto de.
   • LOCATION: The region where your auth provider will be deployed (for example,us-west1`).
   • CONNECTOR_NAME: Es el nombre de tu proveedor de autenticación.

   Por ejemplo: https://iamconnectorcredentials.googleapis.com/v1/projects/my-project/locations/us-west1/connectors/bigquery-mcp-3lo-authprovider/oauthcallback

2. Si te conectas a Google Cloud servicios (como BigQuery), puedes configurar la pantalla de consentimiento y crear credenciales de cliente de OAuth en la Google Cloud consola:

   1. Configura la pantalla de consentimiento de OAuth:

      1. En la Google Cloud consola, ve a la APIs & Services >Pantalla de consentimiento de OAuth página.

         Ir a APIs & Services >Pantalla de consentimiento de OAuth

      2. En la sección Información de la aplicación, ingresa un nombre de aplicación (como Aplicación del administrador de BigQuery) y un correo electrónico de asistencia.
      3. En la sección Público, selecciona Interno o Externo.
      4. Ingresa tu información de contacto para recibir notificaciones.
      5. Lee y acepta la Política de Datos del Usuario de los Servicios de las APIs de Google Política.
      6. Haz clic en Finalizar.

   2. Crea tus credenciales de cliente de OAuth:

      1. En la Google Cloud consola, ve a la página APIs & Services > Pantalla de consentimiento de OAuth > Clientes.

         Ir a APIs & Services >Pantalla de consentimiento de OAuth >Clientes

      2. Haz clic en Crear credenciales >ID de cliente de OAuth.
      3. Selecciona la opción Aplicación web de la lista.
      4. Ingresa un nombre reconocible para tu cliente de OAuth.
      5. En la sección URIs de redireccionamiento autorizados, haz clic en Agregar URI y, luego, ingresa el URI de redireccionamiento que construiste.
      6. Haz clic en Crear. En el diálogo Se creó el cliente de OAuth, copia los valores generados de Client ID (ID de cliente) y Client Secret (Secreto del cliente).

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.

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="AGENT_NAME",
    model="gemini-2.5-flash",
    instruction="AGENT_INSTRUCTIONS",
    tools=[toolset],
)

import os
from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.models import Gemini
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
import google.auth