Menggunakan ID Beban Kerja Microsoft Entra dengan Azure Kubernetes Service (AKS)

Beban kerja yang disebarkan pada kluster AKS memerlukan kredensial aplikasi Microsoft Entra atau identitas terkelola untuk mengakses sumber daya yang dilindungi Microsoft Entra, seperti Azure Key Vault dan Microsoft Graph. ID Beban Kerja Microsoft Entra terintegrasi dengan kemampuan asli Kubernetes untuk bergabung dengan penyedia identitas eksternal, memungkinkan Anda menetapkan identitas beban kerja ke beban kerja Anda untuk mengautentikasi dan mengakses layanan dan sumber daya lain.

ID Beban Kerja Microsoft Entra menggunakan Proyeksi Volume Token Akun Layanan (atau akun layanan), untuk memungkinkan pod menggunakan identitas Kubernetes. Token Kubernetes dikeluarkan dan federasi OpenID Connect (OIDC) memungkinkan aplikasi Kubernetes mengakses sumber daya Azure dengan aman dengan MICROSOFT Entra ID, berdasarkan akun layanan yang diannotasi.

Anda dapat menggunakan ID Beban Kerja Microsoft Entra dengan pustaka klien Azure Identity atau koleksi Microsoft Authentication Library (MSAL), bersama dengan pendaftaran aplikasi, untuk mengautentikasi dan mengakses sumber daya cloud Azure dengan lancar.

Catatan

Anda dapat menggunakan Konektor Layanan untuk membantu mengonfigurasi beberapa langkah secara otomatis. Untuk informasi selengkapnya, lihat Apa itu Konektor Layanan?

Prasyarat

AKS mendukung ID Beban Kerja Microsoft Entra pada versi 1.22 dan yang lebih tinggi.
Azure CLI versi 2.47.0 atau yang lebih baru. Jalankan az --version untuk menemukan versi, dan jalankan az upgrade untuk meningkatkan versi. Jika Anda perlu memasang atau meningkatkan, lihat Memasang Azure CLI.

Batasan

Anda dapat memiliki maksimal 20 kredensial identitas federasi per identitas terkelola.
Dibutuhkan beberapa detik agar kredensial identitas federasi disebarluaskan setelah awalnya ditambahkan.
Add-on simpul virtual, yang didasarkan pada proyek sumber terbuka Virtual Kubelet, tidak didukung.
Pembuatan kredensial identitas gabungan tidak didukung pada identitas terkelola yang ditetapkan pengguna di wilayah ini.

Perpustakaan Klien Azure Identity

Di pustaka klien Azure Identity, pilih salah satu pendekatan berikut:

Gunakan DefaultAzureCredential, yang berusaha memanfaatkan WorkloadIdentityCredential.
Buat ChainedTokenCredential instance yang menyertakan WorkloadIdentityCredential.
Gunakan WorkloadIdentityCredential secara langsung.

Tabel berikut ini menyediakan versi paket minimum yang diperlukan untuk setiap pustaka klien ekosistem bahasa:

Ekosistem	Perpustakaan	Versi minimum
.NET	Azure.Identity	1.9.0
C++	azure-identity-cpp	1.6.0
Pergi	azidentity	1.3.0
Java	azure-identity	1.9.0
Node.js	@azure/identity	3.2.0
Python	azure-identity	1.13.0

Sampel kode pustaka klien Azure Identity

Sampel kode berikut menggunakan DefaultAzureCredential. Jenis kredensial ini menggunakan variabel lingkungan yang disuntikkan oleh workload identity mutating webhook untuk autentikasi dengan Azure Key Vault. Untuk melihat sampel menggunakan salah satu pendekatan lainnya, lihat pustaka klien khusus ekosistem.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

string keyVaultUrl = Environment.GetEnvironmentVariable("<key-vault-url>");
string secretName = Environment.GetEnvironmentVariable("<secret-name>");

var client = new SecretClient(
    new Uri(keyVaultUrl),
    new DefaultAzureCredential());

KeyVaultSecret secret = await client.GetSecretAsync(secretName);

#include <cstdlib>
#include <azure/identity.hpp>
#include <azure/keyvault/secrets/secret_client.hpp>

using namespace Azure::Identity;
using namespace Azure::Security::KeyVault::Secrets;

int main()
{
  const char* keyVaultUrl = std::getenv("<key-vault-url>");
  const char* secretName = std::getenv("<secret-name>");
  auto credential = std::make_shared<DefaultAzureCredential>();

  SecretClient client(keyVaultUrl, credential);
  Secret secret = client.GetSecret(secretName).Value;

  return 0;
}

package main

import (
   "context"
   "os"

   "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
   "github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets"
    "k8s.io/klog/v2"
)

func main() {
   keyVaultUrl := os.Getenv("<key-vault-url>")
   secretName := os.Getenv("<secret-name>")

   credential, err := azidentity.NewDefaultAzureCredential(nil)
   if err != nil {
      klog.Fatal(err)
   }

   client, err := azsecrets.NewClient(keyVaultUrl, credential, nil)
   if err != nil {
      klog.Fatal(err)
   }

   secret, err := client.GetSecret(context.Background(), secretName, "", nil)
   if err != nil {
      klog.ErrorS(err, "failed to get secret", "keyvault", keyVaultUrl, "secretName", secretName)
      os.Exit(1)
   }
}

import java.util.Map;

import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.DefaultAzureCredential;

public class App {
    public static void main(String[] args) {
        Map<String, String> env = System.getenv();
        String keyVaultUrl = env.get("<key-vault-url>");
        String secretName = env.get("<secret-name>");

        SecretClient client = new SecretClientBuilder()
                .vaultUrl(keyVaultUrl)
                .credential(new DefaultAzureCredentialBuilder().build())
                .buildClient();
        KeyVaultSecret secret = client.getSecret(secretName);
    }
}

import { DefaultAzureCredential } from "@azure/identity";
import { SecretClient } from "@azure/keyvault-secrets";

const main = async () => {
    const keyVaultUrl = process.env["<key-vault-url>"];
    const secretName = process.env["<secret-name>"];

    const credential = new DefaultAzureCredential();
    const client = new SecretClient(keyVaultUrl, credential);

    const secret = await client.getSecret(secretName);
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

import os

from azure.keyvault.secrets import SecretClient
from azure.identity import DefaultAzureCredential

def main():
    keyvault_url = os.getenv('<key-vault-url>', '')
    secret_name = os.getenv('<secret-name>', '')

    client = SecretClient(vault_url=keyvault_url, credential=DefaultAzureCredential())
    secret = client.get_secret(secret_name)

if __name__ == '__main__':
    main()

Microsoft Authentication Library (MSAL)

Pustaka klien berikut adalah versi minimum yang diperlukan:

Ekosistem	Perpustakaan	Gambar	Contoh	Memiliki Windows
.NET	Pustaka Autentikasi Microsoft untuk .NET	`ghcr.io/azure/azure-workload-identity/msal-net:latest`	Tautan	Ya
Pergi	Pustaka Autentikasi Microsoft untuk Go	`ghcr.io/azure/azure-workload-identity/msal-go:latest`	Tautan	Ya
Java	Microsoft Authentication Library-for-java	`ghcr.io/azure/azure-workload-identity/msal-java:latest`	Tautan	Tidak
JavaScript	Microsoft Authentication Library-for-js	`ghcr.io/azure/azure-workload-identity/msal-node:latest`	Tautan	Tidak
Python	Microsoft Authentication Library-for-python	`ghcr.io/azure/azure-workload-identity/msal-python:latest`	Tautan	Tidak

Cara kerjanya

Dalam model keamanan ini, kluster AKS bertindak sebagai penerbit token. MICROSOFT Entra ID menggunakan OIDC untuk menemukan kunci penandatanganan publik dan memverifikasi keaslian token akun layanan sebelum menukarnya dengan token Microsoft Entra. Beban kerja Anda dapat menukar token akun layanan yang diproyeksikan ke volumenya untuk token Microsoft Entra menggunakan pustaka klien Azure Identity atau MSAL.

Tabel berikut menjelaskan titik akhir penerbit OIDC yang diperlukan untuk Microsoft Entra Workload ID:

Titik akhir	Deskripsi
`{IssuerURL}/.well-known/openid-configuration`	Juga dikenal sebagai dokumen penemuan OIDC. Ini berisi metadata mengenai konfigurasi dari penerbit.
`{IssuerURL}/openid/v1/jwks`	Ini berisi kunci penandatanganan publik yang digunakan MICROSOFT Entra ID untuk memverifikasi keaslian token akun layanan.

Diagram berikut ini meringkas urutan autentikasi menggunakan OIDC:

Rotasi otomatis sertifikat webhook

Mirip dengan add-on webhook lainnya, operasi pergantian otomatis sertifikat kluster mengganti sertifikat.

Label dan anotasi akun layanan

ID Beban Kerja Microsoft Entra mendukung pemetaan berikut yang terkait dengan akun layanan:

Satu-ke-satu, di mana akun layanan mereferensikan objek Microsoft Entra.
"Banyak-ke-satu", di mana beberapa akun layanan mereferensikan objek Microsoft Entra yang sama.
Satu-ke-banyak, di mana akun layanan merujuk beberapa objek Microsoft Entra dengan memodifikasi anotasi ID klien. Untuk informasi selengkapnya, lihat Cara menggabungkan beberapa identitas dengan akun layanan Kubernetes.

Catatan

Jika Anda memperbarui anotasi akun layanan, Anda harus memulai ulang pod agar perubahan diterapkan.

Jika Anda telah menggunakan Identitas yang Dikelola oleh Pod Microsoft Entra, anggaplah akun layanan sebagai prinsipal keamanan Azure, kecuali bahwa akun layanan adalah bagian inti dari API Kubernetes, bukan CRD (Custom Resource Definition). Bagian berikut menjelaskan daftar label dan anotasi yang tersedia yang dapat Anda gunakan untuk mengonfigurasi perilaku saat bertukar token akun layanan dengan token akses Microsoft Entra.

Anotasi akun layanan

Semua anotasi bersifat opsional. Jika anotasi tidak ditentukan, nilai default akan digunakan.

Anotasi	Deskripsi	Bawaan
`azure.workload.identity/client-id`	Mewakili aplikasi Microsoft Entra ID klien yang akan digunakan dengan pod.
`azure.workload.identity/tenant-id`	Mewakili ID penyewa Azure Aplikasi Microsoft Entra terdaftar.	variabel lingkungan AZURE_TENANT_ID telah diekstraksi dari `azure-wi-webhook-config` ConfigMap.
`azure.workload.identity/service-account-token-expiration`	`expirationSeconds` Mewakili bidang untuk token akun layanan yang diproyeksikan. Ini adalah bidang opsional yang Anda konfigurasi untuk mencegah waktu henti yang disebabkan oleh kesalahan selama pembaruan token akun layanan. Kedaluwarsa token akun layanan Kubernetes tidak berkorelasi dengan token Microsoft Entra. Token Microsoft Entra kedaluwarsa dalam 24 jam setelah dikeluarkan.	3600 Rentang yang didukung adalah 3600-86400.

Label pod

Catatan

Untuk aplikasi yang menggunakan Identitas Beban Kerja Microsoft Entra, diperlukan menambahkan label azure.workload.identity/use: "true" pada spesifikasi pod agar AKS dapat memindahkan identitas beban kerja ke skenario Fail Close guna memberikan perilaku yang konsisten dan andal bagi pod yang perlu menggunakan identitas beban kerja. Jika tidak, pod akan gagal setelah dinyalakan ulang.

Label	Deskripsi	Nilai yang direkomendasikan	Wajib
`azure.workload.identity/use`	Label ini diperlukan dalam spesifikasi templat pod. Hanya pod dengan label ini yang akan dimutasi oleh webhook mutasi penerimaan azure-workload-identity untuk menyuntikkan variabel lingkungan khusus Azure dan volume token akun layanan yang diproyeksikan.	benar	Ya

Anotasi pod

Semua anotasi bersifat opsional. Jika anotasi tidak ditentukan, nilai default akan digunakan.

Anotasi	Deskripsi	Bawaan
`azure.workload.identity/service-account-token-expiration`	Lihat Anotasi akun layanan untuk detailnya. Anotasi pod lebih diutamakan daripada anotasi akun layanan.	3600 Rentang yang didukung adalah 3600-86400.
`azure.workload.identity/skip-containers`	Mewakili daftar kontainer yang dipisahkan titik koma untuk melewatkan penambahan volume token akun layanan yang diproyeksikan. Contohnya,`container1;container2`.	Secara default, volume token akun layanan yang diproyeksikan ditambahkan ke semua kontainer jika pod diberi label dengan `azure.workload.identity/use: true`.
`azure.workload.identity/inject-proxy-sidecar`	Menyuntikkan kontainer inisiasi proksi dan sidecar proksi ke dalam pod. Sidecar proxy digunakan untuk mencegat permintaan token ke IMDS dan memperoleh token Microsoft Entra atas nama pengguna dengan kredensial identitas federasi.	tidak benar
`azure.workload.identity/proxy-sidecar-port`	Mewakili port dari sidecar proxy.	8000

Migrasi ke Microsoft Entra Workload ID

Anda dapat mengonfigurasi kluster yang telah menjalankan identitas yang dikelola pod untuk menggunakan Microsoft Entra Workload ID dengan salah satu dari dua metode berikut:

Gunakan konfigurasi yang sama dengan yang telah Anda implementasikan untuk identitas yang dikelola pod. Anda dapat memberikan anotasi pada akun layanan dalam namespace dengan identitas untuk mengaktifkan ID Beban Kerja Microsoft Entra dan menyuntikkan anotasi ke dalam pod.
Tulis ulang aplikasi Anda untuk menggunakan versi terbaru pustaka klien Azure Identity.

Untuk membantu menyederhanakan dan memudahkan proses migrasi, kami mengembangkan sidecar migrasi yang mengonversi transaksi Instance Metadata Service (IMDS) yang dilakukan aplikasi Anda ke OIDC. Sidecar migrasi tidak dimaksudkan untuk menjadi solusi jangka panjang, tetapi hanya sebagai cara untuk segera beroperasi pada ID Beban Kerja Microsoft Entra. Menjalankan sidecar migrasi dalam proksi aplikasi Anda akan memproksikan transaksi IMDS aplikasi ke OIDC. Pendekatan alternatifnya adalah meningkatkan ke versi pustaka klien Azure Identity yang didukung, yang mendukung autentikasi OIDC.

Tabel berikut ini meringkas rekomendasi migrasi atau penyebaran kami untuk kluster AKS Anda:

Skenario	Deskripsi
Penyebaran kluster baru atau yang sudah ada menjalankan versi yang didukung dari pustaka klien Azure Identity.	Tidak diperlukan langkah-langkah migrasi. Sampel sumber daya penyebaran: Menyebarkan dan mengonfigurasi ID Beban Kerja Microsoft Entra pada kluster baru
Penyebaran kluster baru atau yang sudah ada menjalankan versi pustaka klien Azure Identity yang tidak didukung	Perbarui citra kontainer untuk menggunakan versi Azure Identity SDK yang didukung, atau gunakan sidecar migrasi.

Langkah berikutnya

Untuk mempelajari cara menyiapkan pod untuk mengautentikasi menggunakan identitas beban kerja sebagai opsi migrasi, lihat Memodernisasi autentikasi aplikasi dengan ID Beban Kerja Microsoft Entra.
Lihat Menyebarkan dan mengonfigurasi kluster AKS dengan ID Beban Kerja Microsoft Entra, yang membantu Anda menyebarkan kluster dan mengonfigurasi aplikasi sampel untuk menggunakan identitas beban kerja.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-10

Bagikan melalui

Menggunakan ID Beban Kerja Microsoft Entra dengan Azure Kubernetes Service (AKS)

Prasyarat

Batasan

Perpustakaan Klien Azure Identity

Sampel kode pustaka klien Azure Identity

Microsoft Authentication Library (MSAL)

Cara kerjanya

Rotasi otomatis sertifikat webhook

Label dan anotasi akun layanan

Anotasi akun layanan

Label pod

Anotasi pod

Migrasi ke Microsoft Entra Workload ID

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: