Menggunakan kubelogin untuk mengautentikasi pengguna di Azure Kubernetes Service

  • Artikel

Plugin kubelogin di Azure adalah plugin kredensial client-go yang mengimplementasikan autentikasi Microsoft Entra. Plugin kubelogin menawarkan fitur yang tidak tersedia di alat baris perintah kubectl.

Kluster Azure Kubernetes Service (AKS) yang terintegrasi dengan MICROSOFT Entra ID dan menjalankan Kubernetes versi 1.24 atau yang lebih baru secara otomatis menggunakan format kubelogin.

Artikel ini memberikan gambaran umum dan contoh cara menggunakan kubelogin untuk semua metode autentikasi Microsoft Entra yang didukung di AKS.

Pembatasan

  • Anda dapat menyertakan maksimum 200 grup dalam klaim Microsoft Entra JSON Web Token (JWT). Jika Anda memiliki lebih dari 200 grup, pertimbangkan untuk menggunakan peran aplikasi.
  • Grup yang dibuat di ID Microsoft Entra hanya disertakan oleh nilai ObjectID mereka, dan bukan dengan nama tampilannya. Perintah sAMAccountName hanya tersedia untuk grup yang disinkronkan dari Windows Server Active Directory lokal.
  • Di AKS, metode autentikasi perwakilan layanan hanya berfungsi dengan ID Microsoft Entra terkelola, dan bukan dengan versi Azure Active Directory sebelumnya.
  • Metode autentikasi kode perangkat tidak berfungsi saat kebijakan Microsoft Entra Conditional Access diatur pada penyewa Microsoft Entra. Dalam skenario tersebut, gunakan autentikasi interaktif browser web.

Cara kerja autentikasi

Untuk sebagian besar interaksi dengan kubelogin, Anda menggunakan convert-kubeconfig sub-perintah. Subperintah menggunakan file kubeconfig yang ditentukan dalam --kubeconfig atau dalam KUBECONFIG variabel lingkungan untuk mengonversi file kubeconfig akhir ke format exec berdasarkan metode autentikasi yang ditentukan.

Metode autentikasi yang diterapkan kubelogin adalah alur pemberian token Microsoft Entra OAuth 2.0. Bendera parameter berikut umum digunakan dalam subperindataan kubelogin. Secara umum, bendera ini siap digunakan ketika Anda mendapatkan file kubeconfig dari AKS.

  • --tenant-id: ID penyewa Microsoft Entra.
  • --client-id: ID aplikasi aplikasi klien publik. Aplikasi klien ini hanya digunakan dalam kode perangkat, interaktif browser web, dan metode masuk OAuth 2.0 Resource Owner Password Credentials (ROPC) (identitas alur kerja).
  • --server-id: ID aplikasi aplikasi web atau server sumber daya. Token dikeluarkan untuk sumber daya ini.

Catatan

Dalam setiap metode autentikasi, token tidak di-cache pada sistem file.

Metode autentikasi

Bagian berikutnya menjelaskan metode autentikasi yang didukung dan cara menggunakannya:

  • Kode perangkat
  • Azure CLI
  • Browser web interaktif
  • Perwakilan layanan
  • Identitas terkelola
  • Identitas beban kerja

Kode perangkat

Kode perangkat adalah metode autentikasi default untuk convert-kubeconfig sub-perintah. Parameter -l devicecode bersifat opsional. Metode autentikasi ini meminta kode perangkat agar pengguna masuk dari sesi browser.

Sebelum plugin kubelogin dan exec diperkenalkan, metode autentikasi Azure di kubectl hanya mendukung alur kode perangkat. Ini menggunakan versi pustaka yang lebih lama yang menghasilkan token yang memiliki audience klaim dengan awalan spn: . Ini tidak kompatibel dengan ID Microsoft Entra terkelola AKS, yang menggunakan alur atas nama (OBO). Saat Anda menjalankan convert-kubeconfig sub-perintah, kubelogin menghapus spn: awalan dari klaim audiens.

Jika persyaratan Anda termasuk menggunakan fungsionalitas dari versi sebelumnya, tambahkan --legacy argumen . Jika Anda menggunakan file kubeconfig di kluster Azure Active Directory versi sebelumnya, kubelogin secara otomatis menambahkan --legacy bendera.

Dalam metode masuk ini, token akses dan token refresh di-cache di direktori ${HOME}/.kube/cache/kubelogin . Untuk mengambil alih jalur ini, sertakan --token-cache-dir parameter .

Jika kluster terintegrasi AKS Microsoft Entra Anda menggunakan Kubernetes 1.24 atau yang lebih lama, Anda harus mengonversi format file kubeconfig secara manual dengan menjalankan perintah berikut:

export KUBECONFIG=/path/to/kubeconfig
kubelogin convert-kubeconfig

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Untuk membersihkan token yang di-cache, jalankan perintah berikut:

kubelogin remove-tokens

Catatan

Metode masuk kode perangkat tidak berfungsi saat kebijakan Akses Bersyarat dikonfigurasi pada penyewa Microsoft Entra. Dalam skenario ini, gunakan metode interaktif browser web.

Azure CLI

Metode autentikasi Azure CLI menggunakan konteks masuk yang ditetapkan Azure CLI untuk mendapatkan token akses. Token dikeluarkan dalam penyewa Microsoft Entra yang sama dengan az login. kubelogin tidak menulis token ke file cache token karena sudah dikelola oleh Azure CLI.

Catatan

Metode autentikasi ini hanya berfungsi dengan ID Microsoft Entra terkelola AKS.

Contoh berikut menunjukkan cara menggunakan metode Azure CLI untuk mengautentikasi:

az login

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l azurecli

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Jika direktori konfigurasi Azure CLI berada di luar direktori ${HOME} , gunakan --azure-config-dir parameter dengan convert-kubeconfig sub-perintah. Perintah menghasilkan file kubeconfig dengan variabel lingkungan yang dikonfigurasi. Anda bisa mendapatkan konfigurasi yang sama dengan mengatur AZURE_CONFIG_DIR variabel lingkungan ke direktori ini saat menjalankan perintah kubectl.

Browser web interaktif

Metode autentikasi interaktif browser web secara otomatis membuka browser web untuk memasukkan pengguna. Setelah pengguna diautentikasi, browser mengalihkan ke server web lokal dengan menggunakan kredensial terverifikasi. Metode autentikasi ini mematuhi kebijakan Akses Bersyar.

Saat Anda mengautentikasi dengan menggunakan metode ini, token akses di-cache di direktori ${HOME}/.kube/cache/kubelogin . Anda dapat mengambil alih jalur ini dengan menggunakan --token-cache-dir parameter .

Token pembawa

Contoh berikut menunjukkan cara menggunakan token pembawa dengan alur interaktif browser web:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Token Bukti Kepemilikan

Contoh berikut menunjukkan cara menggunakan token Proof-of-Possession (PoP) dengan alur interaktif browser web:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l interactive --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Perwakilan layanan

Metode autentikasi ini menggunakan perwakilan layanan untuk memasukkan pengguna. Anda dapat memberikan kredensial dengan mengatur variabel lingkungan atau dengan menggunakan kredensial dalam argumen baris perintah. Kredensial yang didukung yang dapat Anda gunakan adalah kata sandi atau sertifikat klien Pertukaran Informasi Pribadi (PFX).

Sebelum Anda menggunakan metode ini, pertimbangkan batasan berikut:

  • Metode ini hanya berfungsi dengan ID Microsoft Entra terkelola.
  • Perwakilan layanan dapat menjadi anggota maksimal 200 grup Microsoft Entra.

Variabel lingkungan

Contoh berikut menunjukkan cara menyiapkan rahasia klien dengan menggunakan variabel lingkungan:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<Service Principal Name (SPN) client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Kemudian jalankan perintah ini:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_SECRET=<SPN secret>

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Argumen baris perintah

Contoh berikut menunjukkan cara menyiapkan rahasia klien dalam argumen baris perintah:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --client-id <SPN client ID> --client-secret <SPN client secret>

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Peringatan

Metode argumen baris perintah menyimpan rahasia dalam file kubeconfig.

Sertifikat klien

Contoh berikut menunjukkan cara menyiapkan rahasia klien dengan menggunakan sertifikat klien:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE=/path/to/cert.pfx
export AAD_SERVICE_PRINCIPAL_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Kemudian jalankan perintah ini:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn

export AZURE_CLIENT_ID=<SPN client ID>
export AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pfx
export AZURE_CLIENT_CERTIFICATE_PASSWORD=<PFX password>

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Token PoP dan variabel lingkungan

Contoh berikut menunjukkan cara menyiapkan token PoP yang menggunakan rahasia klien yang didapatkannya dari variabel lingkungan:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l spn --pop-enabled --pop-claims "u=/ARM/ID/OF/CLUSTER"

export AAD_SERVICE_PRINCIPAL_CLIENT_ID=<SPN client ID>
export AAD_SERVICE_PRINCIPAL_CLIENT_SECRET=<SPN secret>

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Identitas Terkelola

Gunakan metode autentikasi identitas terkelola untuk aplikasi yang terhubung ke sumber daya yang mendukung autentikasi Microsoft Entra. Contohnya termasuk mengakses sumber daya Azure seperti komputer virtual Azure, set skala komputer virtual, atau Azure Cloud Shell.

Identitas terkelola default

Contoh berikut menunjukkan cara menggunakan identitas terkelola default:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Identitas tertentu

Contoh berikut menunjukkan cara menggunakan identitas terkelola dengan identitas tertentu:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l msi --client-id <msi-client-id>

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Identitas beban kerja

Metode autentikasi identitas beban kerja menggunakan kredensial identitas yang digabungkan dengan Microsoft Entra untuk mengautentikasi akses ke kluster AKS. Metode ini menggunakan autentikasi terintegrasi Microsoft Entra. Ini bekerja dengan mengatur variabel lingkungan berikut:

  • AZURE_CLIENT_ID: ID aplikasi Microsoft Entra yang digabungkan dengan identitas beban kerja.
  • AZURE_TENANT_ID: ID penyewa Microsoft Entra.
  • AZURE_FEDERATED_TOKEN_FILE: File yang berisi pernyataan identitas beban kerja yang ditandatangani, seperti token akun layanan yang diproyeksikan Kubernetes (JWT).
  • AZURE_AUTHORITY_HOST: URL dasar otoritas Microsoft Entra. Contohnya, https://login.microsoftonline.com/.

Anda dapat menggunakan identitas beban kerja untuk mengakses kluster Kubernetes dari sistem CI/CD seperti GitHub atau ArgoCD tanpa menyimpan kredensial perwakilan layanan di sistem eksternal. Untuk mengonfigurasi federasi OpenID Koneksi (OIDC) dari GitHub, lihat contoh federasi OIDC.

Contoh berikut menunjukkan cara menggunakan identitas beban kerja:

export KUBECONFIG=/path/to/kubeconfig

kubelogin convert-kubeconfig -l workloadidentity

Jalankan perintah kubectl ini untuk mendapatkan informasi node:

kubectl get nodes

Cara menggunakan kubelogin dengan AKS

AKS menggunakan sepasang aplikasi Microsoft Entra pihak pertama. ID aplikasi ini sama di semua lingkungan.

ID aplikasi server Microsoft Entra AKS yang digunakan sisi server adalah 6dae42f8-4368-4678-94ff-3960e28e3630. Token akses yang mengakses kluster AKS harus dikeluarkan untuk aplikasi ini. Dalam sebagian besar metode autentikasi kubelogin, Anda harus menggunakan --server-id dengan kubelogin get-token.

ID aplikasi klien AKS Microsoft Entra yang digunakan kubelogin untuk melakukan autentikasi klien publik atas nama pengguna adalah 80faf920-1908-4b52-b5ef-a8e7bedfc67a. ID aplikasi klien digunakan dalam kode perangkat dan metode autentikasi interaktif browser web.

Konten terkait