Autenticarsi utilizzando OAuth a tre vie con Auth Manager

Per concedere al tuo agente l'accesso a strumenti e servizi esterni (come attività Jira o repository GitHub) per conto di un utente finale specifico, configura un provider di autenticazione OAuth a tre vie nel gestore di autenticazione di identità dell'agente.

I provider di autenticazione OAuth a tre vie gestiscono per te il reindirizzamento degli utenti e i token. In questo modo non è necessario scrivere codice personalizzato per gestire flussi OAuth 2.0 complessi.

Flusso di lavoro OAuth a tre vie

I provider di autenticazione OAuth a tre vie richiedono il consenso dell'utente perché l'agente accede alle risorse per suo conto.

1. Prompt e reindirizzamento: l'interfaccia di chat chiede all'utente di accedere e poi lo reindirizza alla pagina di consenso dell'applicazione di terze parti.
2. Consenso e archiviazione: dopo che l'utente ha concesso l'autorizzazione, Agent Identity auth manager archivia i token OAuth risultanti in un vault delle credenziali gestito da Google.
3. Inserimento: quando utilizzi Agent Development Kit (ADK), l'agente recupera automaticamente il token dal fornitore di autenticazione e lo inserisce 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 Connector.

   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. Assicurati di avere un'applicazione frontend per gestire le richieste di accesso degli utenti e il reindirizzamento alle pagine di consenso di terze parti.
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 a tre passaggi, chiedi all'amministratore di concederti i seguenti ruoli IAM per il progetto:

• Per creare provider di autenticazione:
  • Amministratore connettore IAM (roles/iamconnectors.admin)
  • Editor connettore IAM (roles/iamconnectors.editor)
• Per utilizzare i provider di autenticazione:
  • IAM Connector User (roles/iamconnectors.user)
  • Utente Vertex AI (roles/aiplatform.user)
  • Consumer Service Usage (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 a tre vie. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

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

Crea un provider di autenticazione a tre passaggi

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

Per creare un provider di autenticazione a tre passaggi, utilizza la console Google Cloud o Google Cloud CLI.

Configura l'applicazione client OAuth

Prima di registrare le credenziali del client OAuth, ottieni un ID client e un client secret dal server di autorizzazione di terze parti (ad esempio Google, GitHub o Jira).

Se ti connetti a un servizio di terze parti al di fuori di Google Cloud, ottieni le credenziali del client OAuth dal portale per sviluppatori del servizio e salta i passaggi di questa sezione.

Registra l'URI di reindirizzamento

Quando configuri le credenziali client OAuth, devi registrare l'URI di reindirizzamento di callback dedicato del provider di autenticazione.

1. Costruisci l'URI di reindirizzamento utilizzando il seguente modello:

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

   Sostituisci quanto segue:

   • PROJECT_ID: l'ID progetto Google Cloud .
   • LOCATION: The region where your auth provider will be deployed (for example,us-west1`).
   • CONNECTOR_NAME: il nome del tuo fornitore di autenticazione.

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

2. Se ti connetti a servizi Google Cloud (come BigQuery), puoi configurare la schermata per il consenso e creare credenziali client OAuth nella console Google Cloud :

   1. Configura la schermata per il consenso OAuth:

      1. Nella console Google Cloud , vai alla pagina API e servizi >Schermata consenso OAuth.

         Vai ad API e servizi >Schermata consenso OAuth

      2. Nella sezione Informazioni sull'app, inserisci un nome dell'applicazione (ad esempio BigQuery Manager Application) e un'email di assistenza.
      3. Nella sezione Pubblico, seleziona Interno o Esterno.
      4. Inserisci i tuoi dati di contatto per ricevere le notifiche.
      5. Leggi e accetta le Norme relative ai dati utente dei servizi API di Google.
      6. Fai clic su Fine.

   2. Crea le credenziali client OAuth:

      1. Nella console Google Cloud , vai alla pagina API e servizi >Schermata consenso OAuth >Client.

         Vai ad API e servizi >Schermata consenso OAuth >Client

      2. Fai clic su Crea credenziali >ID client OAuth.
      3. Seleziona l'opzione Applicazione web dall'elenco.
      4. Inserisci un nome riconoscibile per il tuo client OAuth.
      5. Nella sezione URI di reindirizzamento autorizzati, fai clic su Aggiungi URI e inserisci l'URI di reindirizzamento creato.
      6. Fai clic su Crea. Nella finestra di dialogo Client OAuth creato, copia i valori generati per ID client e Client secret.

Autenticarsi nel codice agente

Per autenticare l'agente, puoi utilizzare l'ADK o chiamare direttamente l'API 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
from google.genai import types

_, project_id = google.auth.default()
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

bigquery_mcp_auth_provider_id = "AUTH_PROVIDER_NAME"
bigquery_mcp_endpoint = os.environ.get(
    "BIGQUERY_MCP_ENDPOINT", "https://bigquery.googleapis.com/mcp"
)

# Register Google Cloud auth provider for Agent Identity Credentials service
CredentialManager.register_auth_provider(GcpAuthProvider())

# The URI to redirect the user to after consent is granted and the callback is received.
CONTINUE_URI = "http://127.0.0.1:8501/validateUserId"

bigquery_mcp_auth_scheme = GcpAuthProviderScheme(
    name=f"projects/{project_id}/locations/LOCATION/connectors/{bigquery_mcp_auth_provider_id}",
    scopes=["https://www.googleapis.com/auth/bigquery"],
    continue_uri=CONTINUE_URI,
)

bigquery_mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(url