Memecahkan masalah autentikasi Identitas Agen

Dokumen ini menjelaskan cara menyelesaikan masalah umum terkait Autentikasi menggunakan Identitas Agen dengan pengelola autentikasi.

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 jalankan perintah gcloud berikut:

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

Peran pengguna tidak ada

Jika agen Anda tidak dapat menggunakan penyedia auth, pastikan identitas agen memiliki peran roles/iamconnectors.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 batasan 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 ada spasi di awal atau di akhir.

Izin ditolak saat mengambil kredensial (iamconnectors.connectors.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://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).

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 Pengguna Konektor (roles/iamconnectors.user) kepada prinsipal:

  • 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 error sintaksis atau melacak paket yang hilang.
  4. Pastikan semua paket yang diperlukan tercantum dalam file requirements.txt Anda.

Langkah berikutnya