Memecahkan masalah Workforce Identity Federation

Halaman ini menunjukkan cara mengatasi masalah umum terkait Workforce Identity Federation.

Memeriksa respons IdP response

Bagian ini menunjukkan cara memeriksa respons dari penyedia identitas Anda (IdP) untuk memecahkan masalah yang tercantum dalam dokumen ini.

Login berbasis browser

Untuk memeriksa respons yang ditampilkan oleh IdP, buat file HAR menggunakan alat pilihan Anda. Misalnya, Anda dapat menggunakan Penganalisis HAR Toolbox Google Admin, yang menyediakan petunjuk untuk membuat file HAR serta alat untuk mengupload dan menganalisisnya.

SAML

Untuk memeriksa respons IdP SAML, lakukan langkah-langkah berikut:

  1. Temukan nilai parameter permintaan SAMLResponse di dalam file HAR yang di-log ke URL dengan jalur /signin-callback.
  2. Lakukan dekode menggunakan alat pilihan Anda. Misalnya, Anda dapat menggunakan Enkode/Dekode Toolbox Google Admin.

OIDC

Untuk memeriksa respons IdP OIDC, lakukan langkah-langkah berikut. Pendekatan ini tidak berfungsi dengan alur kode.

  1. Cari parameter permintaan id_token dalam file HAR yang di-log ke URL dengan jalur /signin-callback.
  2. Lakukan dekode menggunakan alat proses debug JWT pilihan Anda.

gcloud CLI

Untuk memeriksa respons dari IdP saat menggunakan gcloud CLI, salin konten file yang Anda teruskan dalam flag --credential-source-file saat menjalankan perintah gcloud iam workforce-pools create-cred-config, lalu lakukan langkah-langkah berikut:

SAML

Lakukan dekode terhadap respons IdP SAML menggunakan alat pilihan Anda. Misalnya, Anda dapat menggunakan Enkode/Dekode Toolbox Google Admin.

OIDC

Lakukan dekode terhadap respons IdP OIDC menggunakan alat proses debug JWT pilihan Anda.

Meninjau log

Untuk menentukan apakah Google Cloud berkomunikasi dengan IdP Anda dan meninjau informasi transaksi, Anda dapat memeriksa log Cloud Audit Logs.

Untuk melihat contoh log, lihat Contoh log audit.

Error pengelolaan penyedia dan pool workforce

Bagian ini memberikan saran untuk memperbaiki error umum yang mungkin Anda alami saat mengelola pool dan penyedia.

Error pemetaan atribut umum

Untuk memecahkan masalah pemetaan atribut penyedia workload identity pool, lakukan hal berikut:

  • Periksa atribut, yang juga dikenal sebagai klaim, dalam konfigurasi IdP Anda. Verifikasi cara pemetaan atribut Anda mengonversi atribut IdP menjadi atribut Google Cloud dan cara kondisi Anda mengevaluasi atribut tersebut untuk mengizinkan atau menolak akses di konsol Google Cloud .

    1. Pastikan Anda memiliki peran IAM Workforce Pool Editor (roles/iam.workforcePoolEditor).
    2. Untuk mengaktifkan alur login berbasis browser untuk Workforce Identity Federation, tambahkan https://auth.cloud.google/signin-callback/locations/global/workforcePools/POOL_ID/providers/PROVIDER_ID ke daftar URI pengalihan yang diizinkan IdP Anda.

    3. Di konsol Google Cloud , buka Workforce Identity Pools.

      Buka Workforce Identity Pools
    4. Dari daftar pool, klik nama pool yang ingin Anda verifikasi.
    5. Di halaman Workforce pool details, klik nama IdP yang ingin Anda verifikasi.
    6. Di halaman Provider Details, klik Debug IdP token.
    7. Dalam dialog Login, login ke IdP Anda sebagai pengguna uji coba.

    Halaman Validasi atribut penyedia Anda menampilkan atribut yang dipetakan dan hasil kondisi atribut Anda.

    Bagian Atribut yang dipetakan dari token IdP Anda menampilkan cara pengisian atribut Google, seperti google.subject, dari token IdP Anda berdasarkan konfigurasi pemetaan Anda. Ikon error akan muncul jika pemetaan salah.

    Bagian Kondisi atribut menampilkan hasil boolean dari kondisi Anda. Jika kondisi bernilai false, login akan diblokir.

    Untuk melihat token pernyataan lengkap, klik Lihat token lengkap. Bagian ini menampilkan objek JSON mentah dari IdP Anda. Merujuk properti tingkat teratas dalam pemetaan menggunakan format assertion.PROPERTY_NAME.

    Untuk memperbaiki error, Anda dapat mengedit konfigurasi:

    1. Di halaman Validasi atribut penyedia Anda, klik Edit.
    2. Lakukan perubahan yang diperlukan.
    3. Untuk memulai pengujian baru dan melihat hasil yang diperbarui, klik Simpan dan ambil ulang token.

  • Periksa token yang dihasilkan dari IdP Anda. Untuk mempelajari cara membuat token dari IdP Anda, lihat dokumentasi IdP Anda.

  • Tinjau logging audit mendetail Workforce Identity Federation di Cloud Audit Logs.

Logging audit mendetail mencatat error autentikasi dan otorisasi bersama dengan klaim yang diterima oleh Workforce Identity Federation.

Anda dapat mengaktifkan logging audit mendetail saat membuat penyedia workforce identity pool. Untuk mengaktifkan logging audit mendetail, tambahkan tanda --detailed-audit-logging saat Anda membuat penyedia workforce identity pool.

Izin ditolak

Error ini dapat terjadi jika pengguna yang mencoba mengonfigurasi Workforce Identity Federation tidak memiliki peran IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).

INVALID_ARGUMENT: Konfigurasi single sign-on web OIDC tidak ada

Error berikut dapat terjadi jika kolom web-sso-response-type dan web-sso-assertion-claims-behavior tidak ditetapkan saat membuat penyedia pool workforce identity OIDC:

ERROR: (gcloud.iam.workforce-pools.providers.create-oidc) INVALID_ARGUMENT: Missing OIDC web single sign-on config.

Untuk mengatasi error ini, ikuti langkah-langkah di bagian Membuat penyedia untuk menetapkan kolom dengan tepat saat Anda membuat penyedia pool workforce identity OIDC.

Batas kapasitas terlampaui, coba lagi nanti

Error ini dapat terjadi jika Anda telah mencapai batas kuota untuk resource pool workforce. Hubungi Google Cloud perwakilan akun Anda untuk meminta penambahan kuota.

Error saat login

Bagian ini memberikan saran untuk memperbaiki error umum yang mungkin dialami oleh pengguna Workforce Identity Federation saat mereka login.

Error yang umum terjadi saat login

Kredensial tertentu ditolak oleh kondisi atribut

Error ini dapat terjadi jika kondisi atribut yang ditetapkan ke penyedia pool workforce identity tidak terpenuhi.

Misalnya, pertimbangkan kondisi atribut berikut:

SAML

'gcp-users' in assertion.attributes.groups

OIDC

'gcp-users' in assertion.groups

Dalam kasus ini, error akan muncul jika daftar grup yang dikirim dalam atribut groups oleh IdP Anda tidak berisi gcp-users.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Deskripsikan penyedia yang digunakan untuk login, dan pastikan bahwa attributeCondition sudah benar. Untuk mengetahui informasi mengenai operasi yang didukung dalam kondisi, lihat Definisi Bahasa.

  2. Ikuti langkah-langkah dalam memeriksa respons IdP untuk melihat atribut yang ditampilkan oleh IdP tersebut dan memastikan apakah kondisi atribut terbentuk dengan baik dan akurat.

  3. Login ke konsol admin IdP Anda, lalu periksa apakah atribut IdP yang dirujuk dalam kondisi atribut telah disiapkan dengan benar. Jika perlu, lihat dokumentasi IdP Anda.

Atribut yang dipetakan harus berjenis STRING

Error ini dapat terjadi pada penyedia pool workforce identity SAML jika atribut yang ditentukan dalam pesan error diharapkan berupa STRING bernilai tunggal, tetapi tetapi dipetakan ke daftar dalam pemetaan atribut.

Anggap penyedia pool workforce identity SAML yang memiliki pemetaan atribut, yaitu attribute.role=assertion.attributes.userRole, sebagai contoh. Dalam pernyataan ASML, Attribute dapat memiliki beberapa tag AttributeValue seperti yang ditunjukkan dalam contoh berikut. Dengan demikian, semua atribut SAML dianggap sebagai daftar, sehingga assertion.attributes.userRole adalah sebuah daftar.

<saml:Attribute Name="userRole">
    <saml:AttributeValue>
      security-admin
    </saml:AttributeValue>
    <saml:AttributeValue>
      user
    </saml:AttributeValue>
</saml:Attribute>

Dalam contoh ini, Anda mungkin melihat error berikut:

The mapped attribute 'attribute.role' must be of type STRING

Untuk mengatasi masalah ini, lakukan langkah-langkah berikut:

  1. Deskripsikan penyedia yang digunakan untuk login, lalu identifikasi atribut IdP yang ditetapkan di attributeMapping. Periksa atribut tersebut terhadap atribut yang ditampilkan dalam pesan error. Pada contoh sebelumnya, atribut IdP bernama userRole dipetakan ke atribut role. Atribut role kemudian muncul pada contoh error di atas.

  2. Saat memperbarui pemetaan atribut, pertimbangkan hal berikut:

    • Jika atribut yang menyebabkan error bernilai daftar, identifikasi atribut alternatif yang stabil dan bernilai string. Kemudian, update pemetaan atribut untuk menggunakannya dengan mereferensikan item pertamanya. Untuk contoh sebelumnya, jika myRole diidentifikasi sebagai atribut IdP alternatif yang bernilai tunggal, maka pemetaan atributnya adalah sebagai berikut:

      attribute.role=assertion.attributes.myRole[0]

    • Atau, jika atribut diketahui bernilai tunggal, update pemetaan atribut untuk menggunakan item pertama dari daftar. Untuk contoh sebelumnya, jika userRole hanya berisi satu peran, Anda dapat menggunakan pemetaan berikut:

      attribute.role=assertion.attributes.userRole[0]

    • Untuk mendapatkan ID bernilai tunggal dan stabil dari daftar, lihat Definisi Bahasa dan update pemetaan atribut Anda sebagaimana mestinya.

Lihat bagian memeriksa respons IdP untuk mengetahui respons yang ditampilkan oleh IdP.

Tidak dapat memperoleh nilai untuk google.subject dari kredensial tertentu

Error ini dapat terjadi jika klaim yang diperlukan google.subject tidak dapat dipetakan menggunakan pemetaan atribut yang Anda tetapkan di konfigurasi penyedia pool workforce identity.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Deskripsikan penyedia dan periksa attributeMapping. Identifikasi pemetaan yang dikonfigurasi untuk google.subject. Jika pemetaan tidak dapat dilakukan dengan benar, update penyedia pool workforce identity.

  2. Lihat bagian memeriksa respons IdP untuk mengetahui respons yang ditampilkan oleh IdP. Periksa nilai atribut dari respons IdP yang dipetakan ke google.subject dalam pemetaan atribut Anda.

    Jika nilainya kosong atau salah, login ke konsol admin IdP Anda, lalu periksa atribut yang dikonfigurasi. Untuk atribut, periksa apakah pengguna yang terpengaruh memiliki data yang sesuai dalam IdP Anda. Update konfigurasi IdP Anda untuk memperbaiki atribut atau informasi pengguna sebagaimana mestinya.

  3. Coba login kembali.

Ukuran atribut yang dipetakan melebihi batas

Error berikut terjadi saat pengguna gabungan mencoba login:

The size of the entire mapped attributes exceeds the 16 KB limit.

Untuk mengatasi masalah ini, minta administrator IdP Anda untuk mengurangi jumlah atribut yang dikeluarkan IdP Anda. IdP Anda hanya perlu memancarkan atribut yang diperlukan untuk menggabungkan pengguna ke Google Cloud. Untuk mempelajari lebih lanjut batas pemetaan atribut, lihat pemetaan atribut.

Misalnya, jika IdP Anda memancarkan sejumlah besar google.groups yang merupakan atribut yang dipetakan di penyedia pool workforce identity Anda, upaya login dapat gagal. Minta administrator Anda untuk membatasi jumlah grup yang dikeluarkan IdP Anda.

Jumlah grup melebihi batas

Error berikut terjadi saat pengguna gabungan mencoba login:

The current count of GROUPS_COUNT mapped attribute google.groups exceeds the GROUPS_COUNT_LIMIT count limit. Either modify your attribute mapping or the incoming assertion to produce a mapped attribute that has fewer than GROUPS_COUNT_LIMIT groups.

Error ini mencakup nilai berikut:

  • GROUPS_COUNT: jumlah grup yang dikeluarkan IdP

  • GROUPS_COUNT_LIMIT:Batas jumlah grup Google Cloud

Error ini terjadi saat jumlah grup yang dikeluarkan oleh IdP melebihi batas Google Cloud. Grup dipetakan ke Google Cloud menggunakan atribut google.groups.

Untuk mengatasi masalah ini, minta administrator Anda untuk mengurangi jumlah grup yang dikeluarkan IdP Anda. IdP Anda hanya perlu memancarkan grup yang digunakan untuk membuat federasi pengguna ke Google Cloud. Pelajari lebih lanjut batas terkait grup dalam pemetaan atribut.

Tenant SCIM tidak dapat ditemukan

Error ini terjadi saat pengguna mencoba login menggunakan penyedia pool workforce identity yang dikonfigurasi untuk menggunakan SCIM, tetapi tidak ada tenant SCIM yang dikonfigurasi untuk penyedia tersebut.

Jika hal ini terjadi, pengguna akan mendapatkan error berikut saat mencoba login:

There was an issue signing in with your identity provider.

Untuk mengatasi error ini, lakukan hal berikut:

  1. Konfigurasi token dan tenant SCIM di Google Cloud.
  2. Tautkan penyedia ke tenant SCIM.

400. Itu adalah error

Error ini dapat terjadi jika permintaan yang diterima tidak sesuai harapan atau formatnya salah.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Ikuti langkah-langkah di bagian Memberitahukan pengguna Anda cara login untuk memastikan bahwa Anda mengikuti langkah login dengan benar.

  2. Bandingkan konfigurasi penyedia pool workforce identity dengan konfigurasi IdP Anda.

Error login atribut tambahan

Bagian ini memberikan saran untuk memperbaiki error saat menggunakan atribut tambahan.

Login gagal saat atribut tambahan dikonfigurasi

Jika Anda telah mengonfigurasi atribut tambahan, masalah konfigurasi apa pun—seperti ID klien, rahasia klien, atau URI penerbit yang salah—akan menyebabkan upaya login gagal.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Deskripsikan penyedia dan pastikan bahwa client ID dan URI penerbit sudah benar.
  2. Pastikan rahasia klien valid dan masa berlakunya belum habis.
  3. Di IdP Anda, pastikan aplikasi memiliki izin yang diperlukan.

Grup dari pernyataan SAML atau OIDC diabaikan

Jika atribut tambahan dikonfigurasi, Workforce Identity Federation mengabaikan informasi grup yang diberikan langsung dalam klaim SAML atau OIDC. Sebagai gantinya, hanya grup yang diambil menggunakan saluran belakang yang digunakan (misalnya, menggunakan Microsoft Graph API).

Jika pengguna Anda tidak melihat grup yang diharapkan, pastikan grup tersebut diambil dengan benar menggunakan backchannel dan filter atribut dikonfigurasi dengan benar.

Error saat login OIDC

Bagian ini memberikan saran untuk memperbaiki error tertentu pada OIDC yang mungkin dialami oleh pengguna Workforce Identity Federation saat mereka login.

Terjadi error saat menghubungkan ke penerbit kredensial yang diberikan

Error ini dapat terjadi jika penyedia pool workforce identity OIDC tidak dapat menjangkau dokumen discovery OIDC atau URI JWKS.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Deskripsikan penyedia, dan periksa issuerUri yang dikonfigurasi. Buat URL dokumen discovery dengan menambahkan /.well-known/openid-configuration ke URI penerbit Anda. Misalnya, jika issuerUri Anda adalah https://example.com, maka URL dokumen penemuannya adalah https://example.com/.well-known/openid-configuration.

  2. Buka URL dokumen penemuan di jendela penjelajahan samaran.

    1. Jika URL tidak terbuka atau browser menampilkan error 404, lihat dokumentasi IdP Anda untuk mengidentifikasi URI penerbit yang benar. Jika perlu, update issuerUri di penyedia workforce identity pool Anda.

      Jika IdP berjalan secara lokal, lihat dokumentasi IdP Anda untuk menyediakannya agar dapat diakses melalui internet.

    2. Jika URL terbuka, periksa kondisi berikut:

      1. Pastikan URL tidak melakukan pengalihan terlalu sering sebelum menyajikan dokumen discovery. Jika ya, hubungi administrator IdP Anda untuk mengatasi masalah tersebut.
      2. Periksa waktu respons IdP. Hubungi administrator IdP Anda untuk mengurangi latensi respons.
      3. Dokumen discovery yang dibuka harus dalam format JSON.

      4. Cari kolom jwks_uri di JSON.

        1. Pastikan nilai URL yang terkait juga terbuka.
        2. Pastikan URL memenuhi kondisi seperti yang dijelaskan sebelumnya dalam panduan ini.

    3. Coba login kembali.

Error saat login SAML

Bagian ini memberikan saran untuk memperbaiki error tertentu pada SAML yang mungkin dialami oleh pengguna Workforce Identity Federation saat mereka login.

Gagal untuk memverifikasi tanda tangan di SAMLResponse

Error ini dapat terjadi pada penyedia pool workforce identity SAML jika tanda tangan pada respons IdP tidak dapat diverifikasi menggunakan satu pun sertifikat X.509 yang tersedia dalam XML metadata IdP yang dikonfigurasikan di penyedia pool workforce identity Anda. Error ini umumnya disebabkan oleh sertifikat verifikasi yang dirotasi pada IdP Anda, tetapi konfigurasi penyedia pool workforce identity tidak diupdate dengan file XML metadata IdP terbaru.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Opsional: ikuti langkah-langkah dalam memeriksa respons IdP untuk melihat respons yang ditampilkan oleh IdP dan menemukan kolom X509Certificate di dalamnya. Deskripsikan penyedia yang Anda gunakan untuk login, lalu periksa kolom X509Certificate yang ada dalam nilai idpMetadataXml yang ditetapkan pada penyedia pool workforce identity. Bandingkan sertifikat tersebut dengan sertifikat yang terlihat dalam respons yang ditampilkan oleh IdP Anda. Kedua sertifikat tersebut harus cocok.

  2. Login ke konsol admin IdP Anda, lalu download XML metadata terbaru.

  3. Update penyedia pool workforce identity dengan XML metadata IdP yang didownload.

  4. Coba login kembali.

Penerima di pernyataan SAML tidak ditetapkan ke URL ACS yang benar

Error ini dapat terjadi pada penyedia pool workforce identity SAML jika respons IdP berisi nilai yang salah untuk kolom Recipient pada tag SubjectConfirmationData.

Untuk mengatasi error ini, update Recipient URL / Redirect URL atau kolom yang setara di konfigurasi IdP Anda untuk menggunakan URL alihan yang dijelaskan dalam Menyiapkan URL alihan di IdP Anda, lalu coba login kembali.

Ikuti langkah-langkah dalam memeriksa respons IdP untuk melihat respons yang ditampilkan oleh IdP dan memastikan bahwa kolom Recipient sudah benar.

Misalnya, untuk penyedia pool workforce identity locations/global/workforcePools/example-pool/providers/example-provider, Recipient yang berisi URL alihan akan muncul di respons SAML IdP sebagai berikut:

<SubjectConfirmationData Recipient="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

Tujuan SAMLResponse tidak cocok dengan URL callback RP

Error ini dapat terjadi pada penyedia pool workforce identity pool provider SAML jika respons IdP berisi nilai yang salah untuk kolom Destination pada tag Response.

Untuk mengatasi error ini, update Destination URL / Redirect URL atau kolom yang setara di konfigurasi IdP Anda untuk menggunakan URL alihan yang dijelaskan dalam Menyiapkan URL alihan di IdP Anda.

Ikuti langkah-langkah dalam memeriksa respons IdP untuk melihat respons yang ditampilkan oleh IdP dan memastikan bahwa kolom Destination sudah benar.

Misalnya, pada penyedia pool workforce identity locations/global/workforcePools/example-pool/providers/example-provider, Destination yang berisi URL alihan akan muncul di respons SAML IdP sebagai berikut:

<Response Destination="https://auth.cloud.google/signin-callback/locations/global/workforcePools/example-pool/providers/example-provider"

Pernyataan tidak valid: NameID tidak ada atau kosong

Error ini dapat terjadi jika respons SAML yang diterima dari IdP Anda tidak berisi kolom NameId atau nilainya kosong.

Untuk mengatasi error ini, lihat dokumentasi IdP Anda untuk mengonfigurasinya agar mengirim NameID yang merupakan subjek pernyataan SAML yang biasanya adalah pengguna terautentikasi.

Ikuti langkah-langkah dalam memeriksa respons IdP untuk melihat respons yang ditampilkan oleh IdP dan NameID yang ditetapkan di dalamnya.

Semua <AudienceRestriction> harus berisi ID entitas RP SAML

Error ini dapat terjadi jika tag AudienceRestriction dalam respons SAML dari IdP Anda tidak menetapkan tag Audience dengan nilai yang mewakili ID entitas penyedia pool workforce identity.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

  1. Lihat dokumentasi IdP Anda tentang cara mengonfigurasi audiens di tag AudienceRestriction yang dikirimkan dalam respons SAML. Biasanya, audiens dikonfigurasi dengan menyiapkan kolom Entity ID atau Audience di konfigurasi IdP Anda. Lihat bagian SAML tentang Membuat penyedia pool workforce identity untuk mengetahui nilai SP Entity ID yang harus ditetapkan.

  2. Setelah mengupdate konfigurasi IdP Anda, coba login kembali.

Ikuti langkah-langkah dalam memeriksa respons IdP untuk melihat respons yang ditampilkan oleh IdP dan AudienceRestriction yang ditetapkan di dalamnya.

Error sinkronisasi dan penyediaan SCIM

Bagian ini menjelaskan cara mengatasi masalah terkait penyediaan dan sinkronisasi SCIM di Workforce Identity Federation.

Kegagalan autentikasi token SCIM (HTTP 401 atau 403)

Error ini terjadi saat log penyedia identitas (IdP) melaporkan kegagalan autentikasi (HTTP 401 Unauthorized atau HTTP 403 Forbidden). Penyebab umum meliputi hal berikut:

  • Token SCIM tidak ada, tidak valid, atau sudah tidak berlaku.
  • Token SCIM berisi spasi tambahan.
  • Permintaan tidak memiliki header Authorization: Bearer <TOKEN>.
  • Token SCIM tidak memiliki izin yang memadai.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Dalam konfigurasi penyediaan IdP Anda, pastikan token SCIM cocok dengan token rahasia yang dibuat di Google Cloud tanpa spasi tambahan.

  2. Jika token hilang atau tidak valid, buat token SCIM baru:

    gcloud iam workforce-pools providers scim-tenants tokens create SCIM_TOKEN_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --scim-tenant="SCIM_TENANT_ID" \
    --location="global"

    Ganti kode berikut:

    • SCIM_TOKEN_ID: ID untuk token SCIM baru.
    • WORKFORCE_POOL_ID: ID workforce identity pool.
    • PROVIDER_ID: ID penyedia workforce pool.
    • SCIM_TENANT_ID: ID tenant SCIM.

  3. Perbarui token rahasia di konfigurasi IdP Anda.

Batas kecepatan terlampaui (HTTP 429 Too Many Requests)

Error ini terjadi saat rasio permintaan IdP melebihi kuota tenant SCIM. Secara default, permintaan tulis dan baca dibatasi hingga 3.000 permintaan per tenant SCIM per organisasi per menit, yang setara dengan 50 kueri per detik (QPS). Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Pastikan rasio permintaan sinkronisasi IdP Anda berada dalam batas kuota.
  2. Di konsol Google Cloud , buka IAM & Admin > Quotas, lalu filter iamscim.googleapis.com untuk memantau penggunaan kuota.
  3. Jika Anda memerlukan throughput yang lebih tinggi, minta penambahan kuota di konsol Google Cloud .

Pembuatan tenant SCIM gagal

Error ini terjadi saat perintah gcloud iam workforce-pools providers scim-tenants create gagal.

Penyebab umumnya meliputi:

  • Tenant SCIM sudah ada di kumpulan tenaga kerja. Setiap kumpulan tenaga kerja hanya mendukung satu tenant SCIM.
  • Tenant SCIM yang baru saja dihapus masih dalam periode penghapusan sementara selama 30 hari.
  • Anda tidak memiliki peran IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).
  • Flag --claim-mapping berisi ekspresi Common Expression Language (CEL) yang tidak didukung.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Pastikan Anda memiliki peran IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).

  2. Mencantumkan tenant SCIM yang ada untuk memeriksa apakah tenant sudah ada:

    gcloud iam workforce-pools providers scim-tenants list \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --location="global"

    Ganti kode berikut:

    • WORKFORCE_POOL_ID: ID workforce identity pool.
    • PROVIDER_ID: ID penyedia workforce pool.

  3. Jika tenant yang sebelumnya dihapus sementara dihapus, hapus secara permanen menggunakan flag --hard-delete:

    gcloud iam workforce-pools providers scim-tenants delete SCIM_TENANT_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --location="global" \
    --hard-delete

    Ganti SCIM_TENANT_ID dengan ID tenant SCIM.

  4. Pastikan --claim-mapping hanya menggunakan ekspresi CEL yang didukung. Untuk mengetahui informasi selengkapnya, lihat Memetakan token dan atribut SCIM.

Pembuatan token SCIM gagal

Error ini terjadi saat perintah gcloud iam workforce-pools providers scim-tenants tokens create gagal.

Penyebab umumnya meliputi:

  • Tenant SCIM sudah memiliki maksimum dua token SCIM.
  • Anda tidak memiliki peran IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Pastikan Anda memiliki peran IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin).

  2. Mencantumkan token SCIM yang ada untuk memeriksa apakah batas dua token telah tercapai:

    gcloud iam workforce-pools providers scim-tenants tokens list \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --scim-tenant="SCIM_TENANT_ID" \
    --location="global"

    Ganti kode berikut:

    • WORKFORCE_POOL_ID: ID workforce identity pool.
    • PROVIDER_ID: ID penyedia workforce pool.
    • SCIM_TENANT_ID: ID tenant SCIM.

  3. Jika tenant SCIM sudah memiliki dua token, hapus token yang tidak digunakan atau tidak valid:

    gcloud iam workforce-pools providers scim-tenants tokens delete SCIM_TOKEN_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --provider="PROVIDER_ID" \
    --scim-tenant="SCIM_TENANT_ID" \
    --location="global"

    Ganti SCIM_TOKEN_ID dengan ID token SCIM yang akan dihapus.

  4. Setelah menghapus token, coba buat token SCIM baru.

Konflik pemetaan atribut duplikat (HTTP 409 Conflict)

Error ini terjadi saat log penyedia identitas (IdP) melaporkan HTTP 409 Conflict selama sinkronisasi karena IdP mengirimkan nilai duplikat untuk google.subject atau google.group, atau nilai userName atau displayName yang tidak unik.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Di konsol administrator IdP Anda, pastikan atribut yang dipetakan ke google.subject dan google.group menghasilkan nilai yang tidak tumpang-tindih.
  2. Pastikan setiap pengguna memiliki userName unik dan setiap grup memiliki displayName unik.

Permintaan PATCH Microsoft Entra ID gagal

Error ini terjadi saat update pengguna atau permintaan PATCH dari Microsoft Entra ID gagal karena URL Tenant tidak memiliki parameter kueri ?aadOptscim062020, yang diperlukan untuk permintaan PATCH yang sesuai dengan RFC.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Di Microsoft Entra ID, buka aplikasi perusahaan Anda, lalu pilih Provisioning > Manage provisioning > Admin Credentials.

  2. Di kolom URL Tenant, tambahkan ?aadOptscim062020 ke URI dasar:

    https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID?aadOptscim062020

    Ganti SCIM_TENANT_UID dengan ID unik tenant SCIM Anda.

  3. Klik Uji Koneksi, lalu simpan konfigurasi.

Akses atau berbagi berbasis pengguna atau grup tidak berfungsi

Masalah ini terjadi saat pengguna yang disinkronkan tidak dapat mengakses Google Cloud resource, atau saat berbagi notebook di Gemini Notebook Enterprise atau agen di aplikasi Gemini Enterprise gagal.

Penyebab umumnya meliputi:

  • Kegagalan atau penundaan sinkronisasi diam-diam dari IdP.
  • Pemetaan klaim yang tidak konsisten antara penyedia (--attribute-mapping) dan tenant SCIM (--claim-mapping).
  • Perubahan di IdP pada atribut yang dipetakan ke google.subject atau google.group. Google Cloud mengharapkan nilai yang dipetakan ke atribut ini tidak dapat diubah.
  • Penggunaan SCIM tidak diaktifkan untuk grup di penyedia.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Verifikasi sinkronisasi dan keanggotaan: Pastikan pengguna, grup, dan keanggotaan grup berhasil disinkronkan ke Google Cloud:

    • Memverifikasi sinkronisasi pengguna:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Users" \
  --data-urlencode 'filter=userName eq "USER_NAME"'

    • Memverifikasi sinkronisasi grup:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
  --data-urlencode 'filter=displayName eq "GROUP_NAME"'

    • Verifikasi keanggotaan grup: Mengonfirmasi bahwa pengguna adalah anggota grup:

      curl -G -H "Authorization: Bearer SCIM_TOKEN" \
  "https://iamscim.googleapis.com/v1alpha1/tenants/SCIM_TENANT_UID/Groups" \
  --data-urlencode 'filter=id eq "GROUP_ID" and members eq "USER_ID"'

      Jika pengguna adalah anggota grup, respons akan menampilkan totalResults: 1. Jika pengguna bukan anggota, respons akan menampilkan totalResults: 0.

    Ganti kode berikut:

    • SCIM_TOKEN: token rahasia SCIM Anda.
    • SCIM_TENANT_UID: ID unik tenant SCIM Anda.
    • USER_NAME: nama pengguna yang disinkronkan.
    • GROUP_NAME: nama tampilan grup yang disinkronkan.
    • GROUP_ID: ID SCIM grup yang disinkronkan, yang ditampilkan di kolom id respons kueri grup.
    • USER_ID: ID SCIM pengguna yang disinkronkan, ditampilkan di kolom id respons kueri pengguna.

  2. Periksa pemetaan klaim: Pastikan atribut yang dipetakan ke google.subject di penyedia (misalnya, google.subject=assertion.email.lowerAscii()) cocok dengan identitas yang dipetakan di tenant SCIM (misalnya, google.subject=user.emails[0].value.lowerAscii()). Karena pemetaan klaim bersifat tetap, jika pemetaan tidak konsisten, Anda harus menghapus tenant SCIM secara permanen dan membuatnya kembali dengan pemetaan yang benar.

  3. Pastikan ID tidak dapat diubah: Verifikasi bahwa atribut IdP yang dipetakan ke google.subject dan google.group tidak berubah. Google Cloud memperlakukan nilai yang dipetakan ke atribut ini sebagai ID yang tidak dapat diubah. Jika nilai atribut berubah di IdP Anda, batalkan perubahan di IdP Anda, atau hapus pengguna atau grup yang terpengaruh secara permanen dari IdP Anda dan buat ulang dengan nilai baru sehingga ID cocok dengan yang diharapkan Google Cloud Google.

  4. Aktifkan penggunaan grup SCIM: Perbarui penyedia Anda untuk mengaktifkan SCIM untuk grup:

    gcloud iam workforce-pools providers update-oidc PROVIDER_ID \
    --workforce-pool="WORKFORCE_POOL_ID" \
    --location="global" \
    --scim-usage="enabled-for-groups"

    Ganti kode berikut:

    • PROVIDER_ID: ID penyedia workforce pool.
    • WORKFORCE_POOL_ID: ID workforce identity pool.

Perubahan yang dilakukan di IdP tertunda atau tidak tercermin

Masalah ini terjadi saat pembaruan IdP untuk pengguna, keanggotaan grup, atau penghapusan tidak langsung muncul di Google Cloud.

Karena SCIM berbasis push, pembaruan bergantung pada jadwal sinkronisasi IdP Anda. Misalnya, Microsoft Entra ID melakukan sinkronisasi kira-kira setiap 40 menit.

Untuk mengatasi masalah ini, lakukan langkah berikut:

  1. Tunggu siklus sinkronisasi terjadwal berikutnya dari IdP Anda.
  2. Untuk segera menerapkan perubahan, picu sinkronisasi sesuai permintaan di konsol administrator IdP Anda.

Penyediaan pengguna gagal karena format email

Error ini terjadi saat pengguna tertentu gagal disinkronkan ke Google Cloud, dan log penyedia identitas (IdP) Anda melaporkan HTTP 400 Bad Request dengan error SCIM invalidValue.

Google Cloud SCIM memerlukan tepat satu email kantor per pengguna. Penyediaan gagal jika IdP mengirim beberapa email atau email bukan berjenis work.

Untuk mengatasi masalah ini, konfigurasi pemetaan atribut IdP Anda agar hanya mengirim email kerja utama.

Gagal memperbarui grup (HTTP PUT tidak didukung)

Error ini terjadi saat update grup gagal karena klien menggunakan HTTP PUT, yang tidak didukung. Google Cloud SCIM API hanya mendukung HTTP PATCH untuk update grup.

Untuk mengatasi masalah ini, konfigurasi IdP atau klien kustom Anda agar menggunakan PATCH HTTP untuk pembaruan grup.