Mengautentikasi dengan identitas layanan

Identitas layanan dalam lingkungan air-gapped Google Distributed Cloud (GDC) menyediakan identitas khusus bagi beban kerja atau layanan untuk mengakses resource dan mikroservice secara terprogram dengan aman. Identitas ini adalah identitas khusus yang digunakan oleh aplikasi atau workload, bukan oleh pengguna, dan tidak dapat digunakan untuk login pengguna. Mirip dengan akun pengguna, Anda memberikan izin dan peran ke identitas layanan untuk menentukan apa yang diizinkan untuk diaksesnya.

Anda mungkin melihat dua istilah yang digunakan untuk konsep ini. Konsol GDC terutama menggunakan istilah identitas layanan, sementara perintah gdcloud dan interaksi API sering menggunakan istilah akun layanan. Yang terakhir mencerminkan nama resource kustom Kubernetes yang mendasarinya, ProjectServiceAccount. Kedua istilah mengacu pada hal yang sama: identitas non-manusia untuk workload Anda. Dokumen ini menggunakan identitas layanan sebagai istilah utama.

Identitas layanan berguna untuk mengelola infrastruktur GDC, seperti:

Layanan dan workload Distributed Cloud internal untuk mengakses secara aman Application Programming Interface (API) bidang kontrol Distributed Cloud. 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 application programming interface (API) yang sah. Misalnya, identitas layanan dapat mengelola pelanggan menggunakan notebook Vertex AI Workbench untuk mentranskripsikan file audio menggunakan Speech-to-Text API.
Workload eksternal untuk digabungkan dengan Distributed Cloud. Misalnya, identitas 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 dengan aman. Misalnya, identitas layanan dapat mengelola alur kerja autentikasi dan otorisasi saat pengontrol layanan yang berjalan di cluster admin perlu menjalankan workload dalam cluster pengguna yang dikelola oleh pelanggan.

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

Sebelum memulai

Anda hanya dapat membuat identitas layanan dalam project. Untuk mempelajari cara membuat project, lihat Membuat project.

Mengelola identitas layanan melibatkan identitas layanan (yang diwakili oleh resource ProjectServiceAccount) dan kredensial terkaitnya (pasangan kunci publik dan pribadi). Untuk mendapatkan izin yang diperlukan untuk mengelola identitas layanan dan kredensialnya, minta Admin IAM Organisasi atau Admin IAM Project untuk memberi Anda peran Admin IAM Project (project-iam-admin) di project tersebut.

Membuat identitas layanan

Membuat identitas layanan mencakup pembuatan akun dan kredensial terkaitnya.

Buat akun

Untuk membuat akun bagi identitas layanan, gunakan konsol GDC, gdcloud CLI, atau API untuk membuat resource ProjectServiceAccount dalam project.

Konsol

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

gdcloud

Buat akun:

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

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 ECDSA P256 PEM.
- 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.
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.

Buat kredensial

Untuk mengizinkan workload atau aplikasi diautentikasi sebagai identitas layanan (yang diwakili oleh akun yang Anda buat), Anda perlu membuat kredensial. Pembuatan kredensial melibatkan pembuatan pasangan kunci pribadi dan publik kriptografi, serta mengaitkan kunci publik dengan identitas layanan.

Untuk membuat kredensial bagi identitas layanan, gunakan konsol GDC, gdcloud CLI, atau API.

Konsol

Login ke konsol GDC.
Di menu navigasi, pilih Identity & Access > Service Identities.
Klik nama identitas layanan yang ingin Anda tambahkan di kunci.
Klik Create New Key.
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 dan 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 disetel, Anda dapat menghilangkan flag --project.
NAME: nama identitas layanan yang akan ditambahkan kuncinya.
CA_CERTIFICATE_PATH: Opsional: jalur sertifikat otoritas sertifikat (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": "/path/to/ca.crt",
"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.
ca_cert_path: jalur ke sertifikat certificate authority (CA) yang digunakan untuk memverifikasi endpoint autentikasi.
token_uri: alamat endpoint autentikasi.

API

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"
```

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)

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 ECDSA P256 PEM.
- 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.
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.
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.

Untuk mengetahui detail cara menggunakan file kunci yang dibuat untuk mengautentikasi gdcloud CLI sebagai identitas layanan ini, lihat bagian Memberi otorisasi identitas layanan menggunakan kunci.

Melihat identitas layanan

Bagian ini menjelaskan cara melihat identitas layanan Anda dan kunci publik terkaitnya.

Melihat daftar identitas layanan

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

Konsol

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

gdcloud

Mencantumkan akun identitas layanan dalam project:

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

Ganti PROJECT dengan project ID.

Melihat daftar kunci publik untuk identitas layanan

Mencantumkan kunci publik yang terdaftar dengan akun identitas layanan dalam project:

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

Ganti kode berikut:

PROJECT: project ID.
NAME: nama akun identitas layanan yang akan digunakan.

Memberikan izin untuk identitas layanan

Untuk memberikan izin ke identitas layanan, tetapkan satu atau beberapa peran dengan membuat binding peran menggunakan konsol GDC atau gdcloud CLI.

Konsol

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

gdcloud

Anda dapat mengikat akun identitas layanan ke peran dalam namespace project atau ke peran dalam namespace yang berbeda.

Ikat akun ke peran dalam namespace project:
```
gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME
```
Ganti kode berikut:
- PROJECT: project tempat binding peran akan dibuat. Jika gdcloud init sudah disetel, Anda dapat menghilangkan flag --project.
- ROLE: peran standar yang akan ditetapkan ke akun. 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.
- NAME: nama akun identitas layanan yang akan digunakan.
Ikat akun ke peran dalam namespace yang berbeda:
```
gdcloud iam service-accounts add-iam-policy-binding \
    --role=ROLE \
    --role-namespace=ROLE_NAMESPACE \
    --iam-account=NAME
```
Ganti kode berikut:
- ROLE: peran standar yang akan ditetapkan ke akun. 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 selain namespace project.
- NAME: nama akun identitas layanan yang akan digunakan.

Mengautentikasi dan menggunakan identitas layanan

Untuk mengonfigurasi gdcloud dan alat lainnya agar beroperasi sebagai identitas layanan, Anda harus terlebih dahulu melakukan autentikasi ke gdcloud menggunakan file kunci identitas layanan. Setelah diautentikasi, Anda dapat menggunakan kredensial identitas layanan untuk membuat token atau file kubeconfig.

Memberikan otorisasi identitas layanan menggunakan kunci

Perintah gdcloud auth activate-service-account mengautentikasi gdcloud CLI dengan identitas layanan. Dengan begitu, Anda dapat melakukan tindakan pada resource Distributed Cloud menggunakan izin akun identitas layanan alih-alih akun pengguna.

Memberi otorisasi identitas layanan menggunakan kunci:

Buat file kunci kredensial, jika Anda belum memilikinya.
Aktifkan identitas layanan dengan menjalankan perintah berikut:
```
gdcloud auth activate-service-account --key-file=KEY_FILE
```
Ganti KEY_FILE dengan jalur ke file kunci kredensial, biasanya dalam format JSON.

Setelah aktivasi berhasil, gdcloud menggunakan kredensial identitas layanan, bukan kredensial pengguna Anda.

Mencetak token identitas untuk identitas layanan

Setelah mengizinkan identitas layanan, Anda dapat mencetak token identitas untuknya. Anda dapat menggunakan token ini sebagai token pemilik untuk mengautentikasi permintaan HTTP. Artinya, token memberikan akses kepada pihak mana pun yang memilikinya ke layanan yang ditentukan dalam parameter AUDIENCES.

Mencetak token identitas untuk akun identitas layanan yang ditentukan:

gdcloud auth print-identity-token --audiences=AUDIENCES

Ganti AUDIENCES dengan penerima atau layanan yang dituju untuk token tersebut. Hanya satu audiens yang dapat ditentukan.

Buat file kubeconfig

Setelah mengizinkan identitas layanan, Anda dapat membuat file kubeconfig untuk melakukan autentikasi ke cluster.

Setel properti gdcloud core/organization_console_url:
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
Ganti GDC_URL dengan URL organisasi Anda.
Buat file kubeconfig untuk mengakses cluster menggunakan identitas layanan aktif:
- Untuk cluster zona:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
```
  Ganti kode berikut:
  - KUBECONFIG_PATH: jalur tempat Anda ingin menyimpan file kubeconfig yang dihasilkan.
  - CLUSTER_NAME: nama cluster zona.
    
    Catatan: Daftar nama cluster tersedia di URL konfigurasi login:
    https://GDC_URL/.well-known/login-config.
  - ZONE: nama zona tempat cluster berada.
- Untuk server API global:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials global-api
```
  Ganti KUBECONFIG_PATH dengan jalur tempat Anda ingin menyimpan file kubeconfig yang dibuat.

File kubeconfig dibuat, dikonfigurasi untuk mengautentikasi sebagai identitas layanan. Berikut contoh file YAML:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

Menghapus identitas layanan

Setelah Anda menghapus identitas layanan, ProjectServiceAccount dan kunci publik terkaitnya akan dihapus, kunci pribadi yang ada menjadi tidak valid, dan aplikasi tidak lagi memiliki akses ke resource project melalui identitas layanan tersebut.

Untuk menghapus identitas layanan, gunakan konsol GDC atau gdcloud CLI.

Konsol

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

gdcloud

Jalankan perintah berikut untuk menghapus identitas layanan:

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

Ganti kode berikut:

NAME: nama akun identitas layanan yang akan dihapus.
PROJECT: project ID.

Hapus kredensial

Jika ingin menonaktifkan pasangan kunci tertentu tanpa menghapus seluruh akun identitas layanan, Anda dapat menghapus kunci publiknya dari akun identitas layanan. Tindakan ini membuat kunci pribadi yang sesuai menjadi tidak valid.

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

Konsol

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

gdcloud

Hapus kunci publik dengan ID kunci dari akun identitas layanan di project:

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

Ganti kode berikut:

KEY_ID: ID unik kunci.
PROJECT: project ID.
NAME: nama akun identitas layanan.

Mengautentikasi dengan identitas layanan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Membuat identitas layanan

Buat akun

Konsol

gdcloud

API

Buat kredensial

Konsol

gdcloud

API

Melihat identitas layanan

Melihat daftar identitas layanan

Konsol

gdcloud

Melihat daftar kunci publik untuk identitas layanan

Memberikan izin untuk identitas layanan

Konsol

gdcloud

Mengautentikasi dan menggunakan identitas layanan

Memberikan otorisasi identitas layanan menggunakan kunci

Mencetak token identitas untuk identitas layanan

Buat file kubeconfig

Menghapus identitas layanan

Konsol

gdcloud

Hapus kredensial

Konsol

gdcloud

Mengautentikasi dengan identitas layanan