Menyiapkan cluster anggota fleet untuk autentikasi OIDC

Dokumen ini menjelaskan cara administrator cluster atau operator aplikasi dapat mengonfigurasi cluster untuk mendukung autentikasi menggunakan penyedia OpenID Connect (OIDC) pihak ketiga.

Batasan

Anda harus menggunakan jenis cluster yang mendukung OIDC.

Sebelum memulai

1. Install the Google Cloud CLI.

2. Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

3. Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

   gcloud init

4. Setelah melakukan inisialisasi gcloud CLI, update gcloud CLI dan instal komponen yang diperlukan:

   gcloud components update
   gcloud components install kubectl

5. Pastikan administrator platform Anda telah memberi Anda semua informasi penyedia yang Anda butuhkan. Untuk mengetahui informasi selengkapnya, lihat Membagikan detail penyedia identitas.
6. Untuk melakukan autentikasi menggunakan konsol Google Cloud , daftarkan setiap cluster yang ingin Anda konfigurasi ke fleet project Anda. Untuk mengetahui informasi selengkapnya, lihat Ringkasan pembuatan armada.
7. Untuk terhubung ke bidang kontrol cluster AWS atau Azure yang berada di luar jaringan VPC saat ini melalui bastion host, pastikan Anda telah membuat bastion host dan memulai tunnel SSH di port 8118. Saat menjalankan perintah kubectl dalam dokumen ini, tambahkan awalan HTTPS_PROXY=http://localhost:PORT pada perintah, dengan PORT adalah nomor port yang Anda gunakan saat memulai tunnel SSH.
8. Untuk cluster GKE di Google Cloud, daftarkan cluster ke fleet Anda.

Konfigurasi cluster

Untuk mengonfigurasi autentikasi ke cluster menggunakan OIDC, Anda menambahkan informasi berikut ke resource kustom Kubernetes bernama ClientConfig:

• Informasi tentang penyedia identitas Anda, seperti ID klien dan rahasia.
• Informasi tentang Token Web JSON (JWT) yang digunakan penyedia identitas Anda untuk autentikasi.
• Cakupan atau parameter tambahan yang unik untuk penyedia identitas Anda.

Untuk mengetahui informasi selengkapnya tentang informasi yang Anda butuhkan dari administrator platform Anda, atau siapa pun yang mengelola identitas di organisasi Anda, lihat Membagikan detail penyedia identitas.

Cluster menggunakan kolom di resource kustom ClientConfig untuk berinteraksi dengan penyedia identitas Anda. Setiap cluster memiliki ClientConfig bernama default di namespace kube-public. Kolom spesifik yang Anda ubah bergantung pada penyedia identitas Anda.

Untuk mengedit default ClientConfig, pastikan Anda dapat terhubung ke cluster kubectl, lalu jalankan 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 dalam contoh berikut. Jangan ubah data default yang telah ditulis.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
      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.

Misalnya, pertimbangkan kolom token identitas berikut:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['[e-mail]', '[e-mail]']
  # Multiple lines are omitted here
}

Dalam contoh ini, iss adalah URI penyedia identitas, sub mengidentifikasi pengguna, dan groupList mencantumkan grup keamanan tempat pengguna berada. Contoh ini hanya menampilkan contoh kolom yang mungkin dimiliki token sebenarnya.

Untuk token contoh sebelumnya, Anda memperbarui kolom berikut dalam objek spec.authentication.oidc ClientConfig:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

Anda dapat menambahkan beberapa konfigurasi penyedia identitas OIDC, LDAP, dan SAML ke ClientConfig yang sama. Cluster mencoba mengautentikasi dengan setiap konfigurasi dalam urutan yang ditentukan, dan berhenti setelah autentikasi pertama berhasil. Contoh ClientConfig berikut menentukan beberapa penyedia identitas dalam urutan tertentu:

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

Kolom OIDC ClientConfig

Tabel berikut menjelaskan kolom objek ClientConfig oidc. Kolom yang perlu Anda tambahkan bergantung pada token penyedia identitas dan cara administrator platform Anda mengonfigurasi penyedia.

Kolom	Diperlukan	Deskripsi	Format
nama	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 disediakan oleh administrator platform Anda, string sertifikat berenkode PEM untuk penyedia identitas. Sertakan string yang dihasilkan dalam certificateAuthorityData sebagai satu baris.	String
clientID	Ya	ID klien dari penyedia identitas.	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, nilai ini ditetapkan ke false.	Boolean
extraParams	Tidak	Parameter key=value tambahan untuk dikirim ke penyedia identitas, yang ditentukan 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 bentrokan 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 ke penyedia identitas Anda. URI harus menggunakan HTTPS dan tidak boleh diakhiri dengan garis miring di akhir.	URL String
kubectlRedirectURI	Ya	URL pengalihan 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 yang akan 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, nilai defaultnya adalah "sub", yang merupakan klaim ID pengguna yang digunakan oleh banyak penyedia. Anda dapat memilih klaim lain, seperti "email" atau "name", bergantung pada penyedia OpenID. Klaim selain "email" diberi awalan URL penerbit untuk mencegah bentrokan penamaan.	String
userPrefix	Tidak	Awalan yang ingin ditambahkan ke klaim pengguna untuk mencegah bentrokan dengan nama yang ada, jika Anda tidak ingin menggunakan awalan default.	String
enableAccessToken	Tidak	Jika diaktifkan, cluster 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 menyediakan klaim grup dari endpoint ini. Jika tidak disetel, nilai ini dianggap false.	Boolean
proxy	Tidak	Alamat server proxy yang akan digunakan untuk terhubung ke penyedia identitas, jika ada. Anda mungkin perlu menyetel ini jika, misalnya, cluster Anda berada di jaringan pribadi dan perlu terhubung ke penyedia identitas publik. Misalnya: http://user:password@10.10.10.10:8888.	String

Setelah mengedit ClientConfig, simpan file untuk memperbarui ClientConfig bagi cluster Anda. Jika Anda membuat kesalahan sintaksis, Anda akan melihat perintah untuk memperbaiki kesalahan tersebut dan menyimpan file.

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.

Perhatian: Anda harus menggunakan metode OIDC standar atau Microsoft Entra ID (Lanjutan). Jangan terapkan keduanya. Konfigurasi ini tidak dapat muncul bersamaan. Jika mencoba menggunakan keduanya secara bersamaan, plugin OIDC standar akan menggantikan plugin Microsoft Entra ID (Lanjutan), yang menyebabkan kegagalan autentikasi bagi pengguna dengan lebih dari 200 keanggotaan grup.

Microsoft Entra ID

Ini adalah konfigurasi default untuk menyiapkan cluster untuk autentikasi dengan Microsoft Entra ID. Dengan konfigurasi ini, cluster dapat memperoleh informasi keanggotaan pengguna dan grup dari Microsoft Entra ID, dan Anda dapat menyiapkan 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 petunjuk untuk Microsoft Entra ID (Lanjutan).

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    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
# Multiple lines are omitted here. Do not modify any pre-filled data.

Ganti kode berikut:

• CLIENT_ID: ID klien dari Microsoft Entra ID.
• CLIENT_SECRET: Rahasia bersama antara aplikasi klien OIDC dan penyedia OIDC.
• TENANT_ID: Jenis akun Microsoft Entra ID yang akan diautentikasi. Nilai yang didukung adalah ID tenant, atau nama tenant untuk akun yang termasuk dalam tenant tertentu. Nama tenant juga dikenal sebagai domain utama. Untuk mengetahui detail cara menemukan nilai ini, lihat Menemukan ID tenant Microsoft Entra dan nama domain utama.
• PORT: Nomor port yang dipilih untuk URL pengalihan yang digunakan oleh gcloud CLI, yang ditentukan oleh administrator platform Anda saat pendaftaran.

Microsoft Entra ID (Tingkat Lanjut)

Konfigurasi opsional untuk Microsoft Entra ID ini memungkinkan cluster 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 Microsoft Entra ID.

Jika Anda 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 Microsoft Entra ID.

Semua kolom dalam konfigurasi contoh berikut bersifat wajib.

# Multiple lines are omitted here.
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
# Multiple lines are omitted here. Do not modify any pre-filled data.

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 ada. Anda mungkin perlu menyetel ini jika, misalnya, cluster Anda berada di jaringan pribadi dan perlu terhubung ke penyedia identitas publik. Contoh: http://user:password@10.10.10.10:8888.
• CLIENT_ID: ID klien dari Microsoft Entra ID.
• CLIENT_SECRET: Rahasia bersama antara aplikasi klien OIDC dan penyedia OIDC.
• TENANT: Jenis akun Microsoft Entra yang akan diautentikasi. Nilai yang didukung adalah ID tenant, atau nama tenant untuk akun yang termasuk dalam tenant tertentu. Nama tenant juga dikenal sebagai domain utama. Untuk mengetahui detail cara menemukan nilai ini, lihat Menemukan ID tenant Microsoft Entra dan nama domain utama.
• PORT: Nomor port yang dipilih untuk URL pengalihan yang digunakan oleh gcloud CLI, yang ditentukan oleh administrator platform Anda saat pendaftaran.
• GROUP_FORMAT: Format yang Anda inginkan untuk mengambil informasi grup. Kolom ini dapat mengambil nilai yang sesuai dengan ID atau NAME grup pengguna. Perhatikan bahwa 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, cluster akan menggunakan nilai dalam urutan "email", "preferred_username", atau "sub" untuk mengambil detail pengguna. Atribut ini dapat digunakan mulai versi 1.28.

Okta

Berikut cara menyiapkan autentikasi menggunakan pengguna dan grup dengan Okta sebagai penyedia identitas Anda. Konfigurasi ini memungkinkan cluster mengambil klaim pengguna dan grup menggunakan token akses dan endpoint userinfo Okta.

Catatan: Meskipun konfigurasi ini ditujukan untuk Okta, Anda juga dapat mengambil informasi pengguna dan grup dari penyedia identitas lain yang mendukung endpoint userinfo. Dalam konfigurasi Anda, tentukan enableAccessToken: true untuk menggunakan fitur ini.

# Multiple lines are omitted here.
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
# Multiple lines are omitted here. Do not modify any pre-filled data.

Batasan akses grup

Untuk pengguna Okta, cluster 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 panjang grup maksimum Okta. Jika pengguna adalah anggota terlalu banyak grup, panggilan autentikasi akan gagal.

Apa langkah selanjutnya?

Setelah konfigurasi diterapkan, lanjutkan menyiapkan akses pengguna ke cluster.