Mendapatkan token berumur pendek untuk workforce identity federation

Panduan ini menunjukkan cara menggunakan workforce identity pool dan penyedia workforce identity pool untuk mendapatkan token yang memiliki masa aktif singkat dari Security Token Service. Anda dapat menggunakan token tersebut untuk mengakses resource Google Cloud yang mendukung workforce identity federation dan yang telah diberikan akses kepada Anda.

Catatan: Prosedur yang dijelaskan dalam panduan ini dapat digunakan pada mesin headless.

Anda mendapatkan token jangka pendek dengan mengikuti proses ini:

1. Dapatkan kredensial dari penyedia identitas tepercaya.
2. Tukarkan kredensial dengan token dari Security Token Service.

Sebelum memulai

1. Konfigurasikan workforce identity federation atau, untuk petunjuk khusus IdP, lihat panduan berikut:

   • Mengonfigurasi workforce identity federation berbasis Azure AD
   • Mengonfigurasi workforce identity federation berbasis Okta

2. Anda harus mengetahui ID workforce pool atau ID penyedia.

3. Pastikan Anda memiliki izin Identity and Access Management (IAM) serviceusage.services.use. Peran dengan hak istimewa terendah yang berisi izin ini adalah Service Usage Consumer (roles/serviceusage.serviceUsageConsumer).

4. Aktifkan API IAM and Security Token Service.

   Mengaktifkan API

5. Instal Google Cloud CLI, lalu initialize dengan menjalankan perintah berikut:

   gcloud init

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

Tukarkan kredensial eksternal dengan token akses Google Cloud

Bagian ini menunjukkan cara menggunakan Security Token Service untuk menukar kredensial eksternal Anda dengan token akses yang memberikan akses ke Google Cloud. Anda dapat melakukannya menggunakan gcloud CLI, REST API, dan Library Klien Cloud, seperti yang dijelaskan nanti dalam panduan ini.

Jika memerlukan akses jangka panjang, Anda dapat mengonfigurasi proses yang berjalan lama untuk memperbarui kredensial secara terus-menerus di mesin tersebut. Atau, Anda dapat menjalankan server lokal di latar belakang dengan endpoint yang menampilkan kredensial.

Login berbasis browser dengan gcloud CLI

Bagian ini menjelaskan cara mengonfigurasi gcloud CLI untuk menggunakan alur login berbasis browser. Untuk melakukannya, buat file konfigurasi login, lalu referensikan file tersebut dalam panggilan ke gcloud auth login atau aktifkan agar dapat digunakan secara default.

Membuat file konfigurasi login

Untuk membuat file konfigurasi login, jalankan perintah berikut. Secara opsional, Anda dapat mengaktifkan ile sebagai default untuk gcloud CLI dengan menggunakan flag --activate.

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

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool
• PROVIDER_ID: ID penyedia
• LOGIN_CONFIG_FILE: 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 penyedia yang Anda buat sebelumnya dalam panduan ini. File tidak berisi informasi rahasia apa pun.

Outputnya terlihat mirip dengan yang berikut ini:

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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.

Login menggunakan autentikasi berbasis browser

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
  

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

Nonaktifkan login berbasis browser

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.

Gunakan file konfigurasi untuk login

Sebagai alternatif untuk login berbasis browser, bagian ini menunjukkan berbagai cara dalam menggunakan file konfigurasi kredensial untuk memberikan akses ke tindakan Google Cloud yang diautentikasi. Anda tidak harus login ke gcloud CLI untuk menyiapkan file konfigurasi.

Cara Anda menyiapkan file konfigurasi bergantung pada apakah IdP Anda menggunakan OIDC atau SAML.

OIDC

Anda dapat mengambil kredensial yang digunakan untuk menyiapkan file konfigurasi dari sumber berikut:

• Kredensial dari file
• Kredensial dari URL
• Kredensial noninteraktif dari file yang dapat dieksekusi
• Kredensial interaktif dari file yang dapat dieksekusi

Kredensial dari file

Token dimuat dari file. Proses lain harus memuat ulang file ini dengan token OIDC baru sebelum masa berlaku token lama berakhir. Misalnya, jika masa berlaku token adalah satu jam, Anda harus memperbarui file sebelum satu jam berakhir.

Untuk membuat file konfigurasi dengan kredensial dari file, jalankan perintah berikut:

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

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool
• PROVIDER_ID: ID penyedia
• PATH_TO_OIDC_TOKEN: jalur ke file kredensial IdP OIDC
• WORKFORCE_POOL_USER_PROJECT: nomor atau ID project yang terkait dengan project pengguna workforce pool.

Akun utama harus memiliki izin serviceusage.services.use di project ini.

Menjalankan perintah ini akan menghasilkan file konfigurasi IdP OIDC yang mirip dengan berikut ini:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

Kredensial dari URL

Token dimuat dari server lokal dengan endpoint yang merespons permintaan HTTP GET. Respons harus berupa token ID OIDC, baik dalam format teks biasa maupun JSON.

Untuk membuat file konfigurasi dengan kredensial dari URL, jalankan perintah berikut:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool.
• PROVIDER_ID: ID penyedia.
• URL_TO_RETURN_OIDC_ID_TOKEN: URL yang akan dipanggil untuk mengambil kredensial OIDC, seperti token ID OIDC—misalnya: http://localhost:5000/token.
• WORKFORCE_POOL_USER_PROJECT: nomor project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki serviceusage.services.use permission pada project ini.

Menjalankan perintah ini akan menghasilkan file konfigurasi IdP OIDC yang mirip dengan berikut ini:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

Kredensial noninteraktif dari file yang dapat dieksekusi

Token dimuat dari file lokal yang dapat dieksekusi. File yang dapat dieksekusi harus memberikan token ID OIDC yang valid dan belum habis masa berlakunya dalam format JSON ke stdout:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Kolom ini diperlukan agar respons berhasil, kecuali expiration_time. Kolom expiration_time hanya diperlukan jika file output telah ditentukan dalam konfigurasi kredensial.

File yang dapat dieksekusi harus memunculkan error ke stdout dalam format JSON berikut:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Kolom ini wajib diisi untuk respons error. Kolom kode dan pesan digunakan oleh library klien saat menampilkan error yang sesuai.

Perintah ini dapat menampilkan kolom berikut:

• version: versi output JSON. Hanya versi 1 yang didukung.

• success: status respons. Jika statusnya adalah true, file yang dapat dieksekusi harus keluar dengan kode keluar 0 dan respons harus berisi kolom berikut:

  • token_type: id_token
  • expiration_time, jika file output ditentukan dalam konfigurasi kredensial

  Jika statusnya adalah false, file yang dapat dieksekusi harus keluar dengan nilai selain nol dan respons harus berisi kolom berikut:

  • code
  • message

• token_type: jenis token subjek pihak ketiga, yang harus berupa urn:ietf:params:oauth:token-type:id_token

• id_token: token OIDC pihak ketiga

• expiration_time: waktu habis masa berlaku token OIDC pihak ketiga dalam detik (waktu epoch Unix)

• code: string kode error

• message: pesan error

Library klien mengisi variabel lingkungan berikut saat file yang dapat dieksekusi dijalankan:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: kolom audience dari konfigurasi kredensial. Selalu ada.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: jenis token subjek yang diharapkan. Selalu ada.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: lokasi file output dari konfigurasi kredensial. Hanya ada jika ditentukan dalam konfigurasi kredensial.

Variabel lingkungan ini dapat digunakan oleh file yang dapat dieksekusi untuk menghindari hardcode nilai-nilai ini.

Untuk mengaktifkan metode sumber kredensial ini dengan library klien, variabel lingkungan GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES harus ditetapkan ke 1.

Untuk membuat file konfigurasi dengan kredensial dari file yang dapat dieksekusi, jalankan perintah berikut:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool.
• PROVIDER_ID: ID penyedia.
• EXECUTABLE_COMMAND: perintah lengkap, termasuk argumen, yang akan dijalankan untuk mengambil token subjek, seperti token ID OIDC, dalam format berikut: --executable-command="/path/to/command --foo=bar".
• EXECUTABLE_TIMEOUT: (opsional) durasi, dalam milidetik, untuk menunggu file yang dapat dieksekusi dijalankan (defaultnya adalah 30 detik).
• EXECUTABLE_OUTPUT_FILE: (opsional) jalur file ke kredensial pihak ketiga yang dihasilkan oleh file yang dapat dieksekusi. Hal ini berguna untuk menyimpan kredensial dalam cache. Library Autentikasi akan memeriksa jalur ini terlebih dahulu sebelum menjalankan file yang dapat dieksekusi.
• WORKFORCE_POOL_USER_PROJECT: nomor atau ID project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki izin serviceusage.services.use yang ditetapkan di project ini.

Menjalankan perintah ini akan menghasilkan file konfigurasi IdP OIDC yang mirip dengan berikut ini:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Kredensial interaktif dari file yang dapat dieksekusi

Anda dapat menyediakan file yang dapat dieksekusi yang berinteraksi dengan pengguna melalui stdin dan stdout. Jika pengguna berhasil login, file yang dapat dieksekusi akan menulis [kredensial yang valid dan belum habis masa berlakunya] ke file yang ditentukan.

Untuk menggunakan mode ini, diperlukan flag berikut:

• --executable-output-file: file tempat file yang dapat dieksekusi menulis informasi kredensial
• --exeutable-interactive-timeout-millis: nilai selain nol yang menunjukkan mode interaktif dan menyetel waktu tunggu—misalnya, 6000 untuk waktu tunggu 60 detik

Kolom berikut diperlukan agar respons berhasil, dengan pengecualian expiration_time:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

File yang dapat dieksekusi harus menuliskan error apa pun ke file yang ditentukan di --executable-output-file dalam format JSON berikut. Kolom berikut diperlukan saat menampilkan respons error.

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Kolom code dan message harus menunjukkan error yang sesuai. Kolom ini digunakan oleh library klien saat menampilkan error.

Setelah berhasil dijalankan, perintah akan menampilkan kolom yang sama, baik hasil kredensial interaktif maupun non-interaktif dari file yang dapat dieksekusi di atas.

Variabel lingkungan juga sama dengan kredensial normal dari file yang dapat dieksekusi.

Untuk membuat kredensial interaktif dari file yang dapat dieksekusi, tambahkan parameter --executable-interactive-timeout-millis dan parameter --executable-output-file.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool.
• PROVIDER_ID: ID penyedia.
• EXECUTABLE_COMMAND: perintah lengkap, termasuk argumen, yang akan dijalankan untuk mengambil token subjek, yang diformat sebagai berikut: --executable-command="/path/to/command --arg1=val1 --arg2=val2"
• EXECUTABLE_INTERACTIVE_TIMEOUT: durasi, dalam milidetik, untuk menunggu file yang dapat dieksekusi dijalankan.
• EXECUTABLE_OUTPUT_FILE: jalur file ke kredensial pihak ketiga yang dihasilkan oleh file yang dapat dieksekusi. Jalur ini berguna untuk menyimpan kredensial dalam cache. Library Autentikasi akan memeriksa jalur ini terlebih dahulu sebelum menjalankan file yang dapat dieksekusi.
• WORKFORCE_POOL_USER_PROJECT: nomor atau ID project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki izin serviceusage.services.use di project ini.

Menjalankan perintah ini akan menghasilkan file konfigurasi IdP OIDC yang mirip dengan berikut ini:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

Catatan: Kolom timeout_millis ditampilkan karena dalam beberapa kasus, file yang dapat dieksekusi interaktif juga dapat berjalan dalam mode non-interaktif. Dalam mode interaktif, perintah menampilkan waktu tunggu default.

SAML

Anda dapat mengambil kredensial yang digunakan untuk menyiapkan file konfigurasi dari sumber berikut:

• Kredensial dari file
• Kredensial dari URL
• Kredensial dari file yang dapat dieksekusi
• Kredensial dari file yang dapat dieksekusi untuk mode interaktif gcloud

Kredensial dari file

Pernyataan dimuat dari file. Proses lain harus memuat ulang file ini dengan pernyataan SAML berenkode base64 yang baru sebelum masa berlaku pernyataan lama berakhir. Misalnya, jika masa berlaku pernyataan adalah satu jam, Anda harus memperbarui file sebelum satu jam berakhir.

Catatan: Anda harus meneruskan flag --subject-token-type=urn:ietf:params:oauth:token-type:saml2 saat membuat file konfigurasi.

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

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool.
• PROVIDER_ID: ID penyedia.
• CREDENTIAL_FILE: jalur ke file kredensial yang dihasilkan oleh IdP.
• WORKFORCE_POOL_USER_PROJECT: nomor atau ID project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki serviceusage.services.use permission di project ini.

Kredensial dari URL

Pernyataan dimuat dari server lokal dengan endpoint yang merespons permintaan GET HTTP. Responsnya harus berupa pernyataan SAML berenkode base64 atau JSON yang berisi pernyataan SAML berenkode base64.

Untuk menggunakan kredensial dari URL, gunakan flag --credential-source-url:

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

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool.
• PROVIDER_ID: ID penyedia.
• CREDENTIAL_URL: URL endpoint server lokal.
• WORKFORCE_POOL_USER_PROJECT: nomor atau ID project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki serviceusage.services.use permission pada project ini.

Kredensial dari file yang dapat dieksekusi

Pernyataan dimuat dari file lokal yang dapat dieksekusi. File yang dapat dieksekusi harus memberikan pernyataan SAML yang valid dan belum habis masa berlakunya dalam format JSON ke stdout.

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Kolom ini diperlukan agar respons berhasil, kecuali expiration_time. Kolom expiration_time hanya diperlukan jika file output ditentukan dalam konfigurasi kredensial.

Jika terjadi error, error tersebut harus ditampilkan oleh file yang dapat dieksekusi dalam format JSON berikut ke stdout:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Kolom ini wajib diisi untuk respons error. Kolom kode dan pesan digunakan oleh library klien saat menampilkan error yang sesuai.

Perintah ini dapat menampilkan kolom berikut:

• version: versi output JSON. Hanya versi 1 yang didukung.

• success: status respons. Jika statusnya adalah true, file yang dapat dieksekusi harus keluar dengan kode keluar 0 dan respons harus berisi kolom berikut:

  • token_type: saml_response
  • expiration_time, jika file output ditentukan dalam konfigurasi kredensial

  Jika statusnya adalah false, file yang dapat dieksekusi harus keluar dengan nilai selain nol dan respons harus berisi kolom berikut: + code + message

• token_type: jenis token subjek pihak ketiga, yang harus berupa urn:ietf:params:oauth:token-type:saml2

• saml_response: respons SAML pihak ketiga

• expiration_time: waktu habis masa berlaku respons SAML pihak ketiga dalam detik (waktu epoch Unix)

• code: string kode error

• message: pesan error

Library klien mengisi variabel lingkungan berikut saat file yang dapat dieksekusi dijalankan:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: kolom audience dari konfigurasi kredensial. Selalu ada.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: jenis token subjek yang diharapkan. Selalu ada.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: lokasi file output dari konfigurasi kredensial. Hanya ada jika ditentukan dalam konfigurasi kredensial.

Catatan: File yang dapat dieksekusi dapat menggunakan variabel lingkungan ini untuk menghindari hardcode nilai-nilai ini.

Untuk mengaktifkan metode sumber kredensial ini dengan library klien, tetapkan variabel lingkungan GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES ke 1.

Untuk membuat file konfigurasi dengan kredensial dari file yang dapat dieksekusi, jalankan perintah berikut:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool.
• PROVIDER_ID: ID penyedia.
• EXECUTABLE_COMMAND: perintah lengkap, termasuk argumen, yang akan dijalankan untuk mengambil token subjek, dalam format berikut: --executable-command="/path/to/command --foo=bar".
• EXECUTABLE_TIMEOUT: (opsional) durasi dalam milidetik, untuk menunggu file yang dapat dieksekusi dijalankan (defaultnya adalah 30 detik).
• EXECUTABLE_OUTPUT_FILE: (opsional) jalur file ke kredensial 3PI yang dihasilkan oleh file yang dapat dieksekusi. Hal ini berguna untuk menyimpan kredensial dalam cache. Library Autentikasi memeriksa keberadaannya sebelum menjalankan file yang dapat dieksekusi.
• WORKFORCE_POOL_USER_PROJECT: nomor project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki izin serviceusage.services.use di project ini.

Menjalankan perintah ini akan menghasilkan file konfigurasi IdP SAML yang mirip dengan berikut ini:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Kredensial dari file yang dapat dieksekusi untuk mode interaktif gcloud

File yang dapat dieksekusi berinteraksi dengan pengguna melalui command line.

Pada perintah sebelumnya, ganti perintah berikut:

• EXECUTABLE_OUTPUT_FILE: (wajib) jalur ke file yang memberikan kredensial yang dihasilkan oleh file yang dapat dieksekusi.
• EXECUTABLE_TIMEOUT: (wajib) nilai waktu tunggu selain nol juga menandakan perintah untuk menggunakan mode interaktif.

    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

Kolom ini diperlukan agar respons berhasil, kecuali expiration_time. Jika expiration_time tidak ada, maka akan dianggap sebagai sinyal bahwa kita akan menjalankan file yang dapat dieksekusi dengan cara apa pun.

File yang dapat dieksekusi harus memunculkan error ke executable-output-file dalam format JSON berikut:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Kolom ini wajib diisi untuk respons error. Kolom kode dan pesan digunakan oleh library klien saat menampilkan error yang sesuai.

Kolom yang ditampilkan oleh perintah untuk eksekusi yang berhasil sama persis dengan hasil kredensial dari file normal yang dapat dieksekusi di atas.

Variabel lingkungan juga sama dengan kredensial normal dari file yang dapat dieksekusi.

Untuk membuat kredensial interaktif dari file yang dapat dieksekusi, tambahkan parameter --executable-interactive-timeout-millis.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

• WORKFORCE_POOL_ID: ID workforce pool.
• PROVIDER_ID: ID penyedia.
• EXECUTABLE_COMMAND: perintah lengkap, termasuk argumen, yang akan dijalankan untuk mengambil token subjek, yang diformat sebagai berikut: --executable-command="/path/to/command --foo=bar").
• EXECUTABLE_INTERACTIVE_TIMEOUT: durasi dalam milidetik untuk menunggu file yang dapat dieksekusi dijalankan.
• EXECUTABLE_OUTPUT_FILE: jalur file ke kredensial pihak ketiga yang dihasilkan oleh file yang dapat dieksekusi. Hal ini berguna untuk menyimpan kredensial dalam cache. Library Autentikasi akan memeriksa jalur ini terlebih dahulu sebelum menjalankan file yang dapat dieksekusi.
• WORKFORCE_POOL_USER_PROJECT: nomor atau ID project yang digunakan untuk kuota dan penagihan. Akun utama menetapkan izin serviceusage.services.use pada project ini.

Menjalankan perintah ini akan menghasilkan file konfigurasi IdP SAML yang mirip dengan berikut ini:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

Catatan: timeout_millis disertakan dalam konfigurasi karena dalam beberapa kasus, kredensial interaktif dari file yang dapat dieksekusi juga dapat berjalan dalam mode non-interaktif. Generator konfigurasi gcloud CLI akan otomatis mengisi kolom tersebut dengan setelan waktu tunggu default 30 detik.

Untuk login, jalankan perintah berikut:

gcloud auth login --cred-file=/path/to/config.json

Perlu diperhatikan bahwa CLI (gcloud, bq, gsutil) saat ini tidak mendukung jenis kredensial dari file yang dapat dieksekusi.

Untuk alur headless, gcloud otomatis menggunakan cakupan berikut: https://www.googleapis.com/auth/cloud-platform. gcloud kemudian secara transparan memposting kredensial Anda ke endpoint Security Token Service, tempat kredensial tersebut ditukarkan dengan token akses Google Cloud sementara.

Anda kini dapat menjalankan perintah gcloud menggunakan gcloud CLI.

Gunakan library klien Google Cloud

Jika menggunakan library klien yang didukung, Anda dapat mengonfigurasi library klien agar menghasilkan kredensial Google secara otomatis. Jika memungkinkan, sebaiknya buat kredensial secara otomatis, sehingga Anda tidak perlu mengimplementasikan sendiri proses pertukaran token.

Dukungan library klien Google Cloud untuk workforce pools didukung dalam bahasa berikut: Node.js, Java, Python, Go, dan C++ (gRPC).

Untuk menggunakan library klien dengan layanan atau bahasa ini, lakukan hal berikut:

bq

Untuk melakukan autentikasi menggunakan workforce identity federation, gunakan perintah gcloud auth login:

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

dengan FILEPATH sebagai jalur file ke file konfigurasi kredensial.

Dukungan untuk workforce identity federation di bq tersedia di versi 390.0.0 dan Google Cloud CLI versi yang lebih baru.

C++

Sebagian besar Library Klien Google Cloud untuk C++ mendukung workforce identity federation dengan menggunakan objek ChannelCredentials, yang dibuat dengan memanggil grpc::GoogleDefaultCredentials(). Untuk melakukan inisialisasi kredensial ini, Anda harus membangun library klien dengan gRPC versi 1.42.0 atau yang lebih baru.

Library Klien Cloud Storage untuk C++ menggunakan REST API, bukan gRPC, sehingga tidak mendukung workforce identity federation.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

Untuk melakukan autentikasi menggunakan workforce identity federation, gunakan perintah gcloud auth login:

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

dengan FILEPATH sebagai jalur file ke file konfigurasi kredensial.

Dukungan untuk workforce identity federation di gcloud tersedia di versi 392.0.0 dan Google Cloud CLI versi yang lebih baru.

Go

Library klien untuk Go mendukung workforce identity federation jika menggunakan modul golang.org/x/oauth2 versi v0.0.0-20211005180243-6b3c2da341f1 atau yang lebih baru.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

gsutil

Untuk melakukan autentikasi menggunakan workforce identity federation, gunakan salah satu metode berikut:

Saat menggunakan gsutil bersamaan dengan gcloud, login seperti biasa:

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

Saat menggunakan gsutil sebagai aplikasi command line mandiri, edit file .boto untuk menyertakan bagian berikut:

[Credentials]
gs_external_account_file = FILEPATH

FILEPATH dalam kedua kasus tersebut adalah jalur file ke file konfigurasi kredensial.

Dukungan untuk workforce identity federation di gsutil tersedia pada versi 379.0.0 dan Google Cloud CLI versi yang lebih baru.

Java

Library klien untuk Java mendukung workforce identity federation jika menggunakan artefak com.google.auth:google-auth-library-oauth2-http versi 1.2.0 atau yang lebih baru.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

Storage storageService = StorageOptions.newBuilder().setProjectId("project-id")
    .setCredentials(sourceCredentials).build().getService();

Node.js

Library klien untuk Node.js mendukung workforce identity federation. Anda harus menggunakan paket google-auth-library versi 7.10.0 atau yang lebih baru. Tidak seperti workload identity pool, workforce pool dikaitkan dengan organisasi, bukan project Google Cloud. Saat membuat objek GoogleAuth, Anda harus menentukan project ID. Untuk informasi selengkapnya, lihat README untuk paket google-auth-library.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

Library klien untuk Python mendukung workforce identity federation jika menggunakan paket google-auth versi 2.3.0 atau yang lebih baru.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

Pada contoh di atas, nilai project dapat berupa None jika library tidak dapat menemukannya secara otomatis. Anda dapat meneruskannya secara eksplisit saat menggunakan instance layanan (seperti dalam contoh klien penyimpanan) atau menetapkannya melalui variabel lingkungan GOOGLE_CLOUD_PROJECT.

Untuk mengetahui detailnya, lihat panduan pengguna untuk paket google-auth.

Menggunakan REST API

Anda dapat memanggil Security Token Service API Google Cloud untuk menukar kredensial eksternal Anda dengan token akses Google Cloud.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

Ganti kode berikut:

• AUDIENCE: nama resource lengkap penyedia yang menerbitkan token subjek.
• PROVIDER_ID: ID penyedia

• SUBJECT_TOKEN_TYPE: tetapkan ke salah satu opsi berikut:

  • urn:ietf:params:oauth:token-type:id_token untuk token ID OIDC
  • urn:ietf:params:oauth:token-type:saml2 untuk pernyataan SAML

• EXTERNAL_SUBJECT_TOKEN: token yang dikeluarkan IdP yang mewakili identitas akun utama yang token aksesnya diminta. Catatan: Jika Anda menggunakan OIDC, token berformat JWT.

• BILLING_PROJECT_NUMBER: nomor atau ID project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki izin serviceusage.services.use pada project ini.

Responsnya mirip dengan hal berikut ini:

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Kelola sesi menggunakan gcloud CLI

Token Google Cloud sementara yang diperoleh gcloud dari endpoint Security Token Service akan habis masa berlakunya setelah interval waktu yang ditentukan. Saat masa berlaku token akan berakhir, gcloud akan memeriksa file kredensial yang Anda berikan dan memeriksa validitas kredensial yang diterima dari IdP. Jika kredensial Anda masih valid, gcloud akan melanjutkan untuk mendapatkan token akses Google Cloud baru secara transparan dan sesi Anda saat ini akan berjalan tanpa gangguan.

Jika masa berlaku kredensial Anda sudah habis, tidak ada token Google Cloud baru yang akan diterbitkan, dan panggilan yang Anda lakukan dengan kredensial tersebut akan gagal. Pada tahap ini, Anda harus melakukan autentikasi ulang.

Anda dapat menghentikan sesi dengan menjalankan perintah berikut:

gcloud auth revoke

gcloud mendukung beberapa sesi pengguna. Untuk mendapatkan daftar sesi, termasuk sesi yang sedang aktif, jalankan perintah berikut:

gcloud auth list

Output perintah ini akan mirip dengan berikut ini:

Credentialed Accounts
ACTIVE    ACCOUNT
*         [e-mail]
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/[e-mail]

Untuk beralih ke sesi lain dan menyetelnya sebagai aktif, jalankan perintah berikut:

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

Langkah selanjutnya

• Menghapus pengguna workforce identity federation dan datanya
• Pelajari produk Google Cloud mana yang mendukung workforce identity federation
• Menyiapkan akses pengguna ke konsol (gabungan)