Mengonfigurasi Workforce Identity Federation dengan PingOne AIC

Dokumen ini menunjukkan cara mengonfigurasi Workforce Identity Federation dengan PingOne Advanced Identity Cloud (AIC) sebagai penyedia identitas (IdP) dan mengelola akses ke Google Cloud. Setelah Anda mengonfigurasi IdP AIC PingOne, pengguna yang difederasi 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.

   Catatan: Jika Anda telah menginstal gcloud CLI sebelumnya, pastikan Anda memiliki versi terbaru dengan menjalankan gcloud components update.

Membuat IdP yang dihosting

1. Di Native Consoles > Access Management, buka Realms > REALM_NAME > Dashboard, lalu klik SAML Applications.
2. Klik Tambahkan Penyedia Entitas > Dihosting.

3. Masukkan ID Entitas. Catat nilai ini untuk digunakan nanti.

   Catatan: Advanced Identity Cloud memangkas beberapa spasi menjadi satu spasi dalam nilai seperti ID entity. Misalnya, jika nilai MyEntityID (satu spasi) ada, menambahkan entitas baru bernama My Entity ID (beberapa spasi) akan menyebabkan error karena Advanced Identity Cloud memperlakukannya sebagai identik.
   1. Pastikan nilai URL Dasar Penyedia Entitas sudah benar. Advanced Identity Cloud menggunakan nilai ini untuk semua endpoint terkait SAML 2.0.
   2. Di bagian Meta Aliases, berikan nilai yang kompatibel dengan URL di properti Identity Provider Meta Alias. Alias ini harus unik dalam lingkaran kepercayaan.
   3. Klik Create.
   4. Di tab Assertion Processing, di bagian Attribute Mapper, petakan nama atribut SAML ke nama atribut lokal. Nama atribut SAML adalah nama yang digunakan dalam pernyataan.
   5. Klik Tambahkan atau Perbarui untuk setiap pemetaan.
   6. Klik Simpan Perubahan.

Menggunakan atribut

Bagian ini menjelaskan cara menggunakan atribut dari pernyataan SAML.

Dalam contoh berikut, atribut dalam pernyataan SAML dipetakan ke atribut lokal:

Atribut SAML	Atribut lokal
IDPEmail	mail
FirstName	givenName
groups	groups

Siapkan atribut yang diperlukan di bagian pemetaan atribut. Anda akan memetakan atribut ini saat membuat penyedia kumpulan identitas tenaga kerja nanti dalam panduan ini.

Mengekspor metadata penyedia

Anda dapat mengakses metadata SAML 2.0 untuk penyedia yang dihosting dengan salah satu cara berikut:

• Over REST

  Jalankan perintah berikut:

  curl --output METADATA_XML \
      "https://TENANT_ENV_FQDN/am/ExportSamlMetadata?entityid=ENTITY_ID&realm=/REALM"
  

• Di browser

  Buka URL metadata lingkungan tenant Anda di browser untuk mendownload file XML: https://TENANT_ENV_FQDN/am/ExportSamlMetadata?entityid=ENTITY_ID&realm=/REALM

1. Simpan file XML ke komputer lokal Anda.

Mengimpor Google sebagai SP jarak jauh

1. Siapkan Google Cloud XML metadata SP. Gunakan template berikut, dengan mengganti nilai placeholder:

   <?xml version="1.0" encoding="UTF-8"?>
   <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID">
      <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
         <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
         <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
         <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID" index="0" isDefault="true"/>
      </md:SPSSODescriptor>
   </md:EntityDescriptor>
   

2. Impor metadata dengan salah satu cara berikut:

   • Di konsol

     1. Di konsol admin AIC PingOne, buka SAML Applications.
     2. Klik Tambahkan Penyedia Entitas > Jarak Jauh.
     3. Upload file XML metadata SP Google Cloud yang baru saja Anda buat.
     4. Klik Create.

   • Over REST

     1. Konversi metadata XML menjadi string berenkode base64url.
     2. Mendapatkan token akses.

     3. Jalankan perintah berikut:

        curl --request POST \
            --header 'authorization: Bearer ACCESS_TOKEN' \
            --header 'Content-Type: application/json' \
            --header 'Accept-API-Version: resource=1.0' \
            --data-raw '{"standardMetadata": "BASE64URL_ENCODED_METADATA"}' \
            'https://TENANT_ENV_FQDN/am/json/realms/root/realms/alpha/realm-config/saml2/remote?_action=importEntity'
        

Buat lingkaran kepercayaan (CoT)

1. Buka Realms > REALM_NAME > Applications > Federation > Circles of Trust.
2. Klik Tambahkan Lingkaran Kepercayaan.
3. Masukkan nama, lalu klik Buat.
4. Di halaman Circle of Trust, di properti Entity Providers, pilih IdP yang dihosting dan SP jarak jauh Google Cloud .
5. Klik Simpan Perubahan.

Membuat penyedia workforce identity pool PingOne AIC

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

1. Untuk membuat penyedia workforce identity pool SAML, Anda harus memastikan bahwa metadata penyedia identitas Anda menyertakan setidaknya ID entitas SAML, URL single sign-on, dan satu kunci publik penandatanganan. Untuk melakukannya, ikuti langkah-langkah ini:

   gcloud

   1. Simpan metadata SAML dari aplikasi AIC PingOne Anda.

   2. 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 yang Anda ekspor dari PingOne AIC.
      • 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, Anda dapat menetapkan kondisi assertion.ipaddr.startsWith('98.11.12.').

      Untuk mengetahui informasi selengkapnya, lihat Pemetaan atribut.

      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 yang Anda ekspor dari PingOne AIC.
      4. Pastikan bagian Aktifkan provider sudah aktif.
      5. Klik Lanjutkan.
   7. Di bagian Bagikan informasi penyedia Anda, klik Lanjutkan.

   8. Di bagian Konfigurasi penyedia, lakukan hal berikut:

      1. Di Pemetaan atribut, masukkan ekspresi CEL untuk google.subject (misalnya, assertion.subject).

      2. Opsional: Untuk memasukkan pemetaan lain, klik Tambahkan pemetaan, lalu masukkan pemetaan lain, misalnya:

         google.subject=assertion.subject,
         google.groups=assertion.attributes['https://example.com/aliases'],
         attribute.costcenter=assertion.attributes.costcenter[0]
         

      3. Opsional: Untuk menambahkan kondisi atribut, klik Tambahkan kondisi, lalu masukkan ekspresi CEL yang mewakili kondisi atribut. Misalnya, untuk membatasi atribut ipaddr ke rentang IP tertentu, Anda dapat menetapkan kondisi assertion.attributes.ipaddr.startsWith('98.11.12.'). Contoh kondisi ini memastikan bahwa hanya pengguna dengan alamat IP yang diawali dengan 98.11.12. yang dapat login menggunakan penyedia workforce ini.

   9. Untuk mengaktifkan logging audit mendetail, di Logging mendetail, klik tombol Aktifkan logging audit nilai atribut.

   10. Untuk membuat penyedia, klik Kirim.

Mengelola akses ke Google Cloud resource

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

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, sekelompok identitas, atau seluruh pool. Untuk mengetahui informasi selengkapnya, lihat Merepresentasikan pengguna workforce identity pool dalam kebijakan IAM.

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

Masukkan kredensial AIC PingOne Anda saat diminta.

Login berbasis browser Google Cloud CLI

Untuk login ke gcloud CLI menggunakan alur login berbasis browser:

Untuk membuat file konfigurasi login, jalankan perintah berikut. Secara opsional, Anda dapat mengaktifkan file sebagai default untuk gcloud CLI dengan menambahkan flag --activate. Kemudian, Anda dapat menjalankan gcloud auth login tanpa menentukan jalur file konfigurasi setiap kali.

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

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool
• PROVIDER_ID: ID penyedia
• LOGIN_CONFIG_FILE_PATH: jalur ke file konfigurasi yang Anda tentukan—misalnya, login.json

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

Outputnya akan terlihat mirip seperti berikut:

{
  "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"
}

Perhatian: Sebaiknya Anda terlebih dahulu memastikan bahwa konten file ini benar, lalu amankan file tersebut—misalnya, dengan menjadikannya hanya baca dan membatasi akses dengan ACL. File tidak divalidasi; pelaku berbahaya yang memiliki akses tulis ke file ini dapat mengubah endpoint dan menangkap kredensial.

Untuk menghentikan gcloud auth login menggunakan file konfigurasi ini secara otomatis, Anda dapat membatalkannya dengan menjalankan gcloud config unset auth/login_config_file.

Untuk mengautentikasi menggunakan autentikasi login berbasis browser, Anda dapat menggunakan salah satu metode berikut:

• Jika Anda menggunakan flag --activate saat membuat file konfigurasi, atau jika Anda mengaktifkan file konfigurasi dengan gcloud config set auth/login_config_file, gcloud CLI akan menggunakan file konfigurasi Anda secara otomatis:

  gcloud auth login

• Untuk login dengan menentukan lokasi file konfigurasi, jalankan perintah berikut:

  gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH

• Untuk menggunakan variabel lingkungan guna menentukan lokasi file konfigurasi, tetapkan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE ke jalur konfigurasi.

Untuk menghentikan penggunaan file konfigurasi login, lakukan langkah berikut:

• Jika Anda menggunakan flag --activate saat membuat file konfigurasi, atau jika Anda mengaktifkan file konfigurasi dengan gcloud config set auth/login_config_file, Anda harus menjalankan perintah berikut untuk membatalkan penetapannya:

  gcloud config unset auth/login_config_file

• Hapus variabel lingkungan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, jika telah ditetapkan.

Login headless gcloud CLI

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

1. Buat pengguna login ke aplikasi AIC PingOne dan dapatkan respons SAML.
2. Simpan respons SAML yang ditampilkan oleh PingOne AIC di lokasi yang aman di komputer lokal Anda. Simpan jalur dalam variabel lingkungan—misalnya: SAML_ASSERTION_PATH=/tmp/saml_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 AIC PingOne 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 dapat mengakses layanan Google Cloud yang mendukung Workforce Identity Federation 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

• Menghapus pengguna Workforce Identity Federation dan datanya.
• Pelajari Google Cloud produk mana yang mendukung Workforce Identity Federation.
• Menyiapkan akses pengguna ke konsol (gabungan).