Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Memecahkan masalah autentikasi Identitas Agen

Dokumen ini menjelaskan cara menyelesaikan error umum saat mengautentikasi agen dengan Identitas Agen dan pengelola autentikasi Identitas Agen.

Untuk mengetahui petunjuk tentang cara mengonfigurasi penyedia autentikasi, lihat Mengelola penyedia autentikasi Agent Identity. Untuk mengetahui petunjuk tentang cara memverifikasi token ID Identitas Agen di layanan eksternal, lihat Mengautentikasi ke layanan eksternal menggunakan identitas agen sendiri.

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 dihasilkan oleh pengelola autentikasi.

Untuk mengatasi masalah ini, temukan URI pengalihan yang dihasilkan dengan melihat detail penyedia autentikasi di konsol Google Cloud 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 auth, pastikan identitas agen memiliki peran roles/agentidentity.user di resource penyedia auth.

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

Masalah endpoint penerbit

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

Jika Google Cloud tidak dapat mengambil metadata OIDC atau JWKS, pastikan endpoint tidak berada di belakang 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 pengikatan 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 Anda memiliki persyaratan berbagi token tertentu atau harus menyisipkan token langsung di header. Untuk memilih tidak ikut, tetapkan variabel lingkungan berikut saat Anda men-deploy agen:

config={
  "env_vars": {
    "GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN": "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:

Di konsol Google Cloud , buka halaman APIs & Services >Library dan pastikan API target diaktifkan.
Buka APIs & Services >Library
Di konsol Google Cloud , buka halaman APIs & Services >Credentials, edit kunci API Anda, dan verifikasi bahwa pembatasan 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 terbentuk dengan benar, atau tidak ada di kredensial project Anda.

Untuk mengatasi error ini, pastikan Anda menyalin string kunci API yang benar dari halaman Credentials di konsol Google Cloud dan tidak menyertakan spasi di awal atau di 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 ke pokok 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 kurangnya dependensi Python, error sintaksis di agent.py, atau variabel lingkungan yang salah dikonfigurasi.

Untuk mengatasi error ini, lakukan hal berikut:

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

Loop autentikasi ServiceNow atau cakupan yang tidak terduga

Saat agen melakukan autentikasi ke ServiceNow menggunakan OAuth 3-legged, alur autentikasi mungkin gagal atau agen mungkin memasuki loop permintaan.

Masalah ini terjadi karena ServiceNow menentukan cakupan yang diberikan di tingkat aplikasi, bukan dari cakupan yang diminta oleh agen. Jika administrator mengonfigurasi cakupan tertentu di aplikasi ServiceNow (misalnya, useraccount), ServiceNow akan menampilkan token yang hanya berisi cakupan yang dikonfigurasi tersebut, meskipun jika agen meminta cakupan yang berbeda (seperti mcp_server). Jika agen secara ketat mengharapkan atau memvalidasi cakupan yang diminta, agen akan menolak token yang diterima dan mungkin meminta ulang kredensial dalam loop.

Untuk mengatasi masalah ini, lakukan langkah berikut:

Login ke instance ServiceNow Anda sebagai administrator.
Buka konfigurasi aplikasi OAuth ServiceNow.
Pastikan semua cakupan yang diperlukan oleh agen Anda ditambahkan secara eksplisit ke daftar cakupan yang diizinkan untuk aplikasi.
Konfigurasi agen Anda untuk meminta hanya cakupan yang diaktifkan di ServiceNow.

Untuk mengetahui informasi selengkapnya, lihat Layanan pihak ketiga yang didukung.

Error cakupan ganda GitHub atau Microsoft

Saat mengonfigurasi penyedia autentikasi untuk GitHub atau Microsoft, autentikasi akan gagal jika Anda meminta beberapa cakupan OAuth.

Pengelola autentikasi mendukung integrasi cakupan tunggal untuk GitHub dan Microsoft. Pengelola autentikasi tidak mendukung permintaan beberapa cakupan secara bersamaan.

Untuk mengatasi masalah ini, konfigurasi agen atau penyedia autentikasi Anda agar hanya meminta satu cakupan yang diperlukan untuk integrasi.

Untuk mengetahui informasi selengkapnya, lihat Layanan pihak ketiga yang didukung.

Error endpoint JWKS dan penemuan OpenID Connect

Layanan eksternal atau pihak tepercaya dapat mengkueri endpoint Google Cloud Security Token Service OpenID Connect Discovery (/.well-known/openid-configuration) atau JSON Web Key Set (/openid/jwks) untuk memverifikasi token ID Identitas Agen. Saat membuat kueri endpoint ini, permintaan mungkin gagal dengan error HTTP 400, 404, 429, atau 500.

Tabel berikut menjelaskan penyebab dan solusi untuk error ini:

Status HTTP	Penyebab	Resolusi
`400 Bad Request`	Error ini terjadi karena nama resource workload identity pool di URL permintaan tidak valid, atau permintaan menyertakan header HTTP `Authorization`.	Untuk mengatasi error ini, lakukan hal berikut: Verifikasi bahwa nama resource workload identity pool menggunakan format domain tepercaya agen yang didukung (`agents.global.org-ORGANIZATION_ID.system.id.goog` atau `agents.global.proj-PROJECT_NUMBER.system.id.goog`). Hapus header `Authorization` atau OAuth dari permintaan. Endpoint `/.well-known/openid-configuration` dan `/openid/jwks` bersifat publik dan tidak diautentikasi; meneruskan header autentikasi menyebabkan permintaan gagal dengan error `HTTP 400`.
`404 Not Found`	Error ini terjadi karena ID organisasi, nomor project, atau pool workload identity yang ditentukan tidak ada, atau jalur URL salah.	Untuk mengatasi error ini, pastikan ID organisasi, nomor project, dan domain tepercaya (ID pool identitas beban kerja) di URL sudah akurat. Pastikan juga jalur URL diakhiri dengan `/.well-known/openid-configuration` atau `/openid/jwks`.
`429 Too Many Requests`	Error ini terjadi karena verifier Anda melampaui batas kecepatan permintaan dengan membuat kueri ke endpoint penemuan atau JWKS tanpa menyimpan respons dalam cache.	Untuk mengatasi error ini, konfigurasikan verifier Anda untuk meng-cache dokumen penemuan dan JWKS hingga 24 jam sesuai dengan header respons `Cache-Control: public, max-age=86400, must-revalidate`.
`500 Internal Server Error`	Error ini terjadi karena server mengalami masalah internal sementara saat mengambil kunci penandatanganan publik.	Untuk mengatasi error ini, gunakan JWKS yang di-cache jika tersedia, atau coba lagi permintaan dengan backoff eksponensial.

Verifikasi tanda tangan token gagal setelah rotasi kunci

Saat layanan eksternal memverifikasi token ID Agent Identity, verifikasi tanda tangan mungkin gagal untuk token yang baru dikeluarkan meskipun token sebelumnya dari agen yang sama berhasil.

Masalah ini terjadi karena Google Cloud secara berkala merotasi kunci penandatanganan pribadi dan publik untuk workload identity pool. Akibatnya, kid (ID kunci) token masuk mungkin tidak ada di cache kunci lokal verifier Anda.

Untuk mengatasi masalah ini, konfigurasi verifier Anda sehingga saat menerima token dengan kid yang tidak dikenal, verifier akan mengambil JWKS baru dari endpoint /openid/jwks sebelum menolak token.