Memecahkan masalah autentikasi Identitas Agen

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

Untuk mengetahui petunjuk tentang cara mengonfigurasi penyedia autentikasi, lihat Mengelola penyedia autentikasi Identitas Agen.

Ketidakcocokan URI pengalihan

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_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 pembatasan kunci API tidak mengizinkan akses ke layanan ini.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

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

    Buka APIs & Services >Library

  2. 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, salah format, atau tidak ada di kredensial project Anda.

Untuk mengatasi error ini, pastikan Anda menyalin string kunci API yang benar dari halaman Kredensial 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 generik.

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:

  1. Buka konsol Google Cloud , lalu 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 kesalahan sintaksis atau melacak paket yang tidak ada.
  4. 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 3-legged OAuth, 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:

  1. Login ke instance ServiceNow Anda sebagai administrator.
  2. Buka konfigurasi aplikasi OAuth ServiceNow.
  3. Pastikan semua cakupan yang diperlukan oleh agen Anda ditambahkan secara eksplisit ke daftar cakupan yang diizinkan untuk aplikasi.
  4. 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.

Langkah berikutnya