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

Gli agenti ospitati su Google Cloud possono utilizzare la propria identità per autenticarsi a strumenti e servizi ospitati su runtime Google Cloud , come Cloud Run o Google Kubernetes Engine (GKE), richiedendo un token ID OpenID Connect (OIDC) da Agent Identity. Gli agenti possono anche utilizzare questi token ID per l'autenticazione su piattaforme cloud di terze parti (come Amazon Web Services (AWS) e Microsoft Azure), API personalizzate, gateway API e backend on-premise.

Quando un agente agisce di propria autorità per accedere a un servizio esterno, Agent Identity emette un token ID OpenID Connect (OIDC). Questo token web JSON (JWT) asserisce l'identità SPIFFE dell'agente ed è firmato dalle chiavi dell'emittente per il dominio di attendibilità dell'agente (pool di identità del workload gestito). I sistemi esterni possono verificare questi token 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 agente.

Prima di iniziare

  1. Verifica di aver scelto il metodo di autenticazione corretto. Scopri come funzionano le identità SPIFFE, i domini attendibili e le credenziali dell'agente nella panoramica dell'identità 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 (rivendicazione iss): l'URL emittente del pool di identità del 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 (rivendicazione aud): l'URI del pubblico che il servizio esterno o il provider di identità si aspetta durante la convalida dei 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 Agent Identity, 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 agent su Cloud Run: Cloud Run Admin (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 Agent Identity. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per eseguire il deployment di un agente con Agent Identity 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 di agenti in 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. Configurare l'agente con Agent Identity
  2. Richiedere un token ID OIDC nel codice dell'applicazione

Configura l'agente con Agent Identity

Attiva 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 in 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 di token, la memorizzazione nella cache locale e il rinnovo automatico dal server di metadati.

Per impostazione predefinita, i token ID OIDC emessi per i segmenti di pubblico esterni non sono associati al certificato di runtime.

L'esempio seguente utilizza la libreria google-auth per richiedere un token ID OIDC e allegarlo 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.

Per istruzioni ed esempi della libreria client in altri linguaggi di programmazione (inclusi Go, Node.js e Java), consulta Ottieni un token ID. Le versioni attuali della libreria client per queste lingue supportano --identity-type=agent-identity, ma non utilizzano token vincolati per impostazione predefinita.

Verifica dei token ID di Agent Identity

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à per i workload integrata

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

  • Cloud Run: se il servizio di ricezione viene eseguito su Cloud Run con l'accesso autenticato (--no-allow-unauthenticated), Cloud Run convalida i token di identità dell'agente in entrata a livello di ingresso. Concedi all'agente chiamante il ruolo Cloud Run Invoker (roles/run.invoker) sul servizio ricevente. Per ulteriori informazioni, consulta Esegui l'autenticazione sui server MCP su Cloud Run.

    Se il tuo servizio consente l'accesso non autenticato e verifica i token nel codice dell'applicazione, consulta Verificare i token a livello di programmazione.

  • Amazon Bedrock: configura l'autenticazione JWT in entrata specificando l'URL diGoogle Cloud Service Discovery del servizio token di sicurezza o l'URL emittente e il pubblico previsto. Per 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'URL dell'emittente del servizio token di sicurezza Google Cloud , il pubblico previsto e l'identificatore del soggetto (rivendicazione sub). Per istruzioni, vedi Creare una relazione di trust 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 carico di lavoro 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'intestazione HTTP Authorization: Bearer TOKEN.

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

  1. Estrarre e convalidare l'URL dell'emittente del token
  2. Individuare e memorizzare nella cache le chiavi di firma pubbliche
  3. Verificare la firma e le rivendicazioni del token
  4. 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à del 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à del workload del servizio token di sicurezza Google Cloud per la tua organizzazione o il tuo progetto:

  • Domini attendibili 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 attendibili 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.

Individuare e memorizzare 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 servizio token di sicurezza Google Cloud :

  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: l'ID organizzazione Google Cloud. Per un progetto senza un'organizzazione, sostituisci organizations/ORGANIZATION_ID con projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: l'ID del pool di identità del 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 lo 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'URL jwks_uri restituito nei metadati del provider OpenID:

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

    • ORGANIZATION_ID: l'ID organizzazione Google Cloud. Per un progetto senza un'organizzazione, sostituisci organizations/ORGANIZATION_ID con projects/PROJECT_NUMBER.
    • TRUST_DOMAIN: l'ID del pool di identità del 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 lo 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 di rilevamento OpenID Connect sia dell'endpoint JWKS includono il seguente header 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 privata e pubblica per i pool di identità del workload. Se il tuo verificatore riceve un token in entrata con un kid (ID chiave) che non si trova nella cache delle chiavi locale, recupera un nuovo JWKS dall'endpoint /openid/jwks prima di rifiutare il token.

    Se riscontri errori HTTP durante l'esecuzione di query sugli endpoint di discovery o JWKS, consulta Risolvere i problemi di autenticazione di Agent Identity.

Verificare la firma e le rivendicazioni del token

Per verificare in modo crittografico la firma del token e convalidare le attestazioni JWT, utilizza una libreria di verifica OIDC o JWT standard (ad esempio Google Tink) e procedi nel seguente modo:

  1. Firma: trova la chiave pubblica nella JWKS memorizzata nella cache che corrisponde a kid (ID chiave) nell'intestazione JWT. Convalida la firma utilizzando l'algoritmo specificato nel campo alg (RS256). Per la compatibilità futura, esamina i campi alg e kty nel JWKS in modo dinamico anziché codificare in modo permanente i tipi di algoritmo.
  2. Emittente (iss): verifica che l'attestazione iss corrisponda all'URL dell'emittente del pool di identità del workloadGoogle Cloud attendibile per il tuo dominio di attendibilità.
  3. Pubblico (aud): conferma 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 corrente sia precedente all'attestazione exp (consentendo una piccola tolleranza di discrepanza dell'orologio, ad esempio da 1 a 2 minuti).

Il seguente esempio utilizza Google Tink (tink.jwt) per verificare un token ID identità 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)

Autorizza l'identità SPIFFE dell'agente

Dopo aver verificato la firma e le rivendicazioni standard del token, esamina la rivendicazione sub (soggetto) verificata per autorizzare la richiesta e registrare l'agente chiamante nei log di controllo.

La rivendicazione 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 tuo servizio, confronta l'attestazione sub verificata con una lista consentita di ID SPIFFE di agenti attendibili (o prefissi di domini attendibili) prima di concedere l'accesso alle risorse protette.

Passaggi successivi