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

Per consentire agli agenti di autenticarsi su strumenti esterni come ServiceNow o Salesforce utilizzando la propria autorità, configura l'autenticazione in uscita utilizzando provider di autenticazione OAuth a due vie (credenziali client) in Gestore autenticazione identità agente.

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.

Importante:questo documento mostra come eseguire l'autenticazione utilizzando l'API Agent Identity. Ti consigliamo di utilizzare l'API Agent Identity perché l'API IAM Connectors (anteprima) non sarà disponibile a livello generale. Se utilizzi l'API IAM Connectors, esegui la migrazione all'API Agent Identity.

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 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 richiesti per abilitare le API

   Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (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 chiamate, chiedi all'amministratore di concederti i seguenti ruoli IAM per il progetto:

• Per creare provider di autenticazione:
  • Amministratore identità agente (roles/agentidentity.admin)
  • Agent Identity Editor (roles/agentidentity.editor)
• Per utilizzare i provider di autenticazione:
  • Utente identità agente (roles/agentidentity.user)
  • Accesso predefinito agente (roles/aiplatform.agentDefaultAccess)
  • Editor contesto agente (roles/aiplatform.agentContextEditor)
  • Utente Vertex AI (roles/aiplatform.user)
  • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

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 passaggi, utilizza la console Google Cloud o Google Cloud CLI.

Console

1. Nella console Google Cloud , vai alla pagina Registro degli agenti.

   Vai a 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 fornitore 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) .
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à dell'agente nella 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 del fornitore.

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 fornitore di autenticazione sia presente 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) nella risorsa del provider di autenticazione:

   1. Concedi l'accesso all'ID SPIFFE dell'agente di cui è stato eseguito il deployment (identità dell'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. 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 Google Cloud .
• LOCATION: la località in cui vengono implementati il provider di autenticazione e l'agente (ad esempio, us-west1).
• AUTH_PROVIDER_NAME: il nome del tuo fornitore 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 dei token (ad esempio, https://oauth2.googleapis.com/token).
• ORGANIZATION_ID: l'ID della tua organizzazione Google Cloud .
• PROJECT_NUMBER: il tuo Google Cloud numero di progetto.
• 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.

Autenticarsi nel codice agente

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

Nota: gli esempi seguenti registrano il provider di autenticazione a livello di modulo, il che funziona quando esegui l'agente localmente o lo esegui il deployment con la CLI dell'agente. Se esegui il deployment con l'SDK Vertex AI Python, registra il fornitore di autenticazione in set_up() in modo che venga eseguito nel container di cui è stato eseguito il deployment. Per saperne di più, consulta Eseguire il deployment dell'agente.

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 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 = 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 dell'Agent Registry nell'ADK.

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

Attenzione:utilizza la stessa regione per il provider di autenticazione, il server MCP e il client Agent Registry. I fornitori di autenticazione non sono disponibili nella posizione global, quindi se imposti location="global", la creazione del binding in uscita non riesce e viene visualizzato l'errore Location of auth provider does not match location of binding.

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 Google Cloud 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 su Google Cloud, 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, procedi come segue per eseguire il deployment dell'agente con Agent Identity abilitata:

1. Nella cartella dell'applicazione dell'agente, crea un file di configurazione denominato .agent_engine_config.json per attivare 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 Google Cloud.
   • 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 Python, utilizza il flag identity_type=AGENT_IDENTITY:

Attenzione:l'SDK serializza l'oggetto app, quindi la chiamata CredentialManager.register_auth_provider() eseguita dallo script locale al momento dell'importazione non viene eseguita nel contenitore di cui è stato eseguito il deployment. Registra invece il fornitore di autenticazione nel metodo set_up() della tua app, che il runtime chiama all'avvio del container. In caso contrario, l'agente non riesce a eseguire la query e restituisce No auth provider registered for custom auth scheme 'gcpAuthProviderScheme'. Per ulteriori informazioni, vedi Considerazioni sull'implementazione.

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: il tuo ID progetto Google Cloud .
• LOCATION: la regione supportata in cui vuoi eseguire il deployment dell'agente (ad esempio, us-west1).

Passaggi successivi

• Panoramica di Agent Identity
• Eseguire l'autenticazione utilizzando OAuth a tre vie con Auth Manager
• Autenticati utilizzando la chiave API con Auth Manager
• Gestire i provider di autenticazione di Agent Identity
• Risolvere i problemi relativi al gestore di autenticazione di Agent Identity