Używanie Identyfikatora obciążeń Microsoft Entra w usłudze Azure Kubernetes Service (AKS)

Artykuł
2025-04-04

Obciążenia wdrożone w klastrze usług Azure Kubernetes Services (AKS) wymagają poświadczeń aplikacji Microsoft Entra lub zarządzanych tożsamości w celu uzyskania dostępu do chronionych zasobów firmy Microsoft, takich jak Azure Key Vault i Microsoft Graph. Identyfikator obciążeń Microsoft Entra integruje się z natywnymi funkcjami platformy Kubernetes w celu federacji z zewnętrznymi dostawcami tożsamości.

Microsoft Entra Workload ID używa Service Account Token Volume Projection (czyli konta usługi), aby umożliwić zasobnikom korzystanie z tożsamości Kubernetes. Wystawiony jest token Kubernetes, a federacja OIDC umożliwia aplikacjom Kubernetes bezpieczne uzyskiwanie dostępu do zasobów platformy Azure za pomocą identyfikatora Entra firmy Microsoft na podstawie kont usług z adnotacjami.

Tożsamość obciążeń Microsoft Entra działa szczególnie dobrze z bibliotekami klienckimi tożsamości Azure lub kolekcją biblioteki Microsoft Authentication Library (MSAL) wraz z rejestracją aplikacji. Obciążenie może używać dowolnej z tych bibliotek do bezproblemowego uwierzytelniania zasobów w chmurze platformy Azure i uzyskiwania do nich dostępu.

Ten artykuł pomaga zrozumieć pojęcie Workload ID w Microsoft Entra oraz omawia dostępne opcje planowania strategii projektu i potencjalnej migracji z tożsamości zarządzanej przez pod w Microsoft Entra.

Uwaga

Możesz użyć łącznika usługi, aby ułatwić automatyczne konfigurowanie niektórych kroków. Zobacz również: Co to jest łącznik usługi?

Zależności

Usługa AKS obsługuje Tożsamość obciążeń Microsoft Entra w wersji 1.22 lub nowszej.
Interfejs wiersza polecenia platformy Azure w wersji 2.47.0 lub nowszej. Uruchom polecenie az --version , aby znaleźć wersję i uruchomić polecenie az upgrade , aby uaktualnić wersję. Jeśli konieczna będzie instalacja lub uaktualnienie, zobacz Instalowanie interfejsu wiersza polecenia platformy Azure.

Biblioteki klienta tożsamości platformy Azure

W bibliotekach klienta usługi Azure Identity wybierz jedną z następujących metod:

Użyj elementu DefaultAzureCredential, który próbuje użyć elementu WorkloadIdentityCredential.
Utwórz instancję ChainedTokenCredential, która obejmuje WorkloadIdentityCredential.
Użyj WorkloadIdentityCredential bezpośrednio.

Poniższa tabela zawiera minimalną wersję pakietu wymaganą dla biblioteki klienta ekosystemu języka.

Ekosystem	Biblioteka	Minimalna wersja
.NET	Azure.Identity	1.9.0
C++	azure-identity-cpp	1.6.0
Idź	azidentity	1.3.0
Java	azure-identity	1.9.0
Node.js	@azure/identity	3.2.0
Python	azure-identity	1.13.0

W poniższych przykładach kodu używany jest DefaultAzureCredential. Ten typ poświadczeń używa zmiennych środowiskowych wstrzykiwanych przez modyfikujący webhook tożsamości obciążenia dla Azure do logowania się w usłudze Azure Key Vault. Aby wyświetlić przykłady korzystające z jednego z innych podejść, zapoznaj się z powyższymi linkami biblioteki klienta specyficznymi dla ekosystemu.

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

string keyVaultUrl = Environment.GetEnvironmentVariable("KEYVAULT_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("KEYVAULT_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("KEYVAULT_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("KEYVAULT_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["KEYVAULT_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('KEYVAULT_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()

Biblioteka uwierzytelniania firmy Microsoft (MSAL)

Następujące biblioteki klienckie są wymaganą minimalną wersją.

Ekosystem	Biblioteka	Obraz	Przykład	Posiada system Windows
.NET	Biblioteka uwierzytelniania firmy Microsoft dla dotnet	`ghcr.io/azure/azure-workload-identity/msal-net:latest`	Link	Tak
Idź	Biblioteka uwierzytelniania Microsoft dla języka Go	`ghcr.io/azure/azure-workload-identity/msal-go:latest`	Link	Tak
Java	Biblioteka uwierzytelniania firmy Microsoft dla języka Java	`ghcr.io/azure/azure-workload-identity/msal-java:latest`	Link	Nie.
JavaScript	Biblioteka uwierzytelniania firmy Microsoft dla języka js	`ghcr.io/azure/azure-workload-identity/msal-node:latest`	Link	Nie.
Python	Biblioteka uwierzytelniania firmy Microsoft dla języka Python	`ghcr.io/azure/azure-workload-identity/msal-python:latest`	Link	Nie.

Ograniczenia

Możesz mieć maksymalnie 20 poświadczeń tożsamości federacyjnej dla tożsamości zarządzanej.
Propagacja federacyjnych poświadczeń tożsamości po ich dodaniu trwa kilka sekund.
Dodatek węzłów wirtualnych, oparty na projekcie typu otwartego źródła Virtual Kubelet, nie jest obsługiwany.
Tworzenie poświadczeń tożsamości federacyjnej nie jest obsługiwane w przypadku tożsamości zarządzanych przypisanych przez użytkownika w tych regionach.

Jak to działa

W tym modelu zabezpieczeń klaster usługi AKS działa jako wystawca tokenu. Microsoft Entra ID używa openID Connect do odnajdywania publicznych kluczy podpisywania i weryfikowania autentyczności tokenu konta usługi przed wymianą go dla tokenu Microsoft Entra. Twoje obciążenie pracą może wymienić token konta usługi przypisanego do jego wolumenu na token Microsoft Entra, korzystając z biblioteki klienta Azure Identity lub biblioteki Microsoft Authentication Library (MSAL).

W poniższej tabeli opisano wymagane punkty końcowe wystawcy OIDC dla Microsoft Entra Workload ID.

Punkt końcowy	opis
`{IssuerURL}/.well-known/openid-configuration`	Znaany również jako dokument odkrywania OIDC. Zawiera metadane dotyczące konfiguracji wystawcy.
`{IssuerURL}/openid/v1/jwks`	Zawiera on publiczne klucze podpisywania używane przez firmę Microsoft Entra ID w celu zweryfikowania autentyczności tokenu konta usługi.

Na poniższym diagramie przedstawiono podsumowanie sekwencji uwierzytelniania przy użyciu programu OpenID Connect.

Automatyczne odnawianie certyfikatu webhook

Podobnie jak w przypadku innych dodatków webhook, certyfikat podlega automatycznej rotacji certyfikatu klastra.

Etykiety i adnotacje konta usługi

Tożsamość obciążeń Microsoft Entra obsługuje następujące mapowania odnoszące się do konta usługi:

Jeden do jednego, gdzie konto usługi odwołuje się do obiektu Microsoft Entra.
Wiele do jednego – przypadek, gdy wiele kont usług odwołuje się do tego samego obiektu Microsoft Entra.
Jeden do wielu, gdzie konto serwisowe odnosi się do wielu obiektów Microsoft Entra, poprzez zmianę adnotacji identyfikatora klienta. Aby uzyskać więcej informacji, zobacz How to federate multiple identities with a Kubernetes service account (Jak sfederować wiele tożsamości przy użyciu konta usługi Kubernetes).

Uwaga

Jeśli adnotacje konta usługi zostały zaktualizowane, należy ponownie uruchomić zasobnik, aby zmiany weszły w życie.

Jeśli używasz tożsamości zarządzanej przez zasobniki Microsoft Entra, pomyśl o koncie usługi jako jednostce zabezpieczeń platformy Azure, z tą różnicą, że konto usługi jest częścią podstawowego interfejsu API Kubernetes, a nie niestandardowej definicji zasobów (CRD). W poniższych sekcjach opisano listę dostępnych etykiet i adnotacji, które mogą służyć do konfigurowania zachowania podczas wymiany tokenu konta usługi dla tokenu dostępu firmy Microsoft Entra.

Adnotacje konta usługi

Wszystkie adnotacje są opcjonalne. Jeśli adnotacja nie zostanie określona, zostanie użyta wartość domyślna.

Adnotacja	opis	Wartość domyślna
`azure.workload.identity/client-id`	Reprezentuje aplikację Firmy Microsoft Entra identyfikator klienta do użycia z pod.
`azure.workload.identity/tenant-id`	Reprezentuje identyfikator dzierżawy platformy Azure, w którym Zarejestrowano aplikację Microsoft Entra.	Zmienna środowiskowa AZURE_TENANT_ID została wyodrębniona z `azure-wi-webhook-config` obiektu ConfigMap.
`azure.workload.identity/service-account-token-expiration`	Reprezentuje pole `expirationSeconds` dla przewidywany token konta usługi. Jest to pole opcjonalne, które można skonfigurować, aby zapobiec przestojom spowodowane błędami podczas odświeżania tokenu konta usługi. Wygaśnięcie tokenu konta usługi Kubernetes nie jest skorelowane z tokenami firmy Microsoft Entra. Tokeny firmy Microsoft Entra wygasają po upływie 24 godzin od ich wystawienia.	3600 Obsługiwany zakres to 3600-86400.

Etykiety zasobników

Uwaga

W przypadku aplikacji używających tożsamości obciążenia roboczego, należy dodać etykietę azure.workload.identity/use: "true" do specyfikacji zasobnika dla usługi AKS, aby przenieść tożsamość obciążenia roboczego do scenariusza Fail Close, zapewniając spójne i niezawodne działanie dla zasobników, które muszą korzystać z tożsamości obciążenia roboczego. W przeciwnym razie pody ulegają awarii po ponownym uruchomieniu.

Etykieta	opis	Zalecana wartość	Wymagane
`azure.workload.identity/use`	Ta etykieta jest wymagana w specyfikacji szablonu zasobnika. Tylko zasobniki z tą etykietą są zmodyfikowane przez webhook przyjęcia mutującego azure-workload-identity, aby wstrzyknąć zmienne środowiskowe specyficzne dla platformy Azure i wolumin przewidywanego tokenu konta usługi.	prawda	Tak

Adnotacje zasobników

Wszystkie adnotacje są opcjonalne. Jeśli adnotacja nie zostanie określona, zostanie użyta wartość domyślna.

Adnotacja	opis	Wartość domyślna
`azure.workload.identity/service-account-token-expiration`	`expirationSeconds` Reprezentuje pole dla przewidywanego tokenu konta usługi. Jest to opcjonalne pole, które można skonfigurować, aby zapobiec wszelkim przestojom spowodowanym przez błędy podczas odświeżania tokenu konta usługi. Wygaśnięcie tokenu konta usługi Kubernetes nie jest skorelowane z tokenami firmy Microsoft Entra. Tokeny firmy Microsoft Entra wygasają po upływie 24 godzin od ich wystawienia. ¹	3600 Obsługiwany zakres to 3600-86400.
`azure.workload.identity/skip-containers`	Reprezentuje rozdzieloną średnikami listę kontenerów, aby pominąć dodawanie przewidywanego woluminu tokenu konta usługi. Na przykład `container1;container2`.	Domyślnie przewidywany wolumin tokenu konta usługi jest dodawany do wszystkich kontenerów, jeśli zasobnik ma etykietę `azure.workload.identity/use: true`.
`azure.workload.identity/inject-proxy-sidecar`	Wprowadza kontener init serwera proxy i przyczepkę serwera proxy do zasobnika. Element pomocniczy proxy jest używany do przechwytywania żądań tokenu do IMDS i uzyskiwania tokenu Microsoft Entra w imieniu użytkownika z federacyjnym poświadczeniem tożsamości.	prawda
`azure.workload.identity/proxy-sidecar-port`	Reprezentuje port przyczepki serwera proxy.	8000

¹ Ma pierwszeństwo, jeśli konto usługi jest również opatrzone adnotacjami.

Jak przeprowadzić migrację do Microsoft Entra Workload ID

Na klastrze, w którym jest już uruchomiona tożsamość zarządzana przez pod, można ją skonfigurować do korzystania z tożsamości obciążenia pracą na jeden z dwóch sposobów. Pierwsza opcja umożliwia użycie tej samej konfiguracji, którą zaimplementowano dla pod-managed identity. Możesz dodać adnotacje do konta usługi w przestrzeni nazw przy użyciu tożsamości, aby włączyć Tożsamość obciążeń Microsoft Entra i wstrzyknąć adnotacje do zasobników.

Drugą opcją jest ponowne zapisywanie aplikacji w celu korzystania z najnowszej wersji biblioteki klienta tożsamości platformy Azure.

Aby usprawnić i ułatwić proces migracji, opracowaliśmy przyczepkę migracji, która konwertuje transakcje IMDS tworzone przez aplikację na openID Connect (OIDC). Sidecar migracyjny nie jest przeznaczony jako rozwiązanie długoterminowe, lecz jako sposób na szybkie rozpoczęcie pracy z tożsamością obciążenia roboczego. Uruchamianie sidecaru migracyjnego wewnątrz aplikacji pośredniczy w transakcjach IMDS do OIDC. Alternatywną metodą jest uaktualnienie do obsługiwanej wersji biblioteki klienta tożsamości platformy Azure, która obsługuje uwierzytelnianie OIDC.

W poniższej tabeli podsumowano nasze zalecenia dotyczące migracji lub wdrożenia dotyczące tożsamości obciążenia.

Scenariusz	opis
Istniejące lub nowe wdrożenie klastra uruchamia obsługiwaną wersję biblioteki klienta tożsamości Azure	Nie są wymagane żadne kroki migracji. Przykładowe zasoby wdrażania: wdrażanie i konfigurowanie tożsamości obciążenia w nowym klastrze
Nowe lub istniejące wdrożenie klastra uruchamia nieobsługiwaną wersję biblioteki klienta tożsamości platformy Azure	Zaktualizuj obraz kontenera, aby użyć obsługiwanej wersji Azure Identity SDK lub użyj usługi dodatkowej migracji.

Następne kroki

Aby dowiedzieć się, jak skonfigurować zasobnik do uwierzytelniania za pomocą tożsamości obciążenia jako opcji migracji, zajrzyj do Modernizowanie uwierzytelniania aplikacji z użyciem tożsamości obciążenia.
Zobacz Wdrażanie i konfigurowanie klastra AKS z tożsamością obciążenia, co pomoże wdrożyć klaster usługi Azure Kubernetes Service i skonfigurować przykładową aplikację do korzystania z tożsamości obciążenia.

Udostępnij za pośrednictwem

Używanie Identyfikatora obciążeń Microsoft Entra w usłudze Azure Kubernetes Service (AKS)

Zależności

Biblioteki klienta tożsamości platformy Azure

Biblioteka uwierzytelniania firmy Microsoft (MSAL)

Ograniczenia

Jak to działa

Automatyczne odnawianie certyfikatu webhook

Etykiety i adnotacje konta usługi

Adnotacje konta usługi

Etykiety zasobników

Adnotacje zasobników

Jak przeprowadzić migrację do Microsoft Entra Workload ID

Następne kroki

Dodatkowe zasoby