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

Per consentire agli agenti di autenticarsi con strumenti esterni come ServiceNow o Salesforce utilizzando la propria autorità, configura l'autenticazione in uscita utilizzando i provider di autenticazione OAuth a due vie (Client Credentials) nel gestore di autenticazione di Agent Identity.

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 2 passaggi 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), questo 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, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). 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 nel 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 dell'identità dell'agente 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 fasi 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.

Crea 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 la console Cloud de Confiance , Google Cloud CLI o l'API REST.

Console

  1. Nella console Cloud de Confiance , vai alla pagina Agent Registry.

    Vai ad Agent Registry

  2. Fai clic sul nome dell'agente per cui vuoi creare un provider di autenticazione.
  3. Fai clic su Identità.
  4. Nella sezione Provider di autenticazione, fai clic su Aggiungi provider di autenticazione.

  5. Nel riquadro Aggiungi provider di autenticazione, inserisci un nome e una descrizione.

    Il nome può contenere solo lettere minuscole, numeri o trattini, non può terminare con un trattino e deve iniziare con una lettera minuscola.

  6. Nell'elenco OAuth Type (Tipo di OAuth), seleziona OAuth (2 legged) (OAuth a due parti).
  7. Fai clic su Crea e continua.
  8. Per concedere all'identità dell'agente l'autorizzazione a utilizzare il provider di autenticazione, fai clic su Concedi accesso.

    Questo processo assegna automaticamente il ruolo Utente identità agente (roles/agentidentity.user) all'identità agente sulla risorsa del provider di autenticazione.

  9. Nella sezione Credenziali del provider di autenticazione, inserisci le seguenti informazioni:
    • ID client
    • Client secret
    • URL del token
  10. Fai clic su Aggiungi configurazione provider.

Il provider di autenticazione appena creato viene visualizzato nell'elenco Provider di autenticazione.

gcloud CLI

  1. Crea il provider di autenticazione:

    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 che il tuo provider di autenticazione sia visualizzato nell'elenco e che il suo stato sia ENABLED: 
    gcloud agent-identity auth-providers 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 è stato eseguito il deployment e al tuo account utente personale di accedere al provider di autenticazione, concedi il ruolo Utente identità agente (roles/agentidentity.user) alla risorsa del provider di autenticazione:

    1. Concedi l'accesso all'ID SPIFFE dell'agente di cui è stato eseguito il deployment (Agent Identity):

      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. Concedi l'accesso al tuo account utente personale per lo sviluppo e i test locali (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"

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Cloud de Confiance .
  • LOCATION: la località in cui è stato eseguito il deployment del provider di autenticazione e dell'agente (ad esempio, us-west1).
  • AUTH_PROVIDER_NAME: il nome del provider di autenticazione (ad esempio, jira-mcp-2lo-authprovider).
  • CLIENT_ID: l'ID client OAuth generato dal servizio di terze parti.
  • CLIENT_SECRET: il client secret OAuth generato dal servizio di terze parti.
  • TOKEN_URL: l'URL del server token (ad esempio https://oauth2.googleapis.com/token).
  • ORGANIZATION_ID: il tuo ID organizzazione Cloud de Confiance .
  • PROJECT_NUMBER: il tuo numero di progetto Cloud de Confiance .
  • ENGINE_ID: l'ID dell'agente del motore di ragionamento di cui è stato eseguito il deployment.
  • USER_EMAIL: l'indirizzo email del tuo account utente personale.

REST

  1. Crea il provider di autenticazione:

    Il metodo authProviders.create dell'API Agent Identity crea un provider di autenticazione OAuth 2-legged in un progetto e in una località.

    Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

    • PROJECT_ID: l'ID progetto Cloud de Confiance . Gli ID progetto sono stringhe alfanumeriche, come my-project.
    • LOCATION: la località in cui è stato eseguito il deployment del provider di autenticazione e dell'agente (ad esempio, us-west1).
    • AUTH_PROVIDER_NAME: il nome del provider di autenticazione (ad esempio jira-mcp-2lo-authprovider). Il nome può contenere solo lettere minuscole, numeri o trattini, non può terminare con un trattino e deve iniziare con una lettera minuscola.
    • CLIENT_ID: l'ID client OAuth che hai generato dal servizio di terze parti.
    • CLIENT_SECRET: il client secret OAuth che hai generato dal servizio di terze parti.
    • TOKEN_URL: l'URL del server token (ad esempio, https://oauth2.googleapis.com/token).

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

    {
  "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. Per consentire all'agente di cui è stato eseguito il deployment e al tuo account utente personale di recuperare le credenziali dal provider di autenticazione, concedi il ruolo Agent Identity User (roles/agentidentity.user) sulla risorsa del provider di autenticazione:

    Il metodo authProviders.setIamPolicy dell'API Agent Identity imposta la policy di autorizzazione sulla risorsa del provider di autenticazione.

    Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

    • PROJECT_ID: l'ID progetto Cloud de Confiance . Gli ID progetto sono stringhe alfanumeriche, come my-project.
    • LOCATION: la località in cui è stato eseguito il deployment del provider di autenticazione e dell'agente (ad esempio, us-west1).
    • AUTH_PROVIDER_NAME: il nome del provider di autenticazione.
    • ORGANIZATION_ID: il tuo ID organizzazione Cloud de Confiance.
    • PROJECT_NUMBER: il numero di progetto Cloud de Confiance numerico del progetto in cui è stato eseguito il deployment dell'agente (ad esempio, 987654321098).
    • ENGINE_ID: l'ID dell'agente del motore di ragionamento di cui è stato eseguito il deployment.
    • USER_EMAIL: l'indirizzo email del tuo account utente personale.

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

    {
  "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"
        ]
      }
    ]
  }
}

    Per inviare la richiesta, espandi una di queste opzioni:

    Dovresti ricevere una risposta JSON simile alla seguente:

    {
  "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"
      ]
    }
  ]
}

Autenticati 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 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

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

Fai riferimento al provider di autenticazione nel codice dell'agente utilizzando il set di strumenti MCP del registry degli agenti nell'ADK.

Non devi creare uno schema di autenticazione per questo flusso. Il binding in uscita del server MCP registra già quale provider di autenticazione utilizzare.

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

Installa 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]

Esegui il deployment dell'agente

Quando esegui il deployment dell'agente in Cloud de Confiance by S3NS, assicurati che l'identità dell'agente sia abilitata.

Agent CLI

Se utilizzi l'Agent Development Kit (ADK) e l'interfaccia a riga di comando dell'agente, segui questi passaggi per eseguire il deployment dell'agente con l'identità dell'agente abilitata:

  1. Nella cartella dell'applicazione dell'agente, crea un file di configurazione denominato .agent_engine_config.json per abilitare l'identità dell'agente:

    echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json

  2. Esegui il deployment dell'agente in Agent Runtime su Gemini Enterprise Agent Platform:

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    Sostituisci quanto segue:

    • AGENT_NAME: il nome della cartella dell'applicazione dell'agente (ad esempio, maps_agent).
    • PROJECT_ID: il tuo ID progetto Cloud de Confiance.
    • LOCATION: la regione supportata in cui vuoi eseguire il deployment dell'agente (ad esempio, us-west1).

SDK Python

Se esegui il deployment in modo programmatico utilizzando l'SDK Vertex AI per Python, utilizza il flag 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",
        ],
    },
)

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto Cloud de Confiance .
  • LOCATION: la regione supportata in cui vuoi eseguire il deployment dell'agente (ad esempio, us-west1).

Passaggi successivi