Autenticarsi utilizzando OAuth a tre vie con Auth Manager

Se vuoi che il tuo agente acceda a strumenti e servizi esterni (ad esempio, attività Jira o repository GitHub) per conto di un utente specifico, devi configurare 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 il reindirizzamento degli utenti e i token per te. In questo modo non è più 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.

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.
Consenso e archiviazione: dopo che l'utente ha concesso l'autorizzazione, i token OAuth risultanti vengono archiviati in un vault delle credenziali gestito da Google.
Inserimento: quando utilizzi l'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

[Verifica di aver scelto il metodo di autenticazione corretto](/iam/docs/agent-identity-overview#auth-models).
Abilita l'API Agent Identity Connector.
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.
Abilitare l'API
Crea ed esegui il deployment di un agente.
Assicurati di avere un'applicazione frontend per gestire le richieste di accesso degli utenti e il reindirizzamento alle pagine di consenso di terze parti.
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 nel 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)
- Accesso predefinito dell'agente (roles/aiplatform.agentDefaultAccess)
- Editor del contesto dell'agente (roles/aiplatform.agentContextEditor)
- 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:

Autorizzazioni obbligatorie

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

Per creare provider di autenticazione: iamconnectors.connectors.create
Per utilizzare i provider di autenticazione:
- iamconnectors.connectors.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 tre 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 tre passaggi, utilizza la console Google Cloud o Google Cloud CLI.

Console

Nella console Google Cloud , vai alla pagina Registro degli agenti.
Vai al registry degli agenti
Fai clic sul nome dell'agente per cui vuoi creare un provider di autenticazione.
Fai clic su Identità.
Nella sezione Provider di autenticazione, fai clic su Aggiungi provider di autenticazione.
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.
Dall'elenco OAuth Type (Tipo di OAuth), seleziona OAuth (3 legged) (OAuth a tre vie) .
Fai clic su Crea e continua.
Per concedere all'identità dell'agente l'autorizzazione a utilizzare il provider di autenticazione, fai clic su Concedi accesso.
In questo modo, al ruolo Utente connettore (roles/iamconnectors.user) viene assegnata automaticamente l'identità dell'agente nella risorsa del provider di autenticazione.
Copia l'URL di callback.
In una scheda separata, registra l'URL di callback nella tua applicazione di terze parti.
Dalla tua applicazione di terze parti, ottieni l'ID client, il client secret, l'URL token e l'URL di autorizzazione.
Nella sezione Credenziali del provider di autenticazione, inserisci le seguenti informazioni:
- ID client
- Client secret
- URL del token
- URL di autorizzazione
Fai clic su Aggiungi configurazione del fornitore.

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

Google Cloud CLI

Crea il fornitore di autenticazione con gli URL di autorizzazione e token:

gcloud alpha agent-identity connectors create AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-authorization-url="AUTHORIZATION_URL" \
    --three-legged-oauth-token-url="TOKEN_URL"

Recupera l'URI di reindirizzamento dai dettagli del provider di autenticazione:
```
gcloud alpha agent-identity connectors describe AUTH_PROVIDER_NAME \
    --location="LOCATION"
```
Il comando restituisce l'URI di reindirizzamento nel campo redirectUrl.
Registra l'URI di reindirizzamento con l'applicazione di terze parti per ottenere l'ID client e il client secret.

Aggiorna il provider di autenticazione con l'ID client e il client secret:

gcloud alpha agent-identity connectors update AUTH_PROVIDER_NAME \
    --location="LOCATION" \
    --three-legged-oauth-client-id="CLIENT_ID" \
    --three-legged-oauth-client-secret="CLIENT_SECRET"

Per concedere all'identità dell'agente l'autorizzazione a utilizzare i provider di autenticazione, aggiorna la policy di autorizzazione IAM per il progetto o per il provider di autenticazione specifico e concedi il ruolo Utente connettore (roles/iamconnectors.user) all'entità agente.

Agent Identity si basa sul formato dell'ID SPIFFE standard del settore. Nelle policy di autorizzazione IAM, le identità degli agenti vengono indicate utilizzando identificatori di entità.
A livello di progetto (gcloud)

La concessione del ruolo a livello di progetto consente all'agente di utilizzare qualsiasi provider di autenticazione nel progetto.
- Per concedere a un singolo agente l'accesso ai fornitori di autenticazione in un progetto, esegui questo comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"
- Per concedere a tutti gli agenti di un progetto l'accesso ai fornitori di autenticazione, esegui questo comando:
  gcloud projects add-iam-policy-binding PROJECT_ID \ --role='roles/iamconnectors.user' \ --member="principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER"
A livello di connettore (curl)

Per concedere a un singolo agente l'accesso a un fornitore di autenticazione specifico, utilizza l'API setIamPolicy. Questo comando sovrascrive qualsiasi criterio di autorizzazione esistente sulla risorsa.
```
curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
  "policy": {
    "bindings": [
      {
        "role": "roles/iamconnectors.user",
        "members": ["principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID"]
      }
    ]
  }
}' \
    "https://iamconnectors.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME:setIamPolicy"
```
Sostituisci quanto segue:
- PROJECT_ID: l'ID progetto Google Cloud .
- AUTH_PROVIDER_NAME: il nome del fornitore di autenticazione.
- ORGANIZATION_ID: l'ID della tua organizzazione Google Cloud .
- PROJECT_NUMBER: il tuo Google Cloud numero di progetto.
- LOCATION: la posizione dell'agente (ad esempio, us-central1).
- ENGINE_ID: l'ID del motore di ragionamento.

Autenticarsi nel codice agente

Per autenticare l'agente, puoi utilizzare l'ADK o chiamare direttamente l'API Agent Identity.

ADK

Fai riferimento al fornitore 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())

# 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="YOUR_AGENT_NAME",
    model="gemini-2.0-flash",
    instruction="YOUR_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.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())

# The URI to redirect the user to after consent is completed.
CONTINUE_URI = "WEB_APP_VALIDATE_USER_URI"

# Create Auth Config
spotify_auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
        continue_uri=CONTINUE_URI
    )
)

# 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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[spotify_search_track_tool],
)

app = App(
    name="YOUR_APP_NAME",
    root_agent=agent,
)

vertex_app = agent_engines.AdkApp(app_name=app)

ADK

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

# The URI to redirect the user to after consent is completed.
CONTINUE_URI="WEB_APP_VALIDATE_USER_URI"

# Create Google Cloud auth provider by providing auth provider full resource name
auth_scheme=GcpAuthProviderScheme(
name="projects/GOOGLE_PROJECT/locations/LOCATION/connectors/AUTH_PROVIDER_NAME",
continue_uri=CONTINUE_URI)

# Set Agent Registry
registry = AgentRegistry(project_id="GOOGLE_PROJECT", location="global")

toolset = registry.get_mcp_toolset(mcp_server_name="projects/GOOGLE_PROJECT/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="YOUR_AGENT_NAME",
    model="YOUR_MODEL_NAME",
    instruction="YOUR_AGENT_INSTRUCTIONS",
    tools=[toolset],
)

Chiama direttamente l'API

Se non utilizzi l'ADK, l'agente deve chiamare l'API iamconnectorcredentials.retrieveCredentials per ottenere il token.

Poiché si tratta di un flusso OAuth in più passaggi, l'API restituisce un'operazione a lunga esecuzione (LRO). L'agente deve gestire il ciclo di vita dell'operazione:

Richiesta iniziale: l'agente chiama retrieveCredentials.
Consenso richiesto: se l'utente non ha concesso il consenso, l'API restituisce un LRO in cui i metadati contengono auth_uri e un consent_nonce.
Reindirizzamento frontend: la tua applicazione deve reindirizzare l'utente a auth_uri.
Completamento: dopo che l'utente ha concesso il consenso, chiama FinalizeCredential utilizzando consent_nonce per completare il flusso e ottenere il token.

Aggiornare l'applicazione lato client

Per gestire l'accesso e il reindirizzamento degli utenti per OAuth a tre passaggi, l'applicazione lato client deve implementare i seguenti passaggi per gestire il consenso dell'utente e riprendere la conversazione:

Gestire l'attivazione dell'autorizzazione
Implementare un endpoint di convalida degli utenti
Riprendere la conversazione con l'agente

Per un esempio di implementazione completo, consulta la pagina ValidateUserId frontend sample.

Gestire l'attivazione dell'autorizzazione

Quando un agente ha bisogno del consenso dell'utente, restituisce una chiamata di funzione adk_request_credential. La tua applicazione deve intercettare questa chiamata per avviare una finestra di dialogo o un reindirizzamento per l'autorizzazione dell'utente.

Gestisci il contesto della sessione registrando consent_nonce fornito dal provider di autenticazione. Questo nonce è necessario per verificare l'utente durante il passaggio di convalida. Salva auth_config e auth_request_function_call_id all'interno della sessione per facilitare la ripresa del flusso dopo la concessione del consenso.

if (auth_request_function_call := get_auth_request_function_call(event_data)):
    print("--> Authentication required by agent.")
    try:
        auth_config = get_auth_config(auth_request_function_call)
        auth_uri, consent_nonce = handle_adk_request_credential(
            auth_config, auth_provider_name, request.user_id
        )
        if auth_uri:
            event_data['popup_auth_uri'] = auth_uri
            fc_id = auth_request_function_call.get('id') if isinstance(auth_request_function_call, dict) else getattr(auth_request_function_call, 'id', None)
            event_data['auth_request_function_call_id'] = fc_id
            event_data['auth_config'] = auth_config.model_dump()

            # Store session state
            if session_id:
                consent_sessions[session_id] = {
                    "user_id": request.user_id,
                    "consent_nonce": consent_nonce
                }
    except Exception as e:
        print(f"Error handling adk_request_credential: {e}")
        # Optionally, add logic to inform the user about the error.

def handle_adk_request_credential(auth_config, auth_provider_name, user_id):
    if auth_config.exchanged_auth_credential and auth_config.exchanged_auth_credential.oauth2:
        oauth2 = auth_config.exchanged_auth_credential.oauth2
        return oauth2.auth_uri, oauth2.nonce
    return None, None

Implementare un endpoint di convalida utente

Implementa un endpoint di convalida sul tuo server web (lo stesso URI fornito come continue_uri durante la configurazione). Questo endpoint deve:

Ricevi user_id_validation_state e auth_provider_name come parametri di ricerca.
Recupera user_id e consent_nonce dal contesto della sessione.
Chiama l'API FinalizeCredentials del fornitore di autenticazione con questi parametri.
Chiudi la finestra di autorizzazione dopo aver ricevuto una risposta di esito positivo.

@app.api_route("/validateUserId", methods=["GET"])
async def validate_user(request: Request):
  auth_provider_name = request.query_params.get("auth_provider_name")
  session_id = request.cookies.get("session_id")
  session = consent_sessions.get(session_id, {})

  payload = {
      "userId": session.get("user_id"),
      "userIdValidationState": request.query_params.get(
          "user_id_validation_state"
      ),
      "consentNonce": session.get("consent_nonce"),
  }

  finalize_url = f"https://iamconnectorcredentials.googleapis.com/v1alpha/{auth_provider_name}/credentials:finalize"

  try:
    async with httpx.AsyncClient(timeout=30.0) as client:
      resp = await client.post(finalize_url, json=payload)
      resp.raise_for_status()
  except httpx.HTTPError as e:
    err_text = e.response.text if hasattr(e, "response") else str(e)
    status = e.response.status_code if hasattr(e, "response") else 500
    return HTMLResponse(err_text, status_code=status)

  return HTMLResponse("""
      <script>
          window.close();
      </script>
      <p>Success. You can close this window.</p>
  """)

Riprendere la conversazione con l'agente

Dopo che l'utente ha concesso il consenso e la finestra di autorizzazione si è chiusa, recupera auth_config e auth_request_function_call_id dai dati della sessione. Per continuare la conversazione, includi questi dettagli in una nuova richiesta all'agente come function_response.

if request.is_auth_resume and session.auth_request_function_call_id and session.auth_config:
    auth_content = types.Content(
        role='user',
        parts=[
            types.Part(
                function_response=types.FunctionResponse(
                    id=session.auth_request_function_call_id,
                    name='adk_request_credential',
                    response=session.auth_config
                )
            )
        ],
    )
    # Send message to agent
    async for event in agent.async_stream_query(
        user_id=request.user_id,
        message=auth_content,
        session_id=session_id,
    ):
        # ...

Esegui il deployment dell'agente

Quando esegui il deployment dell'agente su Google Cloud, assicurati che l'identità dell'agente sia attivata.

Se esegui il deployment in Agent Runtime, utilizza il flag identity_type=AGENT_IDENTITY:

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