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

Anteprima

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questo documento descrive come risolvere gli errori comuni durante l'utilizzo di Agent Identity auth manager.

Per istruzioni sulla configurazione dei provider di autenticazione, consulta Gestire i provider di autenticazione di Agent Identity.

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 relativi all'endpoint dell'emittente

Per i provider OIDC, verifica che l'endpoint dell'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 può autenticarsi, potrebbe verificarsi il seguente errore. Questo errore è in genere causato da un criterio di accesso sensibile al contesto gestito da Google che applica l'associazione 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 se hai requisiti specifici per la condivisione dei token o devi inserire il token direttamente nell'intestazione. Per disattivare la funzionalità, imposta la seguente variabile di ambiente quando esegui il deployment dell'agente:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

La disattivazione rimuove la protezione del token binding, rendendo questi token di accesso di breve durata vulnerabili a furti o attacchi di replay. Pertanto, la disattivazione non è consigliata.

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 necessarie 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 viene visualizzato 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 tracciare i pacchetti mancanti.
4. Assicurati che tutti i pacchetti richiesti siano elencati nel file requirements.txt.

Ciclo di autenticazione 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 all'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 il tuo agente o il tuo fornitore di autenticazione in modo che richieda un solo ambito necessario per l'integrazione.

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

Passaggi successivi

• Panoramica del gestore di autenticazione di Agent Identity
• Panoramica di Agent Identity
• Eseguire l'autenticazione utilizzando OAuth a tre vie con Auth Manager
• Eseguire l'autenticazione utilizzando OAuth a due vie con Auth Manager
• Autenticati utilizzando la chiave API con Auth Manager
• Gestire i provider di autenticazione di Agent Identity