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.

Penting: Jika Anda meminta file HAR dari pengguna, minta mereka untuk membersihkan semua informasi identitas pribadi (PII) dan cookie dari file HAR sebelum mengirimkannya.

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

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 perwakilan akun Google Cloud 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 penyedia identitas (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. Ikuti panduan di bawah ini untuk mengupdate pemetaan atribut:

   Catatan: Hanya google.groups yang menerima daftar.

   • 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 akan seperti 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 perbarui 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.

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 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 penemuan OIDC atau URI JWKS.

Untuk mengatasi error ini, lakukan langkah-langkah berikut:

1. Deskripsikan penyedia, dan periksa issuerUri yang dikonfigurasi. Buat URL dokumen penemuan 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 kumpulan workforce identity 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 penemuan. 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 penemuan 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 seperti yang ditunjukkan di bawah ini:

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

Catatan: NameID tetap diperlukan meskipun Anda memutuskan untuk memetakan atribut yang berbeda ke google.subject dalam pemetaan atribut.

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.