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

Questo documento descrive come risolvere gli errori comuni Autenticazione utilizzando l'identità dell'agente con Auth Manager.

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 esegui il seguente comando gcloud:

gcloud alpha agent-identity connectors 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/iamconnectors.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 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 se 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 esegui il deployment dell'agente:

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": 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 progetto Google Cloud oppure perché 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 trasmessa 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 che non siano stati inclusi spazi bianchi iniziali o finali.

Autorizzazione negata per il recupero delle credenziali (iamconnectors.connectors.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://iamconnectorcredentials.mtls.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/connectors/AUTH_PROVIDER_NAME/credentials:retrieve?%24alt=json%3Benum-encoding%3Dint: Permission 'iamconnectors.connectors.retrieveCredentials' denied on resource '//iamconnectors.googleapis.com/projects/PROJECT_ID/locations/LOCATION/connectors/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 connettore (roles/iamconnectors.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 l'errore di sintassi o tracciare i pacchetti mancanti.
  4. Assicurati che tutti i pacchetti richiesti siano elencati nel file requirements.txt.

Passaggi successivi