Risolvere i problemi di autenticazione dell'identità dell'agente

Questo documento descrive come risolvere gli errori comuni durante l'autenticazione degli agenti con Agent Identity e il gestore di autenticazione di Agent Identity.

Per istruzioni sulla configurazione dei provider di autenticazione, consulta Gestire i provider di autenticazione di Agent Identity. Per istruzioni sulla verifica dei token ID Agent Identity nei servizi esterni, consulta Autenticarsi ai servizi esterni utilizzando l'identità di un agente.

URI di reindirizzamento non corrispondente

Se ricevi un errore redirect URI mismatch dall'applicazione di terze parti durante il flusso OAuth, assicurati che l'URI di reindirizzamento registrato nel portale per sviluppatori di terze parti corrisponda esattamente all'URI generato da Auth Manager.

Per risolvere il problema, trova l'URI di reindirizzamento generato visualizzando i dettagli del provider di autenticazione nella console Google Cloud o eseguendo il seguente comando gcloud:

gcloud alpha agent-identity authProviders describe AUTH_PROVIDER_NAME \
    --location="LOCATION"

Ruolo utente mancante

Se l'agente non può utilizzare il provider di autenticazione, verifica che l'identità dell'agente disponga del ruolo roles/agentidentity.user nella risorsa del provider di autenticazione.

Per risolvere il problema, concedi il ruolo utilizzando la console Google Cloud o esegui il comando add-iam-policy-binding.

Problemi con l'endpoint dell'emittente

Per i provider OIDC, verifica che l'endpoint emittente sia accessibile pubblicamente e supporti il documento di rilevamento .well-known/openid-configuration.

Se Google Cloud non riesce a recuperare i metadati OIDC o JWKS, assicurati che l'endpoint non si trovi dietro un firewall o una rete con limitazioni.

Errore 401 UNAUTHENTICATED

Se l'agente non riesce ad autenticarsi, potrebbe verificarsi il seguente errore. Questo errore è in genere causato da un criterio di accesso sensibile al contesto gestito da Google che applica il binding mTLS e le prove crittografiche DPoP:

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED"
  }
}

Per risolvere questo errore, puoi disattivare il criterio di accesso sensibile al contesto predefinito quando hai requisiti specifici di condivisione dei token o devi inserire il token direttamente nell'intestazione. Per disattivare la funzionalità, imposta la seguente variabile di ambiente quando deploy l'agente:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "false",
  }
}

Servizio chiavi API bloccato (API_KEY_SERVICE_BLOCKED)

Se convalidi la chiave API, potrebbe verificarsi il seguente errore. Questo errore indica che il servizio è bloccato:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_SERVICE_BLOCKED",
    "domain": "googleapis.com",
    "metadata": {
      "methodName": "google.cloud.translate.v2.TranslateService.TranslateText",
      "service": "translate.googleapis.com",
      "consumer": "projects/PROJECT_NUMBER",
      "apiName": "translate"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "Requests to this API translate method google.cloud.translate.v2.TranslateService.TranslateText are blocked."
  }
]

Questo errore si verifica perché il servizio API di destinazione (ad esempio, l'API Cloud Translation) non è stato abilitato nel tuo Google Cloud progetto oppure le limitazioni della chiave API non consentono l'accesso a questo servizio.

Per risolvere questo errore, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina API e servizi >Libreria e assicurati che l'API di destinazione sia abilitata.

    Vai ad API e servizi >Libreria

  2. Nella console Google Cloud , vai alla pagina API e servizi >Credenziali, modifica la chiave API e verifica che le restrizioni API consentano l'accesso al servizio.

    Vai ad API e servizi >Credenziali

Chiave API non valida (API_KEY_INVALID)

Quando invii richieste a un servizio di terze parti, potrebbe verificarsi il seguente errore. Questo errore indica che la chiave API non è valida:

"details": [
  {
    "@type": "type.googleapis.com/google.rpc.ErrorInfo",
    "reason": "API_KEY_INVALID",
    "domain": "googleapis.com",
    "metadata": {
      "service": "translate.googleapis.com"
    }
  },
  {
    "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
    "locale": "en-US",
    "message": "API key not valid. Please pass a valid API key."
  }
]

Questo errore si verifica perché la stringa della chiave API passata nell'intestazione della richiesta è errata, non è formattata correttamente o non esiste nelle credenziali del progetto.

Per risolvere questo errore, verifica di aver copiato la stringa chiave API corretta dalla pagina Credenziali nella console Google Cloud e di non aver incluso spazi bianchi iniziali o finali.

Autorizzazione negata per il recupero delle credenziali (agentidentity.authProviders.retrieveCredentials)

Quando esegui adk web localmente o interagisci con l'agente di cui è stato eseguito il deployment, potrebbe verificarsi il seguente errore 403 Forbidden:

google.api_core.exceptions.Forbidden: 403 POST https://agentidentitycredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'agentidentity.authProviders.retrieveCredentials' denied on resource '//agentidentity.googleapis.com/projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME' (or it may not exist).

Questo errore si verifica perché l'entità che tenta di richiamare il provider di autenticazione non dispone delle autorizzazioni IAM richieste per recuperare le credenziali.

Per risolvere questo errore, concedi il ruolo Utente Agent Identity (roles/agentidentity.user) all'entità:

  • Se questo errore si verifica durante lo sviluppo locale (uv run adk web o uvicorn), assicurati di aver concesso il ruolo al tuo account utente personale (user:USER_EMAIL).
  • Se questo errore si verifica durante l'interazione con un agente di cui è stato eseguito il deployment, assicurati di aver concesso il ruolo al principal ID SPIFFE dell'agente (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Errore di deployment generico

Quando esegui il deployment dell'agente utilizzando uv run adk deploy, il comando potrebbe non riuscire e visualizzare un messaggio di errore generico.

Questo errore si verifica a causa di dipendenze Python mancanti, errori di sintassi in agent.py o variabili di ambiente configurate in modo errato.

Per risolvere questo errore:

  1. Apri la console Google Cloud e vai alla pagina Esplora log.
  2. Cerca i log del contenitore di deployment temporaneo (ad esempio maps_mcp_agent_tmp... o bigquery_mcp_agent_tmp...).
  3. Controlla il traceback di Python per identificare errori di sintassi o pacchetti mancanti.
  4. Assicurati che tutti i pacchetti richiesti siano elencati nel file requirements.txt.

Ciclo di autenticazione di ServiceNow o ambiti imprevisti

Quando un agente si autentica in ServiceNow utilizzando OAuth a tre vie, il flusso di autenticazione potrebbe non riuscire o l'agente potrebbe entrare in un ciclo di richieste.

Questo problema si verifica perché ServiceNow determina gli ambiti concessi a livello di applicazione anziché dagli ambiti richiesti dall'agente. Se un amministratore configura ambiti specifici nell'applicazione ServiceNow (ad esempio useraccount), ServiceNow restituisce token contenenti solo gli ambiti configurati, anche se l'agente ha richiesto ambiti diversi (ad esempio mcp_server). Se l'agente si aspetta o convalida rigorosamente gli ambiti richiesti, rifiuta il token ricevuto e potrebbe richiedere nuovamente le credenziali in un ciclo.

Per risolvere il problema, segui questi passaggi:

  1. Accedi alla tua istanza ServiceNow come amministratore.
  2. Vai alla configurazione dell'applicazione ServiceNow OAuth.
  3. Assicurati che tutti gli ambiti richiesti dall'agente siano aggiunti esplicitamente all'elenco degli ambiti consentiti per l'applicazione.
  4. Configura l'agente in modo che richieda solo gli ambiti abilitati in ServiceNow.

Per saperne di più, consulta Servizi di terze parti supportati.

Errore di più ambiti GitHub o Microsoft

Quando configuri un provider di autenticazione per GitHub o Microsoft, l'autenticazione non va a buon fine se richiedi più ambiti OAuth.

Auth Manager supporta le integrazioni con un solo ambito per GitHub e Microsoft. Auth Manager non supporta la richiesta simultanea di più ambiti.

Per risolvere il problema, configura l'agente o il fornitore di autenticazione in modo che richieda un solo ambito necessario per l'integrazione.

Per saperne di più, consulta Servizi di terze parti supportati.

Errori di rilevamento OpenID Connect e dell'endpoint JWKS

Un servizio esterno o una relying party può eseguire query sugli endpoint del Google Cloudservizio token di sicurezza OpenID Connect Discovery (/.well-known/openid-configuration) o del set di chiavi web JSON (/openid/jwks) per verificare un token ID Agent Identity. Quando esegui una query su questi endpoint, la richiesta potrebbe non riuscire e restituire un errore HTTP 400, 404, 429 o 500.

La tabella seguente descrive le cause e le soluzioni per questi errori:

Stato HTTP Causa Risoluzione
400 Bad Request Questo errore si verifica perché il nome della risorsa del pool di identità del workload nell'URL della richiesta non è valido oppure la richiesta include un'intestazione HTTP Authorization. Per risolvere questo errore, segui questi passaggi:
  • Verifica che il nome della risorsa del pool di identità del workload utilizzi un formato del dominio di attendibilità dell'agente supportato (agents.global.org-ORGANIZATION_ID.system.id.goog o agents.global.proj-PROJECT_NUMBER.system.id.goog).
  • Rimuovi eventuali intestazioni Authorization o OAuth dalla richiesta. Gli endpoint /.well-known/openid-configuration e /openid/jwks sono pubblici e non autenticati; il passaggio delle intestazioni di autenticazione causa l'esito negativo della richiesta con un errore HTTP 400.
404 Not Found Questo errore si verifica perché l'ID organizzazione, il numero di progetto o il pool di identità del workload specificato non esiste oppure il percorso URL è errato. Per risolvere questo errore, verifica che l'ID organizzazione, il numero di progetto e il dominio di attendibilità (ID pool di identità del workload) nell'URL siano corretti. Verifica inoltre che il percorso dell'URL termini con /.well-known/openid-configuration o /openid/jwks.
429 Too Many Requests Questo errore si verifica perché il tuo programma di verifica ha superato il tasso di richieste eseguendo query sugli endpoint di individuazione o JWKS senza memorizzare nella cache la risposta. Per risolvere questo errore, configura il tuo verificatore in modo che memorizzi nella cache il documento di rilevamento e JWKS per un massimo di 24 ore in base all'intestazione della risposta Cache-Control: public, max-age=86400, must-revalidate.
500 Internal Server Error Questo errore si verifica perché il server ha riscontrato un problema interno temporaneo durante il recupero delle chiavi di firma pubbliche. Per risolvere questo errore, utilizza il JWKS memorizzato nella cache, se disponibile, o riprova a inviare la richiesta con il backoff esponenziale.

La verifica della firma del token non riesce dopo la rotazione della chiave

Quando un servizio esterno verifica un token ID identità agente, la verifica della firma potrebbe non riuscire per i token appena emessi, anche se i token precedenti dello stesso agente sono stati verificati correttamente.

Questo problema si verifica perché Google Cloud ruota periodicamente le chiavi di firma privata e pubblica per i pool di identità del workload. Di conseguenza, l'kid (ID chiave) del token in entrata potrebbe non essere presente nella cache delle chiavi locale del tuo verificatore.

Per risolvere il problema, configura il tuo verificatore in modo che, quando riceve un token con un kid non riconosciuto, recuperi un JWKS aggiornato dall'endpoint /openid/jwks prima di rifiutare il token.

Passaggi successivi