Memecahkan masalah autentikasi Identitas Agen

Dokumen ini menjelaskan cara mengatasi error umum Autentikasi menggunakan Identitas Agen dengan pengelola autentikasi.

URI pengalihan tidak cocok

Jika Anda menerima error redirect URI mismatch dari aplikasi pihak ketiga selama alur OAuth, pastikan URI pengalihan yang terdaftar di portal developer pihak ketiga sama persis dengan URI yang dibuat oleh pengelola autentikasi.

Untuk mengatasi masalah ini, temukan URI pengalihan yang dibuat dengan melihat detail penyedia autentikasi di Google Cloud konsol atau menjalankan perintah gcloud berikut:

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

Peran pengguna tidak ada

Jika agen Anda tidak dapat menggunakan penyedia autentikasi, pastikan identitas agen memiliki peran roles/agentidentity.user pada resource penyedia autentikasi.

Untuk mengatasi masalah ini, berikan peran menggunakan Google Cloud konsol atau jalankan add-iam-policy-binding perintah.

Masalah endpoint penerbit

Untuk penyedia OIDC, pastikan endpoint penerbit dapat diakses secara publik dan mendukung dokumen penemuan .well-known/openid-configuration.

Jika Google Cloud tidak dapat mengambil metadata OIDC atau JWKS, pastikan bahwa endpoint tidak berada di balik firewall atau jaringan terbatas.

Error 401 UNAUTHENTICATED

Jika agen Anda tidak dapat melakukan autentikasi, error berikut mungkin terjadi. Error ini biasanya disebabkan oleh kebijakan Akses Kontekstual yang dikelola Google yang menerapkan binding mTLS dan bukti kriptografi 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"
  }
}

Untuk mengatasi error ini, Anda dapat memilih untuk tidak menggunakan kebijakan Akses Kontekstual default jika memiliki persyaratan berbagi token tertentu atau harus menyisipkan token langsung di header. Untuk memilih tidak menggunakan kebijakan, tetapkan variabel lingkungan berikut saat Anda men-deploy agen:

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

Layanan kunci API diblokir (API_KEY_SERVICE_BLOCKED)

Jika Anda memvalidasi kunci API, error berikut mungkin terjadi. Error ini menunjukkan bahwa layanan diblokir:

"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."
  }
]

Error ini terjadi karena layanan API target (misalnya, Cloud Translation API) belum diaktifkan di project Google Cloud Anda, atau batasan kunci API tidak mengizinkan akses ke layanan ini.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Di Google Cloud konsol, buka halaman APIs & Services >Library dan pastikan API target diaktifkan.

    Buka APIs & Services >Library

  2. Di Google Cloud konsol, buka halaman APIs & Services >Credentials, edit kunci API Anda, dan pastikan batasan API-nya mengizinkan akses ke layanan.

    Buka APIs & Services >Credentials

Kunci API tidak valid (API_KEY_INVALID)

Saat mengirim permintaan ke layanan pihak ketiga, error berikut mungkin terjadi. Error ini menunjukkan bahwa kunci API tidak valid:

"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."
  }
]

Error ini terjadi karena string kunci API yang diteruskan di header permintaan Anda salah, tidak valid, atau tidak ada di kredensial project Anda.

Untuk mengatasi error ini, pastikan Anda menyalin string kunci API yang benar dari halaman Credentials di Google Cloud konsol dan tidak menyertakan spasi kosong di awal atau akhir.

Izin ditolak saat mengambil kredensial (agentidentity.authProviders.retrieveCredentials)

Saat menjalankan adk web secara lokal atau berinteraksi dengan agen yang di-deploy, error 403 Forbidden berikut mungkin terjadi:

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).

Error ini terjadi karena akun utama yang mencoba memanggil penyedia autentikasi tidak memiliki izin IAM yang diperlukan untuk mengambil kredensial.

Untuk mengatasi error ini, berikan peran Agent Identity User (roles/agentidentity.user) kepada akun utama:

  • Jika error ini terjadi selama pengembangan lokal (uv run adk web atau uvicorn), pastikan Anda telah memberikan peran tersebut ke akun pengguna pribadi Anda (user:USER_EMAIL).
  • Jika error ini terjadi saat berinteraksi dengan agen yang di-deploy, pastikan Anda telah memberikan peran tersebut ke akun utama ID SPIFFE agen Anda (principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Kegagalan deployment umum

Saat men-deploy agen menggunakan uv run adk deploy, perintah mungkin gagal dengan pesan error umum.

Error ini terjadi karena dependensi Python tidak ada, error sintaksis di agent.py, atau variabel lingkungan yang salah dikonfigurasi.

Untuk mengatasi error ini, lakukan hal berikut:

  1. Buka Google Cloud konsol dan buka halaman Logs Explorer.
  2. Telusuri log penampung deployment sementara (misalnya, maps_mcp_agent_tmp... atau bigquery_mcp_agent_tmp...).
  3. Periksa traceback Python untuk mengidentifikasi error sintaksis atau melacak paket yang tidak ada.
  4. Pastikan semua paket yang diperlukan tercantum dalam file requirements.txt Anda.

Langkah berikutnya