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

Console

1. En la consola de Cloud de Confiance , ve a la página Registro de agentes.

   Ir al registro de agentes

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 add 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 Tipo de OAuth, selecciona OAuth (2 segmentos) .
7. Haz clic en Crear y continuar.
8. Para otorgar permiso a la identidad de tu agente para que use 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 Proveedores de autenticación.

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 autenticació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 el 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 de tu 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 Cloud de Confiance .
• LOCATION: Es la ubicación en la que se implementan el proveedor de autenticación y el 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 de Cloud de Confiance .
• PROJECT_NUMBER: Es el número del proyecto de Cloud de Confiance .
• ENGINE_ID: Es el ID de tu agente del motor de razonamiento implementado.
• USER_EMAIL: Es la dirección de correo electrónico de tu cuenta de usuario personal.

REST

1. Crea el proveedor de autenticación:

   El método authProviders.create de la API de Agent Identity crea un proveedor de autenticación de OAuth de 2 segmentos en un proyecto y una ubicación.

   Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

   • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance . Los IDs de proyecto son cadenas alfanuméricas, como my-project.
   • LOCATION: Es la ubicación en la que se implementan el proveedor de autenticación y el agente (por ejemplo, us-west1).
   • AUTH_PROVIDER_NAME: Es el nombre de tu proveedor de autenticación (por ejemplo, jira-mcp-2lo-authprovider). 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.
   • 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).

   Método HTTP y URL:

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME

   Cuerpo JSON de la solicitud:

   {
     "authProviderTypeParams": {
       "twoLeggedOauth": {
         "clientId": "CLIENT_ID",
         "clientSecret": "CLIENT_SECRET",
         "tokenUrl": "TOKEN_URL"
       }
     }
   }
   

   Para enviar tu solicitud, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME"

   PowerShell (Windows)

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders?authProviderId=AUTH_PROVIDER_NAME" | Select-Object -Expand Content

   Explorador de APIs (navegador)

   Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

   {
     "name": "projects/my-project/locations/us-west1/authProviders/jira-mcp-2lo-authprovider",
     "createTime": "2026-04-03T21:15:41.367155Z",
     "updateTime": "2026-04-03T21:15:41.367155Z",
     "authProviderTypeParams": {
       "twoLeggedOauth": {
         "clientId": "my-oauth-client-id",
         "tokenUrl": "https://oauth2.googleapis.com/token"
       }
     },
     "state": "ENABLED"
   }
   

2. Para permitir que el agente implementado y tu cuenta de usuario personal recuperen credenciales del proveedor de autenticación, otorga el rol de usuario de identidad del agente (roles/agentidentity.user) en el recurso del proveedor de autenticación:

   El método authProviders.setIamPolicy de la API de Agent Identity establece la política de permisos en el recurso del proveedor de autenticación.

   Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

   • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance . Los IDs de proyecto son cadenas alfanuméricas, como my-project.
   • LOCATION: Es la ubicación en la que se implementan el proveedor de autenticación y el agente (por ejemplo, us-west1).
   • AUTH_PROVIDER_NAME: Es el nombre de tu proveedor de autenticación.
   • ORGANIZATION_ID: Es el ID de organización de Cloud de Confiance.
   • PROJECT_NUMBER: Es el número de proyecto numérico de Cloud de Confiance en el que se implementa tu agente (por ejemplo, 987654321098).
   • 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.

   Método HTTP y URL:

   POST https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy

   Cuerpo JSON de la solicitud:

   {
     "policy": {
       "bindings": [
         {
           "role": "roles/agentidentity.user",
           "members": [
             "principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID",
             "user:USER_EMAIL"
           ]
         }
       ]
     }
   }
   

   Para enviar tu solicitud, expande una de estas opciones:

   curl (Linux, macOS o Cloud Shell)

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy"

   PowerShell (Windows)

   Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method POST `
       -Headers $headers `
       -ContentType: "application/json; charset=utf-8" `
       -InFile request.json `
       -Uri "https://agentidentity.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME:setIamPolicy" | Select-Object -Expand Content

   Explorador de APIs (navegador)

   Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de API se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

   Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

   {
     "version": 1,
     "etag": "BwYKmjvelug=",
     "bindings": [
       {
         "role": "roles/agentidentity.user",
         "members": [
           "principal://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/987654321098/locations/us-west1/reasoningEngines/112233445566778899",
           "user:alex@example.com"
         ]
       }
     ]
   }
   

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 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 Cloud de Confiance 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 autenticación en el código de tu agente con el conjunto de herramientas de MCP del registro de agentes en el ADK.

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

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 Cloud de Confiance 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],
)

  

Agent CLI

Si usas el Kit de desarrollo de agentes (ADK) y la CLI de agentes, haz lo siguiente para implementar tu agente con la identidad de 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: Es el nombre de la carpeta de la aplicación del agente (por ejemplo, maps_agent).
   • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance.
   • 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 manera programática con el SDK de Vertex AI para Python, usa la marca identity_type=AGENT_IDENTITY:

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 del proyecto de Cloud de Confiance .
• LOCATION: Es la región admitida en la que deseas implementar el agente (por ejemplo, us-west1).