Beri pelanggan opsi untuk mengakses resource Google Cloud dari produk atau layanan Anda

Dokumen ini menjelaskan persyaratan dan praktik terbaik yang dapat Anda ikuti agar pelanggan dapat menggunakan produk Anda untuk mengakses resource mereka di Google Cloud tanpa menggunakan kunci akun layanan.

Jika Anda menawarkan produk atau mengoperasikan layanan yang memungkinkan pelanggan menganalisis atau mengelola data atau resource, maka pelanggan Anda mungkin ingin mengakses data atau resource ain di lingkungan Google Cloud mereka. Contoh dari produk dan layanan tersebut mencakup:

  • Produk analisis data: Pelanggan Anda mungkin ingin menggunakan produk tersebut untuk menganalisis data mereka di BigQuery.
  • Produk dan layanan CI/CD: Pelanggan Anda mungkin menggunakan layanan tersebut untuk men-deploy infrastruktur dan aplikasi ke project Google Cloud mereka.
  • Automasi proses robotik (RPA): Pelanggan Anda mungkin menggunakan RPA untuk alur kerja seperti membuat project, mengelola akses, atau mengotomatiskan tugas administratif di Google Cloud.

Untuk mengautentikasi produk lokal atau software-as-a-service (SaaS) ke Google Cloud, pelanggan umumnya mengandalkan kunci akun layanan, tetapi kunci ini dapat menjadi sulit untuk dikelola dan disimpan dengan aman.

Sebagai vendor produk lokal atau SaaS, Anda dapat membantu pelanggan melindungi resource Google Cloud dengan mengizinkan mereka menggunakan Workload Identity Federation untuk mengakses resource Google Cloud. Contoh untuk layanan yang sudah mengizinkan pelanggan menggunakan Workload Identity Federation meliputi Terraform Cloud, GitHub, dan GitLab

Dokumen ini menjelaskan cara memperluas produk untuk mendukung Workload Identity Federation, dan menjelaskan praktik terbaik yang dapat Anda ikuti. Dokumen ini mengasumsikan bahwa Anda sudah memahami Workload Identity Federation dan OpenID Connect.

Arsitektur

Tujuan Workload Identity Federation adalah untuk meniadakan kebutuhan akan kunci akun layanan dengan mengizinkan pelanggan menggabungkan produk atau layanan Anda dengan lingkungan Google Cloud mereka. Pelanggan Anda kemudian dapat mengakses resource Google Cloud mereka menggunakan identitas yang dinyatakan oleh produk atau layanan Anda.

Agar pelanggan dapat menggunakan Workload Identity Federation, produk atau layanan Anda harus mengimplementasikan subset OpenID Connect. Secara khusus, Anda harus mengizinkan workload untuk mendapatkan token ID yang memenuhi kriteria berikut:

  • Token mengidentifikasi workload dalam produk atau platform Anda
  • Token mengidentifikasi instance, tenant, atau penginstalan produk dan platform Anda
  • Token berisi tanda tangan kriptografi yang dapat digunakan Workload Identity Federation untuk memverifikasi keaslian token.

Persyaratan

Untuk mendukung Workload Identity Federation, Anda harus memastikan bahwa produk atau layanan Anda memenuhi persyaratan berikut:

  1. Workload memiliki akses ke token ID yang valid.

    Kapan pun selama siklus prosesnya, workload harus memiliki akses ke token ID yang menyatakan identitas workload dan mematuhi persyaratan yang ditentukan oleh OpenID Connect 1.0.

    Karena masa aktif token ID terbatas, Anda harus memastikan token ID aktif lebih lama dibandingkan workload-nya, atau workload dapat memperoleh token ID baru secara berkala.

  2. Token ID mengidentifikasi workload secara unik.

    Token ID harus berisi setidaknya satu klaim yang mengidentifikasi workload secara unik. ID workload harus tidak dapat diubah.

    Untuk produk atau layanan yang mendukung multi-tenancy, token juga harus berisi setidaknya satu klaim yang mengidentifikasi tenant secara unik. ID tenant juga harus tidak dapat diubah.

  3. Token ID ditandatangani, tetapi tidak dienkripsi.

  4. Metadata penyedia OpenID dapat diakses secara publik dan ditemukan dengan token ID.

    Anda harus memberikan dokumen konfigurasi penyedia OpenID di endpoint yang dapat diakses publik, yang dapat ditemukan menggunakan protokol penemuan penerbit OpenID. Misalnya, jika token ID berisi klaim iss dengan nilai https://service.example.com/v1/, Anda harus memberikan dokumen konfigurasi penyedia di https://service.example.com/v1/.well-known/openid-configuration, dan endpoint harus dapat diakses publik melalui internet dari alamat IP mana pun.

  5. Kunci penandatanganan dapat diakses secara publik dan dapat ditemukan dari metadata penyedia OpenID.

    Anda harus memberikan dokumen Kumpulan Kunci Web JSON (JWKS) di endpoint yang dapat diakses secara publik, yang ditemukan dari kolom jwks_uri pada metadata penyedia OpenID.

Praktik terbaik

Saat memperluas produk atau layanan untuk mendukung Workload Identity Federation, pertimbangkan praktik terbaik berikut.

Membedakan antara identitas dan token akses

Dalam konteks Workload Identity Federation, tujuan dari token ID adalah untuk menyatakan identitas workload: Token harus berisi informasi yang cukup bagi Workload Identity Federation untuk mengidentifikasi workload dan membedakannya dari workload lain.

Berbeda dengan token ID, token akses memiliki kegunaan yang berbeda: Token ini digunakan untuk membuat keputusan akses dan dapat berisi informasi tentang izin apa yang dimiliki suatu workload, atau API mana yang boleh diakses.

Jika produk atau layanan Anda menggunakan token akses untuk tujuan seperti mengizinkan workload memanggil API produk Anda, token akses ini mungkin tidak cocok untuk Workload Identity Federation. Alih-alih menggunakan kembali token akses sebagai token ID, pertimbangkan untuk menerapkan jenis token kedua yang cocok dengan definisi token ID, dan biarkan workload menggunakan token ID untuk Workload Identity Federation.

Mengekspos token ID menggunakan cara yang kompatibel dengan library klien

Library klien Google Cloud dapat secara otomatis memperoleh token ID dari berbagai sumber, termasuk berikut ini:

  • Endpoint HTTP (kredensial yang bersumber dari URL)
  • File lokal (kredensial yang bersumber dari file)

Untuk mendapatkan token ID dari sumber lain, pelanggan Anda mungkin perlu mengubah kode mereka, men-deploy alat atau library tambahan. Dengan mengekspos token ID melalui cara yang kompatibel dengan library klien, Anda dapat menghindari kerumitan dan mempermudah pelanggan untuk mengadopsi Workload Identity Federation.

Menggunakan URL penerbit khusus tenant

Klaim yang disematkan dalam token ID workload mungkin bersifat unik dalam instance tertentu produk atau layanan Anda, dan mungkin tidak di beberapa instance produk atau layanan lainnya. Misalnya, dua pelanggan mungkin menggunakan produk atau layanan Anda untuk men-deploy workload dan secara tidak sengaja menetapkan nama dan ID yang sama untuk workload tersebut.

Workload Identity Federation mencoba untuk mengatasi kurangnya keunikan ini dengan memverifikasi URL penerbit (iss) dari token ID, dan dengan hanya mengizinkan token dari satu penerbit per workload identity pool.

Jika produk atau layanan Anda mendukung multi-tenancy, beberapa pelanggan mungkin berbagi satu instance produk atau layanan, dan token ID workload mereka mungkin menggunakan URL penerbit yang sama. Menggunakan URL penerbit yang sama di beberapa tenant dapat membuat pelanggan Anda terkena serangan spoofing: Misalnya, pihak tidak bertanggung jawab dapat membuat workload di tenant mereka sendiri, menetapkan ID atau nama yang sama sebagai workload di tenant korban, dan menggunakan token ID workload mereka untuk memalsukan identitas workload korban.

Untuk membantu melindungi pelanggan Anda dari serangan spoofing, hindari penggunaan URL penerbit yang sama di beberapa tenant dan sematkan ID tenant unik di URL penerbit, mnisalnya https://saas.example.com/tenant-123/.

Mengizinkan pengguna menentukan audiens token ID

Beberapa workload pelanggan Anda mungkin perlu mengakses Google Cloud serta layanan pihak ketiga lainnya. Saat pelanggan memutuskan untuk melakukan federasi produk atau layanan Anda dengan beberapa pihak tepercaya, mereka mungkin berada dalam situasi saat token ID workload secara tidak sengaja atau dengan niat jahat digunakan untuk pihak tepercaya yang salah: Misalnya, pihak tidak bertanggung jawab mungkin menipu workload untuk mengungkapkan token ID yang ditujukan untuk layanan pihak ketiga, lalu menggunakan token ID tersebut untuk Workload Identity Federation.

Untuk membantu mencegah pelanggan Anda menjadi korban serangan wakil yang bingung tersebut, hindari penggunaan audiens statis (klaim aud) dalam token ID. Sebagai gantinya, biarkan workload menentukan audiens saat mendapatkan token ID dan, secara opsional, pertahankan daftar yang diizinkan untuk audiens yang dapat diminta workload.

Secara default, Workload Identity Federation mengharapkan audiens token ID cocok dengan URL https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID. Pastikan workload dapat menggunakan URL sebagai audiens untuk token ID, dan panjang URL audiens kurang dari 180 karakter.

Menggunakan ID yang tidak dapat diubah dan tidak dapat digunakan kembali dalam klaim token ID

Saat pelanggan ingin memberikan akses ke resource Google Cloud pada salah satu workload mereka, mereka harus membuat binding IAM yang mereferensikan identitas berdasarkan subjek, grup, atau atribut khusus. Subjek, grup, dan atribut khusus workload berasal dari klaim dalam token ID workload.

Jika pelanggan membuat binding IAM yang merujuk pada klaim yang dapat berubah, workload mereka mungkin secara tidak sengaja kehilangan akses saat nilai klaim berubah. Misalnya, pelanggan dapat membuat binding IAM yang mereferensikan nama workloadnya. Jika kemudian mereka mengganti nama workload, binding IAM mungkin tidak diterapkan lagi.

Lebih buruk lagi, pihak tidak bertanggung jawab mungkin mencoba mendapatkan akses tidak sah ke resource lain dengan sengaja mengganti nama atau mengubah lingkungan workload untuk memalsukan identitas workload lain.

Untuk membantu pelanggan mencegah masalah spoofing seperti, pastikan token ID berisi ID yang tidak dapat diubah dan digunakan kembali.

Menyertakan informasi konteks dalam token ID

Alih-alih memberikan akses tanpa syarat ke resource Google Cloud pada workload, pelanggan sebaiknya membatasi akses sehingga workload hanya dapat memperoleh kredensial Google jika kriteria tambahan tertentu terpenuhi.

Agar pelanggan dapat mengonfigurasi batasan tersebut, sertakan klaim tambahan dalam token ID yang berisi informasi konteks. Contoh informasi konteks mencakup:

  • informasi tentang pengguna yang memiliki atau memulai workload
  • alasan dan cara workload dimulai
  • permintaan yang saat ini ditangani oleh workload

Pelanggan dapat menggunakan klaim ini untuk mengonfigurasi kondisi atribut atau dalam ID utama.

Batasi masa pakai token ID menjadi 60 menit

Token ID memiliki masa berlaku terbatas yang ditentukan oleh klaim exp. Saat workload menggunakan token ID untuk melakukan pertukaran token, Workload Identity Federation memvalidasi klaim exp token ID dan mengeluarkan token STS yang valid selama token input, tetapi maksimal 1 jam.

Menggunakan token ID yang valid selama lebih dari satu jam tidak berpengaruh pada Workload Identity Federation, tetapi dapat meningkatkan risiko jika token ID bocor secara tidak sengaja. Menggunakan masa aktif yang jauh di bawah 1 jam dapat membantu mengurangi risiko tersebut, tetapi dapat menyebabkan pertukaran token semakin sering sehingga menurunkan performa.

Langkah selanjutnya