Melakukan autentikasi dengan akun layanan

Akun layanan adalah akun yang digunakan oleh workload atau layanan untuk menggunakan resource secara terprogram dan mengakses mikroservice secara aman. Identitas ini adalah jenis identitas khusus yang digunakan oleh aplikasi atau workload, bukan oleh pengguna. Mirip dengan akun pengguna, akun layanan dapat diberi izin dan peran, tetapi akun layanan tidak dapat login seperti pengguna manusia.

Akun layanan berguna untuk mengelola infrastruktur dengan air gap Google Distributed Cloud (GDC), seperti:

• Layanan dan workload Distributed Cloud internal untuk mengakses Distributed Cloud API (Application Programming Interface) bidang kontrol dengan aman. Misalnya, Layanan Database berinteraksi dengan API Kubernetes untuk membuat dan menghapus database.
• Workload pelanggan di Distributed Cloud untuk mengakses layanan Distributed Cloud dan melakukan panggilan API (Application Programming Interface) aplikasi yang sah. Misalnya, akun layanan dapat mengelola pelanggan yang menggunakan notebook Vertex AI Workbench untuk mentranskripsikan file audio menggunakan Speech-to-Text API.
• Workload eksternal untuk digabungkan dengan Distributed Cloud. Misalnya, akun layanan dapat mengelola aplikasi di luar Distributed Cloud yang mendigitalkan dokumen, tetapi ingin menggunakan Optical Character Recognition (OCR) API untuk menggantikan mesin OCR saat ini.
• Layanan Distributed Cloud atau pengontrol sistem untuk mengakses resource pelanggan atau cluster pengguna secara aman. Misalnya, akun layanan dapat mengelola alur kerja autentikasi dan otorisasi tempat pengontrol layanan yang berjalan di cluster admin perlu menjalankan beban kerja dalam cluster pengguna yang dikelola oleh pelanggan.

Anda dapat mengelola akun menggunakan konsol GDC, gdcloud CLI, atau API. Dengan gdcloud CLI, fitur identitas layanan dibangun di atas ProjectServiceAccount API global. Karena akun layanan dikonfigurasi secara global, akun tersebut beroperasi di semua zona di semesta gdcloud Anda.

Sebelum memulai

Anda hanya dapat membuat akun layanan dalam project. Untuk mengetahui informasi selengkapnya tentang cara membuat project, lihat Membuat project.

Buat identitas layanan

Untuk mendapatkan izin yang diperlukan untuk membuat akun layanan, minta Admin IAM Project Anda untuk memberi Anda peran Admin IAM Project (project-iam-admin).

Pengguna yang memiliki akses ke akun layanan dapat mengakses semua akun layanan dalam project.

Untuk membuat akun layanan di project, gunakan konsol GDC, gdcloud CLI, atau API.

Konsol

1. Login ke konsol GDC.
2. Di menu navigasi, pilih Identity & Access > Service identities.
3. Klik Buat Identitas Layanan. Halaman Service Identity details akan terbuka.
4. Di kolom Nama identitas layanan, masukkan nama untuk identitas layanan Anda. Contoh: testserviceidentity.
5. Klik Buat.

gdcloud

Buat identitas layanan:

gdcloud iam service-accounts create NAME \
    --project=PROJECT

Ganti nilai berikut:

• NAME: nama ProjectServiceAccount. Nama harus unik dalam namespace project.
• PROJECT: project tempat identitas layanan akan dibuat. Jika gdcloud init sudah ditetapkan, hapus flag --project.

Perintah ini akan membuat ProjectServiceAccount di namespace project di server Management API.

API

1. Buat file YAML resource kustom ProjectServiceAccount, seperti my-project-sa.yaml:

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Ganti variabel berikut:

   • NAME: nama resource ProjectServiceAccount. Nama harus unik dalam namespace project.
   • PROJECT: project tempat identitas layanan akan dibuat.
   • ALGORITHM: algoritma kunci. Hanya kunci ES256 yang didukung.
   • KEY_ID: ID unik kunci. ID digunakan untuk menentukan kunci mana yang akan diverifikasi.
   • BASE64_ENCODED_KEY: kunci publik berenkode base64 dalam format PEM untuk diverifikasi. Kunci pribadi yang digunakan untuk membuat kunci publik ini diharapkan dalam format PEM ECDSA P256.
   • START_TIME: waktu mulai saat kunci menjadi valid, seperti 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME: waktu habis masa berlaku untuk kunci, seperti 2026-02-07T00:59:34Z.

2. Terapkan resource kustom ProjectServiceAccount ke server API global:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Ganti variabel GLOBAL_API_SERVER_KUBECONFIG dengan jalur ke file kubeconfig untuk server API global.

Melihat identitas layanan

Untuk melihat daftar akun layanan dalam project, gunakan konsol GDC atau gdcloud CLI.

Konsol

1. Login ke konsol GDC.
2. Pilih project.
3. Di menu navigasi, klik Identity & Access > Service Identities untuk melihat daftar akun layanan untuk project.

gdcloud

Mencantumkan akun layanan dalam project:

gdcloud iam service-accounts list \
    --project=PROJECT

Menetapkan binding peran ke identitas layanan

Untuk menetapkan binding peran, Anda harus memiliki izin yang sesuai. Untuk mendapatkan izin yang diperlukan untuk menetapkan peran, minta Admin IAM Project Anda untuk memberi Anda peran Admin IAM Project (project-iam-admin).

Gunakan konsol GDC atau gdcloud CLI untuk menetapkan binding peran.

Konsol

1. Login ke konsol GDC.
2. Pilih project.
3. Di menu navigasi, pilih Identity & Access > Access.
4. Di daftar Anggota, klik Tambahkan anggota. Anda akan melihat halaman Pengguna dan peran.
5. Pilih Service identity di daftar Member type.
6. Di daftar Service identity, pilih identitas layanan yang ingin Anda tetapkan pengikatan perannya.
7. Di daftar Role, pilih peran yang ingin Anda tetapkan ke identitas layanan, seperti Backup Creator.
8. Opsional: Untuk menambahkan peran lain, klik Tambahkan peran lain. Pilih peran tambahan.
9. Klik Tambahkan.

gdcloud

Perintah ini membuat dan memberi nama binding peran project untuk mengikat peran yang ditentukan dengan ProjectServiceAccount di server Management API:

gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --role-namespace=ROLE_NAMESPACE \
    --iam-account=NAME

Ganti nilai berikut:

• PROJECT: project tempat binding peran akan dibuat. Jika gdcloud init sudah ditetapkan, Anda dapat menghilangkan flag --project.
• ROLE: peran standar yang akan ditetapkan ke ProjectServiceAccount. Tentukan peran dalam format Role/name dengan Role adalah jenis Kubernetes IAMRole, dan name adalah nama peran bawaan. Misalnya, untuk menetapkan peran Project Viewer, tetapkan peran ke IAMRole/project-viewer.
• ROLE_NAMESPACE: namespace peran yang akan diikat dengan akun layanan. Hal ini hanya berlaku jika semesta Anda memiliki beberapa zona.
• NAME: nama identitas layanan yang akan digunakan.

Menghapus identitas layanan

Penting: Saat Anda menghapus akun layanan, binding peran yang terkait dengannya tidak dihapus secara otomatis. Jika Anda membuat akun layanan baru dengan nama yang sama, akun tersebut akan otomatis mewarisi izin dari akun layanan yang dihapus sebelumnya. Untuk menghindari izin yatim piatu yang dapat bertahan dari akun layanan yang dihapus, hapus semua binding peran yang ada yang terkait dengan akun layanan sebelum menghapus akun layanan itu sendiri.

Untuk menghapus akun layanan di project, gunakan konsol GDC atau gdcloud CLI.

Setelah Anda menghapus identitas layanan, aplikasi tidak memiliki akses ke resource project melalui identitas layanan tersebut.

Konsol

1. Login ke konsol GDC.
2. Di menu navigasi, pilih Identity & Access > Service Identities.
3. Pilih kotak centang identitas layanan yang ingin Anda hapus.
4. Klik Hapus.
5. Dialog konfirmasi akan muncul. Di kolom Confirm by typing the following below, masukkan remove.
6. Klik Hapus.

gdcloud

Jalankan perintah berikut untuk menghapus identitas layanan:

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

Membuat dan menambahkan pasangan kunci

Untuk membuat dan menambahkan pasangan kunci dalam project, gunakan konsol GDC, gdcloud CLI, atau API.

Konsol

1. Login ke konsol GDC.
2. Di menu navigasi, pilih Identity & Access > Service Identities.
3. Klik nama identitas layanan yang ingin Anda tambahkan di kunci.
4. Klik Create New Key.
5. Kunci baru akan muncul dalam daftar Keys, dan dialog akan mengonfirmasi bahwa Anda telah berhasil membuat kunci.

gdcloud

Perintah gdcloud akan membuat file JSON kredensial default aplikasi serta pasangan kunci publik dan pribadi:

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

Ganti nilai berikut:

• APPLICATION_DEFAULT_CREDENTIALS_FILENAME: nama file JSON.
• PROJECT : memilih project untuk membuat kunci. Jika gdcloud init sudah ditetapkan, Anda dapat menghilangkan flag --project.
• NAME: nama identitas layanan yang akan ditambahkan kuncinya.
• CA_CERTIFICATE_PATH: Opsional: jalur sertifikat certificate authority (CA) untuk memverifikasi endpoint autentikasi. Jika Anda tidak menentukan jalur ini, sertifikat CA sistem akan digunakan. Anda harus menginstal CA di sertifikat CA sistem.

Distributed Cloud menambahkan kunci publik ke kunci ProjectServiceAccount yang Anda gunakan untuk memverifikasi token web JSON (JWT) yang ditandatangani oleh kunci pribadi. Kunci pribadi ditulis ke file JSON kredensial default aplikasi.

Contoh berikut menunjukkan file JSON kredensial default aplikasi:

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "service_identity_name",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

Contoh ini menggunakan nilai berikut:

• project: namespace project di organisasi.
• private_key_id: ID yang ditetapkan ke kunci.
• private_key: kunci pribadi ECDSA P256 dalam format PEM yang dihasilkan CLI.
• name: nama identitas layanan.
• token_uri: alamat endpoint autentikasi.

API

1. Buat pasangan kunci publik dan pribadi. Perintah berikut menggunakan openssl sebagai contoh, yang merupakan alat umum untuk tujuan ini.

   openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
   openssl ec -in "key.pem" -pubout > "pub.pem"
   

2. Enkode kunci publik dengan base64 dan ambil ID kuncinya:

   KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
   BASE64_ENCODED_KEY=$(cat pub.pem | base64)
   

3. Buat atau perbarui file YAML resource kustom ProjectServiceAccount, termasuk informasi kunci yang dihasilkan dari langkah sebelumnya:

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Ganti variabel berikut:

   • NAME: nama resource ProjectServiceAccount. Nama harus unik dalam namespace project.
   • PROJECT: project tempat Anda membuat kunci.
   • ALGORITHM: algoritma kunci. Hanya kunci ES256 yang didukung.
   • KEY_ID: ID unik kunci. ID digunakan untuk menentukan kunci mana yang akan diverifikasi.
   • BASE64_ENCODED_KEY: kunci publik berenkode base64 dalam format PEM untuk diverifikasi. Kunci pribadi yang digunakan untuk membuat kunci publik ini diharapkan dalam format PEM ECDSA P256.
   • START_TIME: waktu mulai saat kunci menjadi valid, seperti 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME: waktu habis masa berlaku untuk kunci, seperti 2026-02-07T00:59:34Z.

4. Terapkan resource kustom ProjectServiceAccount ke server API global:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Ganti variabel GLOBAL_API_SERVER_KUBECONFIG dengan jalur ke file kubeconfig untuk server API global.

5. Buat file JSON kredensial default aplikasi yang berisi kunci pribadi. Pastikan variabel KEY_ID dalam file JSON ditetapkan ke nilai yang sama dengan variabel KEY_ID yang Anda gunakan dalam spesifikasi ProjectServiceAccount.

   cat <<EOF > "key_file.json"
   {
     "format_version": "1",
     "name": "NAME",
     "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
     "private_key_id": "KEY_ID",
     "project": "PROJECT",
     "token_uri": "AUTH_URL",
     "type": "gdch_service_account"
   }
   EOF
   

   Ganti variabel berikut:

   • NAME: nama identitas layanan.
   • KEY_ID: ID unik kunci. ID digunakan untuk menentukan kunci mana yang akan diverifikasi, dan ID harus cocok dengan nilai KEY_ID yang digunakan dalam spesifikasi ProjectServiceAccount.
   • PROJECT: namespace project di organisasi.
   • AUTH_URL: alamat endpoint autentikasi.

6. Tambahkan pasangan kunci ke project Anda dengan mengaktifkan akun layanan:

   gdcloud auth activate-service-account –-key-file=key_file.json
   

Mencantumkan kredensial untuk akun layanan

Mencantumkan kunci publik dari ProjectServiceAccount tertentu dalam project:

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

Hapus kredensial

Untuk menghapus kunci publik, gunakan konsol GDC atau gdcloud CLI.

Catatan: Menghapus kunci tidak akan mencabut kredensial berjangka pendek yang dikeluarkan dengan menggunakan kunci tersebut.

Konsol

1. Login ke konsol GDC.
2. Di menu navigasi, pilih Identity & Access > Service Identities.
3. Klik nama identitas layanan yang memiliki kunci yang ingin Anda hapus.
4. Klik Hapus.
5. Pada dialog konfirmasi, klik Delete.

gdcloud

Hapus kunci publik dengan ID kunci dari ProjectServiceAccount tertentu dalam project:

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

Memberi otorisasi akun layanan menggunakan kunci akun layanan

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan hati-hati. Lihat Mengamankan kunci akun layanan untuk mengetahui informasi tentang praktik terbaik untuk mengelola, menggunakan, dan mengamankan kunci akun layanan.

Anda dapat menggunakan perintah gdcloud untuk mengaktifkan akun layanan menggunakan kunci akun layanan:

1. Buat file kunci akun layanan, jika Anda belum memilikinya.

2. Aktifkan akun layanan dengan menjalankan perintah berikut:

   gdcloud auth activate-service-account --key-file=KEY_FILE
   

   Ganti KEY_FILE dengan jalur ke file kunci akun layanan.

   Setelah mengaktifkan akun layanan, gdcloud akan menggunakan kredensial akun layanan untuk perintah berikutnya, bukan kredensial pengguna Anda.