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 yang telah diberikan akses kepada Anda.

Metode yang dijelaskan dalam panduan ini dapat digunakan pada mesin headless.

Anda bisa mendapatkan token jangka pendek dengan menggunakan proses tingkat tinggi ini, yang dijelaskan secara mendetail nanti dalam dokumen 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:

    Catat ID kumpulan identitas tenaga kerja dan ID penyedia kumpulan identitas tenaga kerja Anda.

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

  3. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  4. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

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 file agar dapat digunakan secara default.

Membuat file konfigurasi login

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

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

Ganti kode berikut:

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

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

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/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",
}

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

Saat Anda menggunakan kredensial dari file, token akan 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 memuat ulang 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/WORKFORCE_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 identity pool
  • WORKFORCE_PROVIDER_ID: ID penyedia workforce identity pool
  • 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/WORKFORCE_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

Saat Anda menggunakan kredensial yang bersumber 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/WORKFORCE_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 kumpulan identitas tenaga kerja.
  • WORKFORCE_PROVIDER_ID: ID penyedia kumpulan identitas tenaga kerja.
  • 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/WORKFORCE_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

Saat Anda menggunakan kredensial noninteraktif dari file yang dapat dieksekusi, token dimuat dari file yang dapat dieksekusi secara lokal. 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 menetapkan variabel lingkungan berikut saat file yang dapat dieksekusi dijalankan:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: kolom audience dari konfigurasi kredensial. Variabel ini selalu ditetapkan.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: jenis token subjek yang diharapkan. Variabel ini selalu ditetapkan.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: lokasi file output dari konfigurasi kredensial. Variabel ini 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/WORKFORCE_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 kumpulan identitas tenaga kerja.
  • WORKFORCE_PROVIDER_ID: ID penyedia kumpulan identitas tenaga kerja.
  • 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 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/WORKFORCE_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

Saat menggunakan 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 untuk kredensial interaktif dan non-interaktif dari file yang dapat dieksekusi.

Variabel lingkungan juga sama untuk kredensial interaktif dan noninteraktif 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/WORKFORCE_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 kumpulan identitas tenaga kerja.
  • WORKFORCE_PROVIDER_ID: ID penyedia kumpulan identitas tenaga kerja.
  • 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 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/WORKFORCE_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",
    }
  }
}

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

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.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 kumpulan identitas tenaga kerja.
  • WORKFORCE_PROVIDER_ID: ID penyedia kumpulan identitas tenaga kerja.
  • 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](https://toolbox.googleapps.com/apps/encode_decode/) atau JSON yang berisi pernyataan SAML berenkode base64. Untuk menggunakan kredensial dari URL, gunakan flag `--credential-source-url`: ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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 hal berikut: * WORKFORCE_POOL_ID: ID kumpulan identitas tenaga kerja. * WORKFORCE_PROVIDER_ID: ID penyedia kumpulan identitas tenaga kerja. * CREDENTIAL_URL: URL endpoint server lokal. * 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.

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 menetapkan variabel lingkungan berikut saat file yang dapat dieksekusi dijalankan:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: kolom audience dari konfigurasi kredensial. Variabel ini selalu ditetapkan.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: jenis token subjek yang diharapkan. Variabel ini selalu ditetapkan.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: lokasi file output dari konfigurasi kredensial. Variabel ini hanya ada jika ditentukan dalam konfigurasi kredensial.

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/WORKFORCE_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 kumpulan identitas tenaga kerja.
  • WORKFORCE_PROVIDER_ID: ID penyedia kumpulan identitas tenaga kerja.
  • 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 ke kredensial identitas pihak ketiga (3PI) yang dihasilkan oleh file yang dapat dieksekusi. Hal ini berguna untuk menyimpan kredensial dalam cache. Library otorisasi memeriksa keberadaan file 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/WORKFORCE_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

Saat Anda menggunakan kredensial dari file yang dapat dieksekusi untuk mode interaktif gcloud, file yang dapat dieksekusi akan berinteraksi dengan pengguna melalui antarmuka command line.

Pada perintah sebelumnya, ganti perintah berikut:

  • EXECUTABLE_OUTPUT_FILE: Wajib diisi. Jalur ke file yang memberikan kredensial yang dihasilkan oleh file yang dapat dieksekusi.
  • EXECUTABLE_TIMEOUT: Wajib diisi. 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 dihilangkan, file yang dapat dieksekusi masih berjalan.

File yang dapat dieksekusi harus memunculkan error ke executable-output-file dalam format JSON berikut. Jika file yang dapat dieksekusi melaporkan error, semua kolom ini wajib diisi. Kolom kode dan pesan digunakan oleh library klien saat menampilkan error yang sesuai.

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

Eksekusi perintah yang berhasil akan menampilkan kolom yang sama dengan kredensial dari file yang dapat dieksekusi dan non-interaktif.

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

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/WORKFORCE_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 kumpulan identitas tenaga kerja.
  • WORKFORCE_PROVIDER_ID: ID penyedia kumpulan identitas tenaga kerja.
  • 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 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 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/<var>WORKFORCE_POOL_ID<var>/providers/<var>WORKFORCE_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>",
    }
  }
}

Untuk login, jalankan perintah berikut:

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

Perlu diperhatikan bahwa gcloud CLI maupun alat command line bq tidak mendukung jenis kredensial dari file yang dapat dieksekusi.

Untuk alur headless, gcloud CLI otomatis menggunakan cakupan berikut: https://www.googleapis.com/auth/cloud-platform. Gcloud CLI 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:

alat bq

Untuk melakukan autentikasi menggunakan Workforce Identity Federation, gunakan perintah gcloud auth login:

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

dengan FILEPATH sebagai jalur ke file konfigurasi kredensial.

Dukungan untuk Workforce Identity Federation di alat bq tersedia di Google Cloud CLI versi 390.0.0 dan 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

Ganti FILEPATH dengan jalur ke file konfigurasi kredensial.

Dukungan untuk Workforce Identity Federation di gcloud CLI tersedia di Google Cloud CLI versi 392.0.0 dan versi yang lebih baru.

Go

Library Klien Cloud untuk Go mendukung Workforce Identity Federation saat Anda 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)
}

Java

Library Klien Cloud untuk Java mendukung Workforce Identity Federation saat Anda 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 Cloud untuk Node.js mendukung Workforce Identity Federation saat Anda menggunakan paket google-auth-library versi 7.10.0 atau yang lebih baru.

Tidak seperti workload identity pool, workforce identity 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 Cloud untuk Python mendukung Workforce Identity Federation saat Anda 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)

Dalam kode contoh, nilai project dapat berupa None jika library tidak dapat menemukan project ID secara otomatis. Anda dapat meneruskan project ID secara eksplisit saat menggunakan instance layanan, seperti yang dilakukan contoh klien penyimpanan, atau menetapkan project ID 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 dengan menjalankan perintah berikut:

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_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.
  • WORKFORCE_POOL_ID: ID workforce identity pool
  • WORKFORCE_PROVIDER_ID: ID penyedia workforce identity pool

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

    Jika Anda mengonfigurasi penyedia OIDC, token harus berformat JWT.

  • BILLING_PROJECT_NUMBER: nomor atau ID project yang digunakan untuk kuota dan penagihan. Akun utama harus memiliki izin serviceusage.services.use di 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 CLI dari endpoint Security Token Service akan habis masa berlakunya setelah interval waktu yang ditentukan. Saat masa berlaku token akan berakhir, gcloud CLI akan memeriksa file kredensial yang Anda berikan dan memeriksa validitas kredensial yang diterima dari IdP. Jika kredensial Anda masih valid, gcloud CLI 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 saat ini aktif, jalankan perintah berikut:

gcloud auth list

Output perintah ini akan mirip dengan berikut ini:

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

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