Autenticarsi ai servizi esterni utilizzando l'identità dell'agente

L'identità dell'agente consente agli agenti di Google Cloud utilizzare la propria identità per l'autenticazione a servizi esterni e ai workload ospitati su Cloud Run o Google Kubernetes Engine (GKE). Utilizzando i token ID OpenID Connect (OIDC), puoi connettere gli agenti a piattaforme cloud di terze parti come Amazon Web Services (AWS) e Microsoft Azure, API personalizzate, API Gateway e backend on-premise.

Quando un agente agisce di propria iniziativa, l'identità dell'agente emette un token ID OIDC, ovvero un token web JSON (JWT) che dichiara l'identità SPIFFE dell'agente ed è firmato dalle chiavi dell'emittente per il dominio di attendibilità dell'agente (pool di identità dei workload gestiti). I sistemi esterni possono verificare questi token ID senza Google Cloud credenziali o SDK tramite endpoint pubblici ospitati dal Google Cloud servizio token di sicurezza:

  • Un endpoint OpenID Connect Discovery 1.0 (/.well-known/openid-configuration) che pubblica i metadati del provider OpenID e l'endpoint della chiave pubblica (jwks_uri).
  • Un endpoint JSON Web Key Set (JWKS) (/openid/jwks) che fornisce le chiavi pubbliche attive utilizzate per verificare le firme sui token ID dell'agente.

Per autenticare l'agente alle Google Cloud API e alle risorse utilizzando la propria identità, consulta Autenticati Google Cloud utilizzando l'identità dell'agente. Per accedere ai servizi per conto di un utente finale, consulta Autenticati utilizzando OAuth a tre vie con il gestore dell'autenticazione.

Prima di iniziare

  1. Verifica di aver scelto il metodo di autenticazione corretto. Consulta la panoramica dell'identità dell'agente per scoprire come funzionano le identità SPIFFE, i domini di attendibilità, e le credenziali dell'agente.
  2. Crea ed esegui il deployment di un agente con l'identità dell'agente abilitata.

  3. Assicurati che il servizio esterno o il provider di identità soddisfi i seguenti requisiti:

  4. Identifica i seguenti valori di configurazione per l'agente e il servizio esterno di destinazione:

    • URL emittente (iss claim): l'URL emittente del pool di identità dei workload per la tua organizzazione (https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN) o il tuo progetto (https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN).
    • Pubblico consentito (aud claim): l'URI del pubblico che il servizio esterno o il provider di identità si aspetta quando convalida i token ID.

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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire il deployment di un agente con l'identità dell'agente, chiedi all'amministratore di concederti i seguenti ruoli IAM nel progetto:

  • Esegui il deployment di un agente in Agent Runtime su Gemini Enterprise Agent Platform: Utente Vertex AI (roles/aiplatform.user)
  • Esegui il deployment di un servizio agente su Cloud Run: Amministratore Cloud Run (roles/run.admin)

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 eseguire il deployment di un agente con l'identità dell'agente. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per eseguire il deployment di un agente con l'identità dell'agente sono necessarie le seguenti autorizzazioni:

  • Esegui il deployment di un agente in Agent Runtime su Gemini Enterprise Agent Platform:
    • aiplatform.reasoningEngines.create
    • aiplatform.reasoningEngines.update
  • Esegui il deployment di un servizio agente su Cloud Run:
    • run.services.create
    • run.services.update

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

Ottieni un token ID OIDC per un agente

Per configurare l'agente in modo che ottenga e invii un token ID OIDC a un servizio esterno, completa le seguenti attività:

  1. Configura l'agente con l'identità dell'agente
  2. Richiedi un token ID OIDC nel codice dell'applicazione

Configura l'agente con l'identità dell'agente

Abilita l'identità dell'agente quando esegui il deployment dell'agente:

  • Se esegui il deployment dell'agente in Agent Runtime su Gemini Enterprise Agent Platform , imposta identity_type su AGENT_IDENTITY:

    remote_app = client.agent_engines.create(
    agent=app,
    config={
        "identity_type": types.IdentityType.AGENT_IDENTITY,
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
    },
)

  • Se esegui il deployment di un servizio agente containerizzato su Cloud Run, passa il flag --identity-type=agent-identity:

    gcloud run deploy SERVICE_NAME \
    --image=IMAGE_URL \
    --identity-type=agent-identity \
    --no-allow-unauthenticated

    Sostituisci quanto segue:

    • SERVICE_NAME: il nome del servizio Cloud Run.
    • IMAGE_URL: l'URL dell'immagine container per l'agente.

Richiedi un token ID OIDC nel codice dell'applicazione

Nel codice dell'applicazione dell'agente, utilizza la libreria client Google Auth per richiedere un token ID OIDC per il pubblico esterno di destinazione. La libreria client gestisce la generazione dei token, la memorizzazione nella cache locale e il rinnovo automatico dal server dei metadati.

Per impostazione predefinita, le librerie client Google Auth supportate associano crittograficamente i token ID OIDC al certificato X.509 univoco dell'agente includendo l'impronta del certificato nell'attestazione cnf (x5t#S256) del token. I servizi di ricezione possono facoltativamente convalidare questa attestazione rispetto al certificato client presentato durante un handshake mutual TLS (mTLS) oppure ignorare l'attestazione se non applicano l'associazione dei certificati.

Cloud Run applica automaticamente l'associazione dei certificati quando l'attestazione cnf è presente in un token ID. Se l'agente chiama un servizio Cloud Run utilizzando un token ID associato, devi chiamare l'endpoint mTLS (*.mtls.run.app) tramite una connessione mTLS. Per continuare a chiamare un URL *.run.app standard, disattiva l'associazione dei certificati per richiesta (ad esempio, impostando bind_id_token=False in Python) o nell'ambiente di runtime con GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false. Per le versioni e gli esempi delle librerie supportate, consulta Disattivare i token associati ai certificati.

Quando chiami un endpoint che applica l'associazione dei certificati tramite mTLS, configura la sessione client in modo che presenti il certificato X.509 dell'agente durante l'handshake mTLS (ad esempio, chiamando authed_session.configure_mtls_channel() in Python).

Gli esempi seguenti utilizzano la libreria google-auth per richiedere un token ID OIDC associato a un certificato, configurare facoltativamente il canale mTLS e allegare il token come token Bearer in una richiesta in uscita:

Python

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import id_token

# 1. Specify the audience expected by the external receiver
# (for example, AWS Bedrock AgentCore or your external service URL).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create ID token credentials and an AuthorizedSession, which handles
# local token caching, automatic renewal before expiry, and the
# Bearer header.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)

# 3. Send the authenticated request to the external service.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

Sostituisci quanto segue:

  • EXTERNAL_SERVICE_AUDIENCE: l'URI del pubblico previsto dal servizio di ricezione (ad esempio, bedrock.us-east-1.amazonaws.com o api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: l'URL dell'API esterna o dell'endpoint di backend chiamato dall'agente.

Python (mTLS)

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import id_token

# 1. Specify the audience expected by the receiving service
# (for example, a regional Cloud Run mTLS URL or an on-premises mTLS endpoint).
target_audience = "https://EXTERNAL_SERVICE_AUDIENCE"

# 2. Create certificate-bound ID token credentials and configure the mTLS
# channel to present the agent's X.509 certificate.
credentials = id_token.fetch_id_token_credentials(audience=target_audience)
authed_session = AuthorizedSession(credentials)
authed_session.configure_mtls_channel()

# 3. Send the authenticated request over mTLS.
response = authed_session.post(
    "https://EXTERNAL_SERVICE_ENDPOINT",
    json={"prompt": "Hello from Agent"},
)

Sostituisci quanto segue:

  • EXTERNAL_SERVICE_AUDIENCE: l'URI del pubblico previsto dal servizio di ricezione (ad esempio, un URL mTLS di Cloud Run regionale o api.example.com).
  • EXTERNAL_SERVICE_ENDPOINT: l'URL dell' API mTLS o dell'endpoint di backend chiamato dall'agente.

Per istruzioni ed esempi sulle librerie client in altri linguaggi, come Go, Node.js e Java, consulta Ottieni un token ID. Le librerie client per questi linguaggi supportano --identity-type=agent-identity. Le librerie che supportano i token ID associati ai certificati associano i token per impostazione predefinita e ti consentono di disattivare l'associazione per le singole richieste.

Verifica i token ID dell'identità dell'agente

Quando un servizio esterno riceve un token ID OIDC dal tuo agente, verifica il token utilizzando uno dei seguenti approcci in base al servizio di destinazione:

Utilizza la federazione delle identità dei workload integrata

Se il servizio di ricezione viene eseguito su una piattaforma cloud che supporta l'autenticazione IAM integrata o la federazione delle identità dei workload OIDC, non devi scrivere codice di verifica dei token personalizzato:

  • Cloud Run: se il servizio di ricezione viene eseguito su Cloud Run con l'ingresso autenticato (--no-allow-unauthenticated), Cloud Run convalida i token dell'identità dell'agente in entrata a livello di ingresso. Quando il token include l'attestazione cnf, configura l'agente chiamante in modo che punti all'URL mTLS regionale del servizio di ricezione (https://SERVICE_NAME-PROJECT_NUMBER.REGION.mtls.run.app) in modo che Cloud Run possa convalidare il certificato client durante l'handshake mTLS. Concedi all'agente chiamante il ruolo Cloud Run Invoker (roles/run.invoker) sul servizio di ricezione. Per ulteriori informazioni, consulta Autenticati ai server MCP su Cloud Run.

    Se il tuo servizio consente l'ingresso non autenticato e verifica i token nel codice dell'applicazione, consulta Verifica i token in modo programmatico.

  • Amazon Bedrock: configura l'autenticazione JWT in entrata specificando l' Google Cloud URL di rilevamento del servizio token di sicurezza o l'URL dell'emittente e il pubblico previsto. Per le istruzioni, consulta Configura l'autorizzatore JWT in entrata nella documentazione di AWS.

  • Microsoft Entra ID: configura una credenziale di identità federata con lo scenario Altro emittente. Specifica l' Google Cloud URL dell'emittente del servizio token di sicurezza , il pubblico previsto e l'identificatore del soggetto (sub claim). Per le istruzioni, consulta Creare una relazione di attendibilità tra un'app e un provider di identità esterno nella documentazione di Microsoft Learn.

Verifica i token in modo programmatico

Se l'agente invia richieste a un'API personalizzata, a un microservizio, a un gateway API o a un workload on-premise, il servizio di ricezione deve verificare il token ID OIDC in entrata prima di concedere l'accesso. In genere, l'agente passa questo token nell' Authorization: Bearer TOKEN intestazione HTTP.

Per verificare i token ID in entrata in modo programmatico, completa le seguenti attività:

  1. Estrai e convalida l'URL dell'emittente del token
  2. Rileva e memorizza nella cache le chiavi di firma pubbliche
  3. Verifica la firma e le attestazioni del token
  4. (Facoltativo) Convalida l'associazione dei certificati (cnf claim)
  5. Autorizza l'identità SPIFFE dell'agente

Estrai e convalida l'URL dell'emittente del token

Quando arriva una richiesta in entrata, leggi il payload JWT non verificato per estrarre l'attestazione iss (emittente). Questa attestazione contiene l'URL del pool di identità dei workload per il dominio di attendibilità dell'agente. Questo URL funge da URL di base per il documento di rilevamento e le chiavi di firma pubbliche.

Prima di effettuare qualsiasi richiesta di rete in uscita, verifica che l'attestazione iss corrisponda all'URL del pool di identità dei workload del servizio token di sicurezza Google Cloud previsto per la tua organizzazione o il tuo progetto:

  • Domini di attendibilità a livello di organizzazione:

    https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Ad esempio, per un'organizzazione con ID 123456789012, TRUST_DOMAIN è agents.global.org-123456789012.system.id.goog.

  • Domini di attendibilità a livello di progetto (per i progetti senza un'organizzazione):

    https://sts.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/TRUST_DOMAIN

    Ad esempio, per un progetto con numero 9876543210, TRUST_DOMAIN è agents.global.proj-9876543210.system.id.goog.

Rileva e memorizza nella cache le chiavi di firma pubbliche

Dopo aver convalidato l'URL dell'emittente, recupera e memorizza nella cache le chiavi di firma pubbliche dal Google Cloud servizio token di sicurezza:

  1. Esegui una query sull'endpoint OpenID Connect Discovery: aggiungi /.well-known/openid-configuration all'URL dell'emittente di base e invia una richiesta HTTP GET non autenticata:

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

    • ORGANIZATION_ID: Il tuo Google Cloud ID organizzazione. Per un progetto senza un'organizzazione, sostituisci organizations/ORGANIZATION_ID con projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: l'ID del pool di identità dei workload per il dominio di attendibilità dell'agente (ad esempio, agents.global.org-123456789012.system.id.goog).

    Metodo HTTP e URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/.well-known/openid-configuration

    Per inviare la richiesta, espandi una di queste opzioni:

    Una richiesta riuscita restituisce uno stato HTTP 200 OK e un oggetto JSON contenente i metadati del provider OpenID, incluso il campo jwks_uri:

    {
  "issuer": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog",
  "jwks_uri": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/openid/jwks",
  "authorization_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/authorize",
  "token_endpoint": "https://sts.googleapis.com/v1/organizations/123456789012/locations/global/workloadIdentityPools/agents.global.org-123456789012.system.id.goog/token",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

  2. Esegui una query sull'endpoint JSON Web Key Set (JWKS): invia una richiesta HTTP GET non autenticata all'jwks_uri URL restituito nei metadati del provider OpenID:

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

    • ORGANIZATION_ID: Il tuo Google Cloud ID organizzazione. Per un progetto senza un'organizzazione, sostituisci organizations/ORGANIZATION_ID con projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: l'ID del pool di identità dei workload per il dominio di attendibilità dell'agente (ad esempio, agents.global.org-123456789012.system.id.goog).

    Metodo HTTP e URL: 

    GET https://sts.googleapis.com/v1/organizations/ORGANIZATION_ID/locations/global/workloadIdentityPools/TRUST_DOMAIN/openid/jwks

    Per inviare la richiesta, espandi una di queste opzioni:

    Una richiesta riuscita restituisce uno stato HTTP 200 OK e un oggetto JSON contenente un array di chiavi pubbliche formattate in base a RFC 7517:

    {
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "4d1933f8e6c4e0b512c140989f6655c68997...",
      "n": "uQn4zN_1mQ0VpGv82-Wp3w...",
      "e": "AQAB"
    }
  ]
}

  3. Memorizza nella cache il documento di rilevamento e le chiavi: le risposte sia dell'endpoint OpenID Connect Discovery sia dell'endpoint JWKS includono la seguente intestazione della cache HTTP:

    Cache-Control: public, max-age=86400, must-revalidate

    Memorizza nella cache il documento di rilevamento e JWKS per un massimo di 24 ore (86400 secondi) per migliorare le prestazioni di verifica ed evitare limitazione di frequenza.

    Google Cloud ruota periodicamente le chiavi di firma private e pubbliche per i pool di identità dei workload. Se il verificatore riceve un token in entrata con un kid (ID chiave) non presente nella cache delle chiavi locale, recupera un JWKS aggiornato dall'endpoint /openid/jwks prima di rifiutare il token.

    Se riscontri errori HTTP durante l'esecuzione di query sugli endpoint di rilevamento o JWKS consulta Risolvere i problemi di autenticazione dell'identità dell'agente.

Verifica la firma e le attestazioni del token

Per verificare crittograficamente la firma del token e convalidare le attestazioni JWT, utilizza una libreria di verifica OIDC o JWT standard (come Google Tink) ed esegui le seguenti operazioni:

  1. Firma: trova la chiave pubblica nel JWKS memorizzato nella cache che corrisponde all'ID chiave kid nell'intestazione JWT. Convalida la firma utilizzando l'algoritmo specificato nel campo alg (RS256). Per la compatibilità con le versioni precedenti, esamina dinamicamente i campi alg e kty in JWKS anziché codificare i tipi di algoritmo.
  2. Emittente (iss): verifica che l'attestazione iss corrisponda all'URL dell'emittente del pool di identità dei workload attendibile Google Cloud per il tuo dominio di attendibilità.
  3. Pubblico (aud): verifica che l'attestazione aud corrisponda all'identificatore del pubblico configurato del tuo servizio.
  4. Ora di emissione (iat) e ora di scadenza (exp): verifica che l'attestazione iat sia nel passato e che l'ora attuale sia precedente all'attestazione exp (consentendo una piccola tolleranza di clock-skew, ad esempio da 1 a 2 minuti).

L'esempio seguente utilizza Google Tink (tink.jwt) per verificare un token ID dell'identità dell'agente rispetto a un payload JSON JWKS:

Python

import tink
from tink import jwt

# Initialize Tink JWT signature primitives (call once at application startup).
jwt.register_jwt_signature()


def verify_agent_identity_token(
    token: str,
    jwks_json: str,
    expected_issuer: str,
    expected_audience: str,
) -> jwt.VerifiedJwt:
    """Verifies an Agent Identity JWT against a JWKS JSON string using Tink.

    Args:
        token: The compact serialized JWT string.
        jwks_json: The JWKS JSON string fetched from the STS pool endpoint.
        expected_issuer: The expected token issuer ('iss' claim).
        expected_audience: The expected token audience ('aud' claim).

    Returns:
        jwt.VerifiedJwt: The verified JWT claims object.

    Raises:
        tink.TinkError: If the JWKS cannot be parsed, the key is not found,
            or token validation (signature, issuer, audience, expiration) fails.
    """
    # 1. Convert the JWKS JSON into a Tink public KeysetHandle.
    keyset_handle = jwt.jwk_set_to_public_keyset_handle(jwks_json)

    # 2. Instantiate the Tink JwtPublicKeyVerify primitive.
    jwt_verifier = keyset_handle.primitive(jwt.JwtPublicKeyVerify)

    # 3. Configure expected validation rules (issuer, audience, expiration).
    # Google Cloud STS sets 'typ': 'JWT' in the header, so
    # expected_type_header="JWT" is required.
    validator = jwt.new_validator(
        expected_issuer=expected_issuer,
        expected_audience=expected_audience,
        expected_type_header="JWT",
        allow_missing_expiration=False,
    )

    # 4. Cryptographically verify the signature and standard OIDC claims.
    return jwt_verifier.verify_and_decode(token, validator)

(Facoltativo) Convalida l'associazione dei certificati (cnf claim)

Se il servizio di ricezione applica l'associazione dei certificati tramite mTLS, convalida l'attestazione cnf (x5t#S256) rispetto al certificato client presentato durante l'handshake mTLS:

  1. Termina mutual TLS (mTLS): configura il server o il proxy di ingresso in modo che richieda e convalidi il certificato X.509 dell'agente durante l'handshake TLS in base a TLS 1.3 (RFC 9846).
  2. Calcola l'impronta del certificato (x5t#S256): estrai il certificato client X.509 foglia dalla connessione mTLS. Calcola l'hash SHA-256 sui byte con codifica DER e codifica in base64url il digest senza padding =.
  3. Convalida l'attestazione cnf (x5t#S256): esamina il payload JWT verificato per l'oggetto cnf ({"cnf": {"x5t#S256": "FINGERPRINT"}}) e verifica che il valore x5t#S256 corrisponda alla fingerprint del certificato client in base a RFC 8705 sezione 6.1. Se il chiamante non ha presentato un certificato client tramite mTLS o se le impronte non corrispondono, rifiuta la richiesta con una risposta HTTP 401 Unauthorized.

Autorizza l'identità SPIFFE dell'agente

Dopo aver verificato la firma e le attestazioni standard del token, esamina l'attestazione sub (oggetto) verificata per autorizzare la richiesta e registrare l'agente chiamante nei log di audit.

L'attestazione sub contiene l'ID SPIFFE univoco dell'agente, ad esempio:

  spiffe://agents.global.org-123456789012.system.id.goog/resources/aiplatform/projects/9876543210/locations/us-central1/reasoningEngines/my-test-agent

Nella logica di autorizzazione del servizio, confronta l'attestazione sub verificata con una lista consentita di ID SPIFFE dell'agente attendibili (o prefissi del dominio di attendibilità) prima di concedere l'accesso alle risorse protette.

Passaggi successivi