Menyiapkan cluster untuk GKE Identity Service dengan OIDC

Dokumen ini ditujukan untuk administrator cluster atau operator aplikasi yang ingin menyiapkan GKE Identity Service di cluster individual, sehingga developer dan pengguna lain dapat login ke cluster menggunakan detail identitas yang sudah ada dari penyedia OpenID Connect (OIDC). Panduan ini mengasumsikan bahwa Anda telah membaca Ringkasan Layanan Identitas GKE.

Petunjuk dalam dokumen ini mengasumsikan bahwa GKE Identity Service telah terdaftar dengan penyedia identitas Anda sebagai aplikasi klien.

Ringkasan penyiapan

Penyiapan GKE Identity Service untuk masing-masing cluster melibatkan pengguna dan langkah-langkah berikut:

  1. Administrator platform mendaftarkan GKE Identity Service sebagai aplikasi klien dengan penyedia identitas pilihan mereka dan mendapatkan client ID dan rahasia klien. Untuk melakukannya, ikuti petunjuk di Mengonfigurasi penyedia untuk GKE Identity Service.
  2. Administrator cluster mengonfigurasi cluster untuk menggunakan layanan dengan mengikuti petunjuk di halaman ini.
  3. Administrator cluster menyiapkan akses pengguna, dan secara opsional mengonfigurasi role-based access control (RBAC) Kubernetes untuk pengguna di cluster. Untuk melakukannya, ikuti petunjuk di Menyiapkan akses pengguna untuk GKE Identity Service.

Prasyarat

  • Cluster Anda harus berupa cluster GKE lokal (VMware atau bare metal), di AWS, atau di Azure. Konfigurasi OIDC per cluster tidak didukung untuk cluster terpasang atau cluster GKE.
  • Untuk melakukan autentikasi melalui Konsol Google Cloud, setiap cluster yang ingin dikonfigurasi untuk autentikasi OIDC harus didaftarkan ke fleet project Anda.

Sebelum memulai

  • Pastikan administrator platform telah memberikan semua informasi yang diperlukan dari Mendaftarkan GKE Identity Service dengan penyedia Anda sebelum memulai penyiapan, termasuk client ID dan rahasia untuk GKE Identity Service.

  • Pastikan Anda telah menginstal alat command line berikut:

    • Versi terbaru Google Cloud CLI, yang mencakup gcloud, alat command line untuk berinteraksi dengan Google Cloud. Jika Anda perlu menginstal Google Cloud CLI, lihat panduan penginstalan.
    • kubectl untuk menjalankan perintah pada cluster Kubernetes. Jika Anda perlu menginstal kubectl, ikuti instructions ini.

    Jika Anda menggunakan Cloud Shell sebagai lingkungan shell untuk berinteraksi dengan Google Cloud, alat ini diinstal untuk Anda.

  • Pastikan Anda telah melakukan inisialisasi gcloud CLI untuk digunakan dengan project tempat cluster didaftarkan.

  • Jika perlu terhubung ke bidang kontrol cluster AWS atau Azure GKE yang berada di luar VPC saat ini melalui bastion host, pastikan Anda telah membuat bastion host dan memulai tunnel SSH di port 8118 sebelum penyiapan ini. Kemudian, tambahkan perintah kubectl Anda saat mengikuti panduan ini dengan HTTPS_PROXY=http://localhost:8118. Jika Anda menggunakan port yang berbeda saat memulai tunnel SSH, ganti 8118 dengan port yang Anda pilih.

Konfigurasi cluster

Untuk mengonfigurasi cluster agar menggunakan penyedia pilihan Anda, GKE Identity Service mengharuskan Anda menentukan detail tentang penyedia identitas, informasi dalam token JWT yang disediakannya untuk identifikasi pengguna, dan informasi lain yang diberikan saat Anda mendaftarkan GKE Identity Service sebagai aplikasi klien.

Jadi, misalnya, jika penyedia Anda membuat token identitas dengan kolom berikut (di antara kolom lainnya), dengan iss sebagai URI penyedia identitas, sub akan mengidentifikasi pengguna, dan groupList mencantumkan grup keamanan yang mencakup pengguna tersebut:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

...konfigurasi Anda akan memiliki kolom sesuai berikut ini:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

Administrator platform Anda, atau siapa pun yang mengelola identitas di organisasi Anda, akan memberikan sebagian besar informasi yang dibutuhkan untuk membuat konfigurasi.

GKE Identity Service menggunakan jenis resource kustom (CRD) Kubernetes yang disebut ClientConfig untuk konfigurasi cluster, dengan kolom untuk semua informasi yang diperlukan GKE Identity Service untuk berinteraksi dengan penyedia identitas. Setiap cluster GKE memiliki resource ClientConfig bernama default di namespace kube-public yang Anda perbarui dengan detail konfigurasi, dengan mengikuti petunjuk di bawah.

Anda dapat melihat beberapa contoh konfigurasi tertentu untuk penyedia populer dalam konfigurasi khusus Penyedia.

kubectl

Untuk mengedit ClientConfig default, pastikan Anda dapat terhubung ke cluster melalui kubectl, dan menjalankan perintah berikut:

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

Ganti KUBECONFIG_PATH dengan jalur ke file kubeconfig cluster Anda, misalnya $HOME/.kube/config.

Editor teks memuat resource ClientConfig cluster Anda. Tambahkan objek spec.authentication.oidc seperti yang ditunjukkan di bawah ini. Jangan ubah data default apa pun yang telah ditulis.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_STRING
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Tabel berikut menjelaskan kolom objek oidc ClientConfig. Sebagian besar kolom bersifat opsional. Kolom yang perlu ditambahkan bergantung pada Penyedia Identitas Anda dan opsi penyiapan yang dipilih oleh admin platform saat mengonfigurasi penyedia untuk GKE Identity Service.

Kolom Diperlukan Deskripsi Format
name ya Nama yang ingin Anda gunakan untuk mengidentifikasi konfigurasi ini, biasanya nama penyedia identitas. Nama konfigurasi harus dimulai dengan huruf, diikuti dengan maksimal 39 huruf kecil, angka, atau tanda hubung, dan tidak boleh diakhiri dengan tanda hubung. String
certificateAuthorityData Tidak Jika diberikan oleh administrator platform, string sertifikat berenkode PEM untuk penyedia identitas. Sertakan string yang dihasilkan di certificateAuthorityData sebagai satu baris. String
clientID Ya Client ID yang ditampilkan saat mendaftarkan GKE Identity Service dengan penyedia OIDC Anda. String
clientSecret Tidak Rahasia bersama antara aplikasi klien OIDC dan penyedia OIDC. String
deployCloudConsoleProxy Tidak Menentukan apakah proxy di-deploy sehingga memungkinkan Konsol Google Cloud terhubung ke penyedia identitas lokal yang tidak dapat diakses secara publik melalui internet. Secara default, opsi ini ditetapkan ke false. Boolean
extraParams Tidak Parameter key=value tambahan yang akan dikirim ke penyedia identitas, yang ditetapkan sebagai daftar yang dipisahkan koma—misalnya `prompt=consent,access_type=offline`. Daftar yang dipisahkan koma
groupsClaim Tidak Klaim JWT (nama kolom) yang digunakan penyedia Anda untuk menampilkan grup keamanan akun. String
groupPrefix Tidak Awalan yang ingin ditambahkan ke nama grup keamanan untuk menghindari bentrok dengan nama yang ada dalam aturan kontrol akses jika Anda memiliki konfigurasi untuk beberapa penyedia identitas (biasanya nama penyedia). String
issuerURI Ya URI tempat permintaan otorisasi dibuat untuk penyedia identitas Anda. URI harus menggunakan HTTPS. URL String
kubectlRedirectURI Ya URL dan port alihan yang digunakan oleh gcloud CLI dan ditentukan oleh admin platform Anda saat pendaftaran, biasanya dalam bentuk `http://localhost:PORT/callback`. URL String
cakupan Ya Cakupan tambahan untuk dikirim ke penyedia OpenID. Misalnya, Microsoft Azure dan Okta memerlukan cakupan offline_access. Daftar yang dipisahkan koma
userClaim Tidak Klaim JWT (nama kolom) yang digunakan penyedia Anda untuk mengidentifikasi akun pengguna. Jika Anda tidak menentukan nilai di sini, GKE Identity Service akan menggunakan "sub", yang merupakan klaim User-ID yang digunakan oleh banyak penyedia. Anda dapat memilih klaim lain, seperti "email" atau "nama", tergantung pada penyedia OpenID. Klaim selain "email" diawali dengan URL penerbit untuk mencegah konflik penamaan. String
userPrefix Tidak Awalan yang ingin Anda tambahkan ke klaim pengguna untuk mencegah bentrokan dengan nama yang sudah ada, jika Anda tidak ingin menggunakan awalan default. String
enableAccessToken Tidak Jika diaktifkan, GKE Identity Service dapat menggunakan endpoint userinfo penyedia identitas untuk mendapatkan informasi grup saat pengguna login dari command line. Dengan begitu, Anda dapat menggunakan grup keamanan untuk otorisasi jika memiliki penyedia (seperti Okta) yang memberikan klaim grup dari endpoint ini. Jika tidak disetel, nilai ini dianggap sebagai false. Boolean
proxy Tidak Alamat server proxy yang akan digunakan untuk terhubung ke penyedia identitas, jika berlaku. Anda mungkin perlu menyetelnya jika misalnya cluster berada dalam jaringan pribadi dan perlu terhubung ke penyedia identitas publik. Misalnya: http://user:password@10.10.10.10:8888. String

Setelah Anda menyelesaikan ClientConfig, simpan file yang memperbarui ClientConfig di cluster. Jika membuat error sintaksis, Anda akan diminta untuk mengedit ulang konfigurasi guna memperbaikinya.

Konfigurasi khusus penyedia

Bagian ini memberikan panduan konfigurasi untuk beberapa penyedia OIDC populer, termasuk contoh konfigurasi yang dapat Anda salin dan edit dengan detail Anda sendiri.

Azure AD

Ini adalah konfigurasi default untuk menyiapkan GKE Identity Service dengan Azure AD. Dengan menggunakan konfigurasi ini, GKE Identity Service dapat mendapatkan informasi keanggotaan pengguna dan grup dari Azure AD, dan menyiapkan kontrol akses berbasis peran (RBAC) Kubernetes berdasarkan grup. Namun, menggunakan konfigurasi ini akan membatasi Anda untuk mengambil sekitar 200 grup per pengguna.

Jika perlu mengambil lebih dari 200 grup per pengguna, lihat petunjuk untuk Azure AD (Advanced).

...
spec:
  authentication:
  - name: oidc-azuread
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Ganti kode berikut:

  • CLIENT_ID: Client ID yang ditampilkan saat mendaftarkan GKE Identity Service dengan penyedia Anda.
  • CLIENT_SECRET: Rahasia bersama antara aplikasi klien OIDC dan penyedia OIDC.
  • TENANT: Jenis akun Azure AD yang akan diautentikasi. Nilai yang didukung adalah ID tenant, atau nama tenant untuk akun milik tenant tertentu. Nama tenant juga dikenal sebagai domain primer. Untuk mengetahui detail tentang cara menemukan nilai ini, lihat Menemukan ID tenant Microsoft Azure AD dan nama domain primer.
  • PORT: Nomor port yang dipilih untuk URL alihan yang digunakan oleh gcloud CLI, yang ditentukan oleh admin platform Anda saat pendaftaran.

Azure AD (Lanjutan)

Konfigurasi opsional untuk Azure AD ini memungkinkan GKE Identity Service mengambil informasi pengguna dan grup tanpa batasan jumlah grup per pengguna, menggunakan Microsoft Graph API.

Untuk mengetahui informasi tentang platform yang mendukung konfigurasi ini, lihat Penyiapan lanjutan untuk Azure AD.

Jika perlu mengambil kurang dari 200 grup per pengguna, sebaiknya gunakan konfigurasi default menggunakan anchor oidc di ClientConfig Anda. Untuk mengetahui informasi selengkapnya, lihat petunjuk untuk Azure AD.

Semua kolom dalam contoh konfigurasi berikut wajib diisi.

...
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Ganti kode berikut:

  • NAME: Nama yang ingin Anda gunakan untuk mengidentifikasi konfigurasi ini, biasanya nama penyedia identitas. Nama konfigurasi harus dimulai dengan huruf, diikuti dengan maksimal 39 huruf kecil, angka, atau tanda hubung, dan tidak boleh diakhiri dengan tanda hubung.
  • PROXY_URL: Alamat server proxy yang akan digunakan untuk terhubung ke penyedia identitas, jika berlaku. Anda mungkin perlu menyetelnya jika misalnya cluster berada dalam jaringan pribadi dan perlu terhubung ke penyedia identitas publik. Contoh: http://user:password@10.10.10.10:8888.
  • CLIENT_ID: Client ID yang ditampilkan saat mendaftarkan GKE Identity Service dengan penyedia Anda.
  • CLIENT_SECRET: Rahasia bersama antara aplikasi klien OIDC dan penyedia OIDC.
  • TENANT: Jenis akun Azure AD yang akan diautentikasi. Nilai yang didukung adalah ID tenant, atau nama tenant untuk akun milik tenant tertentu. Nama tenant juga dikenal sebagai domain primer. Untuk mengetahui detail tentang cara menemukan nilai ini, lihat Menemukan ID tenant Microsoft Azure AD dan nama domain primer.
  • PORT: Nomor port yang dipilih untuk URL alihan yang digunakan oleh gcloud CLI, yang ditentukan oleh admin platform Anda saat pendaftaran.
  • GROUP_FORMAT: Format yang Anda inginkan untuk mengambil informasi grup. Kolom ini dapat berisi nilai yang sesuai dengan ID atau NAME grup pengguna. Perlu diperhatikan bahwa saat ini setelan ini hanya tersedia untuk cluster Google Distributed Cloud Virtual untuk Bare Metal.
  • USER_CLAIM (Opsional): Klaim JWT (nama kolom) yang digunakan penyedia Anda untuk mengidentifikasi akun. Jika Anda tidak menentukan nilai di sini, GKE Identity Service akan menggunakan nilai dalam urutan "email", "preferred_username", atau "sub" untuk mengambil detail pengguna. Atribut ini dapat digunakan dari GKE Enterprise versi 1.28.

Okta

Berikut ini cara menyiapkan autentikasi menggunakan pengguna dan grup dengan Okta sebagai penyedia identitas. Dengan konfigurasi ini, Anthos Identity Service dapat mengambil klaim pengguna dan grup menggunakan token akses dan endpoint userinfo Okta.

...
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Batas akses grup

Untuk pengguna Okta, Anthos Identity Service dapat mengambil informasi grup untuk pengguna yang nama grupnya, jika digabungkan, memiliki panjang kurang dari 170.000 karakter. Ini sama dengan keanggotaan sekitar 650 grup berdasarkan panjang grup maksimum Okta. Jika pengguna merupakan anggota dari terlalu banyak grup, panggilan autentikasi akan gagal.

Apa langkah selanjutnya?

Setelah konfigurasi diterapkan, lanjutkan untuk menyiapkan akses pengguna ke cluster.