Menyiapkan cluster untuk GKE Identity Service dengan OIDC

Dokumen ini ditujukan untuk administrator cluster atau operator aplikasi yang ingin menyiapkan GKE Identity Service di tiap cluster, yang memungkinkan developer dan pengguna lain login ke cluster menggunakan detail identitas mereka yang sudah ada dari penyedia OpenID Connect (OIDC).

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 yang terpasang atau cluster GKE.
  • Untuk melakukan autentikasi melalui konsol Google Cloud, setiap cluster yang ingin dikonfigurasi untuk autentikasi OIDC harus terdaftar ke fleet project Anda.

Sebelum memulai

  • Pastikan administrator platform telah memberikan semua informasi yang diperlukan dari cara 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 terhadap cluster Kubernetes. Jika Anda perlu menginstal kubectl, ikuti petunjuk ini.

    Jika Anda menggunakan Cloud Shell sebagai lingkungan shell untuk berinteraksi dengan Google Cloud, alat ini akan 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 Anda 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 saat mengikuti panduan ini dengan HTTPS_PROXY=http://localhost:8118. Jika Anda menggunakan port lain saat memulai tunnel SSH, ganti 8118 dengan port yang Anda pilih.

Konfigurasi cluster

Untuk mengonfigurasi cluster agar menggunakan penyedia yang Anda pilih, GKE Identity Service mengharuskan Anda menentukan detail tentang penyedia identitas, informasi dalam token JWT yang diberikannya 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 (antara lain), dengan iss adalah URI penyedia identitas, sub akan mengidentifikasi pengguna, dan groupList mencantumkan grup keamanan tempat pengguna berada:

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

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

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

Administrator platform Anda, atau siapa pun yang mengelola identitas di organisasi, harus memberikan sebagian besar informasi yang diperlukan 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 spesifik untuk penyedia populer di Konfigurasi khusus penyedia.

kubectl

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

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

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

Editor teks memuat resource ClientConfig cluster Anda. Tambahkan spec.authentication.oidc seperti yang ditunjukkan di bawah ini. Jangan ubah data {i>default<i} yang sudah 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 Anda saat mengonfigurasi penyedia untuk GKE Identity Service.

Kolom Diperlukan Deskripsi Format
nama ya Nama yang ingin Anda gunakan untuk mengidentifikasi konfigurasi ini, biasanya nama penyedia identitas. Nama konfigurasi harus diawali dengan huruf, diikuti dengan maksimal 39 huruf kecil, angka, atau tanda hubung, dan tidak boleh diakhiri dengan tanda hubung. String
certificateAuthorityData Tidak Jika disediakan oleh administrator platform Anda, string sertifikat berenkode PEM untuk penyedia identitas. Sertakan hasil string di certificateAuthorityData sebagai baris tunggal. 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 yang memungkinkan Konsol Google Cloud terhubung ke penyedia identitas lokal yang tidak dapat diakses secara publik melalui internet. Secara default, parameter ini ditetapkan ke false. Boolean
extraParams Tidak Parameter key=value tambahan yang akan dikirim ke penyedia identitas, 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 Anda tambahkan ke nama grup keamanan untuk menghindari bentrok dengan nama yang sudah ada di aturan kontrol akses jika Anda memiliki konfigurasi untuk beberapa penyedia identitas (biasanya nama penyedia). String
issuerURI Ya URI tempat permintaan otorisasi dibuat ke penyedia identitas Anda. URI harus menggunakan HTTPS dan tidak boleh diakhiri dengan garis miring. URL String
kubectlRedirectURI YaURL alihan dan port 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 dikirimkan 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 ID pengguna 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 ditambahkan ke klaim pengguna untuk mencegah bentrok 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. Hal ini memungkinkan Anda menggunakan grup keamanan untuk otorisasi jika Anda memiliki penyedia (seperti Okta) yang memberikan klaim grup dari endpoint ini. Jika tidak disetel, nilai ini akan dianggap false. Boolean
proxy Tidak Alamat server proxy yang akan digunakan untuk terhubung ke penyedia identitas, jika berlaku. Anda mungkin perlu menyetelnya jika, misalnya, cluster Anda 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 tersebut, yang akan 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 memperoleh pengguna serta informasi keanggotaan grup dari Azure AD, dan memungkinkan Anda mengatur Kontrol akses berbasis peran (RBAC) Kubernetes berdasarkan grup. Namun, menggunakan konfigurasi ini membatasi Anda untuk mengambil sekitar 200 grup per pengguna.

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

...
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 pada jumlah grup per pengguna, menggunakan Microsoft Graph API.

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

Jika Anda perlu mengambil kurang dari 200 grup per pengguna, sebaiknya gunakan konfigurasi default menggunakan anchor oidc di ClientConfig. Untuk 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 diawali 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 Anda 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 tempat Anda ingin mengambil informasi grup. Kolom ini dapat mengambil nilai yang sesuai dengan ID atau NAME grup pengguna. Perlu diperhatikan bahwa saat ini setelan ini hanya tersedia untuk cluster dalam deployment Google Distributed Cloud 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

Di bawah ini menunjukkan kepada Anda cara menyiapkan otentikasi menggunakan pengguna dan grup dengan Okta sebagai penyedia identitas. Konfigurasi ini memungkinkan Anthos Identity Layanan mengambil klaim pengguna dan grup dengan menggunakan token akses dan endpoint info pengguna.

...
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. Hal ini sesuai dengan keanggotaan sekitar 650 grup, mengingat nilai maksimum panjang grup. Jika pengguna adalah anggota terlalu banyak grup, otentikasi gagal.

Apa langkah selanjutnya?

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