Mengonfigurasi Workforce Identity Federation dengan PingFederate

Dokumen ini menunjukkan cara mengonfigurasi Workforce Identity Federation dengan penyedia identitas (IdP) PingFederate dan mengelola akses ke Google Cloud. Setelah Anda mengonfigurasi IdP PingFederate, pengguna gabungan dapat mengakses Google Cloud layanan yang mendukung Workforce Identity Federation dengan menggunakan protokol SAML 2.0.

Sebelum memulai

  1. Pastikan Anda menyiapkan organisasi Google Cloud .
  2. Instal Google Cloud CLI. Setelah penginstalan, inisialisasi Google Cloud CLI dengan menjalankan perintah berikut:

    gcloud init

    Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

  3. Untuk login, IdP Anda harus memberikan informasi autentikasi yang ditandatangani: Respons IdP SAML harus ditandatangani.
  4. Untuk menerima informasi penting tentang perubahan pada organisasi atau Google Cloud produk Anda, Anda harus memberikan Kontak Penting. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Workforce Identity Federation.

Biaya

Workforce Identity Federation tersedia sebagai fitur tanpa biaya. Namun, audit logging mendetail Workforce Identity Federation menggunakan Cloud Logging. Untuk mempelajari harga Logging, lihat Harga Google Cloud Observability.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengonfigurasi Workforce Identity Federation, minta administrator untuk memberi Anda peran IAM IAM Workforce Pool Admin (roles/iam.workforcePoolAdmin) di organisasi. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Jika Anda mengonfigurasi izin di lingkungan pengembangan atau pengujian—tetapi tidak di lingkungan produksi—Anda dapat memberikan peran dasar Pemilik IAM (roles/owner). Peran ini juga mencakup izin untuk Workforce Identity Federation.

Membuat workforce identity pool

gcloud

Untuk membuat workforce identity pool, jalankan perintah berikut:

gcloud iam workforce-pools create WORKFORCE_POOL_ID \
    --organization=ORGANIZATION_ID \
    --display-name="DISPLAY_NAME" \
    --description="DESCRIPTION" \
    --session-duration=SESSION_DURATION \
    --location=global

Ganti kode berikut:

  • WORKFORCE_POOL_ID: ID yang Anda pilih untuk mewakili Google Cloud workforce pool Anda. ID pool harus unik secara global di semua workforce identity pool di Google Cloud. Untuk mengetahui informasi tentang cara memformat ID, lihat bagian Parameter kueri dalam dokumentasi API.
  • ORGANIZATION_ID: ID organisasi numerik organisasi Anda Google Cloud untuk workforce identity pool. Workforce identity pool tersedia di semua project dan folder dalam organisasi.
  • DISPLAY_NAME: Opsional. Nama tampilan untuk kumpulan identitas tenaga kerja Anda.
  • DESCRIPTION: Opsional. Deskripsi workforce identity pool.
  • SESSION_DURATION: Opsional. Durasi sesi, dinyatakan sebagai angka yang ditambahkan dengan s—misalnya, 3600s. Durasi sesi menentukan durasi validnya token akses Google Cloud , sesi login konsol (federasi), dan sesi login gcloud CLI dari workforce pool ini. Durasi sesi default adalah satu jam (3600 detik). Nilai durasi sesi harus antara 15 menit (900 detik) dan 12 jam (43200 detik).

Konsol

Untuk membuat workforce identity pool, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Workforce Identity Pools:

    Buka Workforce Identity Pools

  2. Pilih organisasi untuk workforce identity pool Anda. Kumpulan identitas tenaga kerja tersedia di semua project dan folder dalam organisasi.

  3. Klik Buat pool dan lakukan tindakan berikut:

    1. Di kolom Name, masukkan nama tampilan pool. ID pool diambil secara otomatis dari nama saat Anda mengetik, dan ID tersebut ditampilkan di bawah kolom Nama. Anda dapat memperbarui ID pool dengan mengklik Edit di samping ID pool.

    2. Opsional: Di Deskripsi, masukkan deskripsi pool.

    3. Untuk membuat workforce identity pool, klik Berikutnya.

Durasi sesi workforce identity pool secara default adalah satu jam (3600 detik). Durasi sesi menentukan durasi validnya token akses Google Cloud , konsol (federasi), dan sesi login gcloud CLI dari workforce pool ini. Setelah membuat kumpulan, Anda dapat memperbarui kumpulan untuk menetapkan durasi sesi kustom. Durasi sesi harus dari 15 menit (900 detik) hingga 12 jam (43200 detik).

Membuat aplikasi PingFederate

Bagian ini menunjukkan cara membuat integrasi aplikasi PingFederate.

Untuk menyiapkan aplikasi PingFederate yang menggunakan protokol SAML 2.0, lakukan langkah-langkah berikut di PingFederate:

  1. Tetapkan ID Entitas SAML 2.0 IdP PingFederate Anda. Untuk mengetahui detailnya, lihat Menentukan informasi federasi.
  2. Buat koneksi SP SAML 2.0, lihat Memilih jenis koneksi SP dan lakukan hal berikut:

    1. Di Connection Type, pilih Browser SSO Profiles dan SAML 2.0 protocol.
    2. Di Impor Metadata, pilih Tidak Ada.
  3. Di General Info, tetapkan Partner's Entity ID (Connection ID) ke nilai berikut:

    https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
    
  4. Di SAML Profiles, aktifkan SP-initiated SSO. Jika Anda berencana menggunakan single sign-on (SSO) yang dimulai IdP, Anda juga dapat mengaktifkannya.

  5. Di Attribute Contract, tentukan atribut kustom (misalnya, email dan grup) yang akan diteruskan dalam pernyataan. Atribut ini dapat digunakan di Google Cloud untuk membuat kebijakan pengelolaan akses nanti.

  6. Di Attribute Contract Fulfillment, pastikan SAML_SUBJECT dipetakan ke kolom yang memiliki nilai unik untuk setiap pengguna. Misalnya, alamat email biasanya unik untuk setiap pengguna, tidak berubah, dan sering digunakan untuk merujuk ke pengguna tertentu dalam kebijakan pengelolaan akses Google Cloud .

  7. Untuk menyiapkan login konsol (gabungan), di Assertion Consumer Service URL, tambahkan URL endpoint berikut:

    https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
    

    Ganti kode berikut:

    • WORKFORCE_POOL_ID: ID workforce pool yang Anda buat sebelumnya.
    • WORKFORCE_PROVIDER_ID: ID penyedia workforce yang Anda buat nanti.
  8. Tetapkan Binding untuk endpoint ini ke POST.

  9. Untuk mengaktifkan login konsol (gabungan), di Allowable SAML Bindings, pilih Redirect.

  10. Untuk Signature Policy, pilih Sign Response As Required.

  11. Simpan dan aktifkan koneksi.

Menggunakan atribut

Bagian ini menjelaskan cara menggunakan atribut dari pernyataan SAML.

Gunakan kontrak atribut untuk menentukan atribut kustom dalam pernyataan SAML yang dihasilkan. Setelah mengonfigurasi atribut, Anda dapat menggunakannya di Google Cloud untuk membuat kebijakan pengelolaan akses. Untuk mempelajari lebih lanjut kontrak atribut, lihat Kontrak atribut dalam dokumentasi server PingFederate.

Misalnya, dalam panduan ini, kita menggunakan PingOne sebagai penyimpanan data untuk PingFederate dan memetakan kontrak atribut email, firstName, dan groups menggunakan atribut pengguna dari penyimpanan data PingOne, sebagai berikut:

Kontrak Atribut Nilai
email email
firstName name.given
groups memberOfGroupIDs

Membuat penyedia workforce identity pool PingFederate

Bagian ini menjelaskan cara membuat penyedia workforce identity pool untuk memungkinkan pengguna IdP Anda mengakses Google Cloud. Anda dapat mengonfigurasi penyedia untuk menggunakan protokol SAML.

Membuat penyedia workforce identity pool SAML 2.0

  1. Untuk mengonfigurasi aplikasi SAML, lakukan hal berikut:

    gcloud

    Untuk membuat penyedia workforce identity pool SAML, jalankan perintah berikut:

    gcloud iam workforce-pools providers create-saml WORKFORCE_PROVIDER_ID \
        --workforce-pool="WORKFORCE_POOL_ID" \
        --display-name="DISPLAY_NAME" \
        --description="DESCRIPTION" \
        --idp-metadata-path="XML_METADATA_PATH" \
        --attribute-mapping="ATTRIBUTE_MAPPING" \
        --attribute-condition="ATTRIBUTE_CONDITION" \
        --location=global
    

    Ganti kode berikut:

    • WORKFORCE_PROVIDER_ID: ID penyedia.
    • WORKFORCE_POOL_ID: ID kumpulan identitas tenaga kerja.
    • DISPLAY_NAME: nama tampilan.
    • DESCRIPTION: deskripsi.
    • XML_METADATA_PATH: jalur ke file metadata berformat XML dari PingFederate.
    • ATTRIBUTE_MAPPING: pemetaan atribut; misalnya, google.subject=assertion.subject,google.groups=assertion.attributes.groups,attribute.department=assertion.attributes.department[0].
    • ATTRIBUTE_CONDITION: kondisi atribut opsional; misalnya, untuk membatasi atribut ipaddr ke rentang IP tertentu, tetapkan kondisi ke assertion.ipaddr.startsWith('98.11.12.').

    Perintah ini menetapkan subject, groups, dan department dalam pernyataan SAML ke atribut google.subject, google.groups, dan attribute.department. Kondisi atribut juga memastikan bahwa hanya pengguna dalam rentang IP tertentu yang dapat login menggunakan penyedia workforce ini.

    Konsol

    Untuk mengonfigurasi penyedia SAML menggunakan Google Cloud konsol, lakukan langkah berikut:

    1. Di konsol Google Cloud , buka halaman Workforce Identity Pools: Buka Workforce Identity Pools
    2. Di tabel Workforce Identity Pool, pilih pool yang ingin Anda buatkan penyedia.
    3. Di bagian Penyedia, klik Tambahkan Penyedia.
    4. Di daftar Select a Provider vendor, pilih Generic Identity Provider.
    5. Di bagian Pilih protokol autentikasi, pilih SAML.
    6. Di bagian Buat penyedia, lakukan hal berikut:
      1. Di bagian Nama, masukkan nama penyedia.
      2. Opsional: Di bagian Deskripsi, masukkan deskripsi penyedia.
      3. Di IDP metadata file (XML), pilih file XML metadata dari PingFederate.
      4. Untuk membuat penyedia yang diaktifkan, pastikan Aktifkan penyedia sudah aktif.
      5. Klik Lanjutkan.
    7. Di bagian Bagikan informasi penyedia Anda, klik Lanjutkan.
    8. Opsional: Untuk mengaktifkan logging audit mendetail, di bagian Konfigurasi penyedia, di Logging mendetail, klik tombol Aktifkan logging audit nilai atribut.

      Pencatatan log audit mendetail Workforce Identity Federation mencatat informasi yang diterima dari IdP Anda ke Logging. Logging audit mendetail dapat membantu Anda memecahkan masalah konfigurasi penyedia pool identitas tenaga kerja. Untuk mempelajari cara memecahkan masalah error pemetaan atribut dengan logging audit mendetail, lihat Error pemetaan atribut umum. Untuk mempelajari harga Logging, lihat Harga Google Cloud Observability.

      Untuk menonaktifkan logging audit mendetail bagi penyedia workforce identity pool, biarkan tombol Aktifkan logging audit nilai atribut nonaktif saat Anda membuat penyedia. Untuk menonaktifkan logging audit mendetail, Anda juga dapat memperbarui penyedia.

    9. Untuk membuat penyedia, klik Kirim.

    Setelah penyedia dibuat, Anda akan dialihkan ke halaman atribut penyedia.

    Untuk mengonfigurasi pemetaan dan kondisi atribut, lakukan hal berikut:

    1. Saat diminta, login ke IdP eksternal Anda untuk memvalidasi pemetaan atribut default.
    2. Di halaman atribut penyedia, lihat dan edit pemetaan dan kondisi atribut:

      1. Untuk menambahkan atau mengedit pemetaan atribut, lakukan hal berikut:

        1. Klik Tambahkan pemetaan untuk menambahkan pemetaan baru, atau edit pemetaan yang ada.
        2. Di kolom Google n, dengan n adalah angka, pilih kunci yang didukung Google Cloud.
        3. Di kolom SAML n yang sesuai, masukkan nama atribut IdP atau ekspresi CEL—misalnya:

          google.subject=assertion.subject,
          google.groups=assertion.attributes['https://example.com/aliases'],
          attribute.costcenter=assertion.attributes.costcenter[0]
          
      2. Untuk menambahkan kondisi atribut, lakukan hal berikut:

        1. Klik Add condition.
        2. Di kolom Kondisi Atribut, masukkan kondisi dalam format CEL—misalnya, assertion.ipaddr.startsWith('98.11.12.').
    3. Untuk memvalidasi pemetaan, klik Simpan dan ambil ulang token.

    4. Untuk menyelesaikan penyiapan, klik Simpan dan keluar.

Mengelola akses ke Google Cloud resource

Bagian ini menunjukkan cara mengelola akses ke Google Cloud resource untuk pengguna PingFederate.

Project contoh yang digunakan dalam panduan ini dapat berbeda dengan project yang Anda gunakan untuk menyiapkan Workforce Identity Federation.

Anda dapat mengelola peran untuk satu identitas, grup identitas, atau keseluruhan pool. Untuk mengetahui informasi selengkapnya, lihat ID principal tenaga kerja untuk kebijakan izin.

Menggunakan atribut departemen yang dipetakan

Untuk memberikan peran Storage Admin (roles/storage.admin) ke semua identitas dalam departemen tertentu untuk project TEST_PROJECT_ID, jalankan perintah berikut:

gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"

Ganti kode berikut:

  • TEST_PROJECT_ID: project ID.
  • WORKFORCE_POOL_ID: ID kumpulan identitas tenaga kerja.
  • DEPARTMENT_VALUE: nilai attribute.department yang dipetakan.

Menggunakan grup yang dipetakan

Untuk memberikan peran Storage Admin (roles/storage.admin) ke semua identitas dalam grup GROUP_ID untuk project TEST_PROJECT_ID, jalankan perintah berikut:

gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
    --role="roles/storage.admin" \
    --member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"

Ganti kode berikut:

  • TEST_PROJECT_ID: project ID.
  • WORKFORCE_POOL_ID: ID kumpulan identitas tenaga kerja.
  • GROUP_ID: grup dalam klaim google.groups yang dipetakan.

Login dan uji akses

Di bagian ini, Anda akan login sebagai pengguna workforce identity pool dan menguji akses Anda.

Login

login konsol (gabungan)

Untuk login ke konsol Google Cloud Workforce Identity Federation, yang juga dikenal sebagai konsol (gabungan), lakukan tindakan berikut:

  1. Buka halaman login konsol (gabungan).

    Buka konsol (gabungan)

  2. Masukkan nama penyedia, dengan format berikut:
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
  3. Masukkan kredensial PingFederate Anda saat diminta.

Login berbasis browser gcloud CLI

Untuk login ke gcloud CLI menggunakan alur login berbasis browser:

Jalankan perintah berikut untuk membuat file konfigurasi login:

Linux and macOS

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=LOGIN_CONFIG_PATH

Windows (PowerShell)

gcloud iam workforce-pools create-login-config `
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
    --output-file=LOGIN_CONFIG_PATH

Ganti kode berikut:

  • WORKFORCE_POOL_ID: ID pool Federasi Identitas Tenaga Kerja.
  • WORKFORCE_PROVIDER_ID: ID penyedia Workforce Identity Federation.
  • LOGIN_CONFIG_PATH: Jalur untuk menulis file konfigurasi login ke. Contoh, login-config.json.

File konfigurasi login berisi endpoint yang digunakan oleh gcloud CLI untuk mengaktifkan alur autentikasi berbasis browser dan menetapkan audience ke IdP yang dikonfigurasi di penyedia workforce identity pool. File tidak berisi informasi rahasia.

Konten file konfigurasi login akan terlihat seperti berikut:

{
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect"
}

Arahkan ke file konfigurasi login dengan variabel lingkungan, properti dalam konfigurasi gcloud CLI aktif, atau gunakan secara langsung dengan perintah gcloud auth login:

Variabel lingkungan

Untuk menggunakan file konfigurasi login dengan variabel lingkungan, selesaikan petunjuk berikut:

  1. Tetapkan variabel lingkungan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE ke jalur file konfigurasi login.
  2. Jalankan perintah berikut:

    gcloud auth login
  3. gcloud CLI mereferensikan variabel lingkungan untuk menemukan file konfigurasi login, lalu memulai proses autentikasi. Ikuti alur berbasis browser untuk mengautentikasi dan mengizinkan gcloud CLI mengakses resource atas nama Anda untuk perintah mendatang.

Untuk berhenti menggunakan file konfigurasi login untuk perintah gcloud auth login, hapus variabel lingkungan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

Konfigurasi gcloud CLI

Untuk menggunakan file konfigurasi login dengan properti konfigurasi gcloud CLI, selesaikan petunjuk berikut:

  1. Tetapkan properti auth/login_config_file konfigurasi gcloud CLI aktif ke jalur file konfigurasi login dengan perintah berikut:

    gcloud config set auth/login_config_file LOGIN_CONFIG_PATH
  2. Jalankan perintah berikut:

    gcloud auth login
  3. gcloud CLI mereferensikan properti konfigurasi untuk menemukan file konfigurasi login, lalu memulai proses autentikasi. Ikuti alur berbasis browser untuk mengautentikasi dan mengizinkan gcloud CLI mengakses resource atas nama Anda untuk perintah mendatang.

Untuk berhenti menggunakan file konfigurasi login untuk perintah gcloud auth login, hapus setelan properti dengan perintah berikut:

gcloud config unset auth/login_config_file

gcloud auth login

Untuk menggunakan file konfigurasi login secara langsung dengan perintah gcloud auth login, selesaikan petunjuk berikut:

  • Jika Anda menggunakan flag --activate saat membuat file konfigurasi login, jalankan perintah berikut:

    gcloud auth login
  • Jika Anda tidak menggunakan flag --activate saat membuat file konfigurasi login, jalankan perintah berikut:

    Linux and macOS

    gcloud auth login \
        --login-config=LOGIN_CONFIG_PATH

    Windows (PowerShell)

    gcloud auth login `
        --login-config=LOGIN_CONFIG_PATH

    Ganti LOGIN_CONFIG_PATH dengan jalur file konfigurasi login Anda.

Perintah gcloud auth login menyimpan kredensial akses di direktori beranda Anda. Principal yang diautentikasi menjadi principal aktif dalam konfigurasi gcloud CLI aktif Anda. Kecuali diganti, gcloud CLI menggunakan kredensial tersimpan ini untuk mengakses Google Cloud.

Login headless gcloud CLI

Untuk login ke PingFederate dengan gcloud CLI menggunakan protokol SAML, lakukan langkah berikut:

  1. Buat pengguna login ke aplikasi PingFederate dan dapatkan respons SAML.
  2. Simpan respons SAML yang ditampilkan oleh PingFederate di lokasi yang aman di komputer lokal Anda. Simpan jalur dalam variabel lingkungan—misalnya: SAML_ASSERTION_PATH=/path/to/assertion.xml.
  3. Buat file konfigurasi:

    gcloud iam workforce-pools create-cred-config \
        locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
        --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
        --credential-source-file=SAML_ASSERTION_PATH \
        --workforce-pool-user-project=PROJECT_ID \
        --output-file=config.json
    

    Ganti kode berikut:

    • SAML_ASSERTION_PATH: jalur file pernyataan SAML.
    • PROJECT_ID: project ID.
  4. File konfigurasi yang dihasilkan akan terlihat mirip dengan berikut:

    {
      "type": "external_account",
      "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
      "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
      "token_url": "https://sts.googleapis.com/v1/token",
      "credential_source": {
        "file": "SAML_ASSERTION_PATH"
      },
      "workforce_pool_user_project": "PROJECT_ID"
    }
    
  5. Untuk login ke gcloud CLI menggunakan pertukaran token, jalankan perintah berikut:

    gcloud auth login --cred-file=config.json
    

    gcloud kemudian secara transparan menukar kredensial PingFederate Anda dengan token akses sementara Google Cloud , sehingga Anda dapat melakukan panggilan gcloud lainnya ke Google Cloud. Outputnya mirip dengan hal berikut ini:

    Authenticated with external account user credentials for: [principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

  6. Untuk mencantumkan akun berkredensial dan akun aktif, jalankan perintah berikut:

    gcloud auth list
    

Menguji akses

Anda memiliki akses ke layanan Google Cloud yang mendukung Workforce Identity Federation dan yang aksesnya diberikan kepada Anda. Sebelumnya dalam panduan ini, Anda telah memberikan peran Storage Admin ke semua identitas dalam departemen atau grup tertentu untuk project TEST_PROJECT_ID. Anda dapat menguji apakah Anda memiliki akses dengan mencantumkan bucket Cloud Storage.

login konsol (gabungan)

Untuk memverifikasi akses Anda di konsol (gabungan), lakukan hal berikut:

  1. Buka halaman Cloud Storage.
  2. Pastikan Anda dapat melihat daftar bucket yang ada untuk project TEST_PROJECT_ID.

gcloud CLI

Untuk mencantumkan bucket dan objek Cloud Storage untuk project yang dapat Anda akses, jalankan perintah berikut:

gcloud alpha storage ls --project="TEST_PROJECT_ID"

Akun utama harus memiliki izin serviceusage.services.use pada project yang ditetapkan di sesi gcloud CLI: PROJECT_ID.

Langkah berikutnya