Eseguire l'autenticazione utilizzando OAuth a due vie con Auth Manager

Per consentire agli agenti di autenticarsi a strumenti esterni come ServiceNow o Salesforce utilizzando la propria autorità, configura l'autenticazione in uscita utilizzando i provider di autenticazione OAuth a due vie (credenziali client) in Agent Identity Auth Manager.

Gestendo le credenziali e i token, i provider di autenticazione OAuth a due vie eliminano la necessità di codice personalizzato per gestire i flussi di autenticazione

Flusso di lavoro OAuth a due vie

I provider di autenticazione OAuth a due vie utilizzano l'identità dell'agente e non richiedono il consenso dell'utente. Google gestisce l'archiviazione delle credenziali client. Quando utilizzi l'Agent Development Kit (ADK), recupera e inserisce automaticamente i token di accesso risultanti nelle intestazioni di chiamata dello strumento.

Prima di iniziare

  1. Verifica di aver scelto il metodo di autenticazione corretto.

  2. Abilita l'API Agent Identity.

    Ruoli necessari per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

  3. Crea ed esegui il deployment di un agente.

  4. Ottieni l'ID client e il client secret dall'applicazione di terze parti a cui vuoi connetterti.

  5. Verifica di disporre dei ruoli necessari per completare questa attività.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e utilizzare un provider di autenticazione Agent Identity a due vie, chiedi all'amministratore di concederti i seguenti ruoli IAM per il progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per creare e utilizzare un provider di autenticazione Agent Identity a due vie. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per creare e utilizzare un provider di autenticazione Agent Identity a due vie sono necessarie le seguenti autorizzazioni:

  • Per creare provider di autenticazione: agentidentity.authProviders.create
  • Per utilizzare i provider di autenticazione:
    • agentidentity.authProviders.retrieveCredentials
    • aiplatform.endpoints.predict
    • aiplatform.sessions.create

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Creare un provider di autenticazione a due vie

Crea un provider di autenticazione per definire la configurazione e le credenziali per le applicazioni di terze parti.

Per creare un provider di autenticazione a due vie, utilizza gcloud CLI:

  1. Crea il provider di autenticazione:

    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 che il provider di autenticazione sia visualizzato nell'elenco e che il suo stato sia ENABLED: 
    gcloud alpha agent-identity authProviders list \
   --project="PROJECT_ID" \
   --location="LOCATION"

  3. Concedi le autorizzazioni di accesso per consentire all'agente e all'ambiente di sviluppo locale di recuperare le credenziali dal provider di autenticazione. Per consentire all'agente di cui hai eseguito il deployment e al tuo account utente personale di accedere al provider di autenticazione, concedi il ruolo Utente Agent Identity (roles/agentidentity.user) alla risorsa del provider di autenticazione:

    1. Concedi l'accesso all'ID SPIFFE dell'agente di cui hai eseguito il deployment (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. Concedi l'accesso al tuo account utente personale per lo sviluppo e il test locali (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"

Sostituisci quanto segue:

  • PROJECT_ID: l' Google Cloud ID progetto.
  • LOCATION: la località in cui sono stati eseguiti il deployment del provider di autenticazione e dell'agente (ad esempio, us-west1).
  • AUTH_PROVIDER_NAME: il nome del provider di autenticazione (ad esempio, bigquery-mcp-3lo-authprovider).
  • AUTHORIZATION_URL: l'URL del server di autorizzazione (ad esempio, https://accounts.google.com/o/oauth2/v2/auth).
  • TOKEN_URL: l'URL del server di token (ad esempio, https://oauth2.googleapis.com/token).
  • CLIENT_ID: l'ID client OAuth generato dal servizio di terze parti.
  • CLIENT_SECRET: il client secret OAuth generato dal servizio di terze parti.
  • ORGANIZATION_ID: l' Google Cloud ID organizzazione.
  • PROJECT_NUMBER: il Google Cloud numero di progetto.
  • ENGINE_ID: l'ID dell'agente del motore di ragionamento di cui hai eseguito il deployment.
  • USER_EMAIL: l'indirizzo email del tuo account utente personale.

Autenticarsi nel codice dell'agente

Per autenticare l'agente, puoi utilizzare l'ADK.

ADK

Fai riferimento al provider di autenticazione nel codice dell'agente utilizzando il set di strumenti MCP nell'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

Fai riferimento al provider di autenticazione nel codice dell'agente utilizzando uno strumento di funzione autenticata nell'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

Fai riferimento al provider di autenticazione nel codice dell'agente utilizzando il set di strumenti MCP del registro degli agenti nell'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],
)

Installare le dipendenze per i test locali

Per testare l'agente localmente in un ambiente virtuale, installa le seguenti dipendenze necessarie:

  1. Crea e attiva un ambiente virtuale: 
    python3 -m venv env
source env/bin/activate
  2. Installa i pacchetti richiesti: 
    pip install google-cloud-aiplatform[agent_engines,adk] google-adk[agent-identity]

Eseguire il deployment dell'agente

Quando esegui il deployment dell'agente su Google Cloud, assicurati che Agent Identity sia abilitato.

Se esegui il deployment in Agent Runtime su Gemini Enterprise Agent Platform , utilizza il identity_type=AGENT_IDENTITY flag:

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

Passaggi successivi