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

Obciążenia wdrożone w klastrze usługi AKS wymagają poświadczeń aplikacji firmy Microsoft lub tożsamości zarządzanych w celu uzyskania dostępu do chronionych zasobów firmy Microsoft, takich jak Azure Key Vault i Microsoft Graph. Tożsamość obciążeń Microsoft Entra integruje się z wbudowanymi funkcjami Kubernetes, aby łączyć się z zewnętrznymi dostawcami tożsamości, co umożliwia przypisywanie tożsamości obciążeniom w celu uwierzytelniania i uzyskiwania dostępu do innych usług i zasobów.

Uwaga

Workload ID obejmuje scenariusz tożsamości pod-to-Azure w usłudze AKS — sposób, w jaki aplikacje uruchomione w zasobnikach uwierzytelniają się wobec usług chronionych przez Microsoft Entra. W usłudze AKS Automatic tożsamość obciążenia roboczego oparta na Tożsamość obciążeń Microsoft Entra oraz wystawca klastra OIDC są domyślnie skonfigurowane — nie jest wymagana konfiguracja na poziomie klastra. W usłudze AKS Standard można włączyć i skonfigurować tożsamość obciążenia oddzielnie. Inne scenariusze tożsamości (uwierzytelnianie i autoryzacja płaszczyzny sterowania oraz zarządzane tożsamości między klastrem a platformą Azure) można znaleźć w temacie Opcje dostępu i tożsamości dla AKS.

Tip

Jeśli używasz klastra AKS Automatic, tożsamość obciążenia Tożsamość obciążeń Microsoft Entra oraz wystawca OIDC klastra są domyślnie skonfigurowane. Możesz pominąć konfigurację na poziomie klastra i przejść bezpośrednio do konfigurowania aplikacji w celu korzystania z tożsamości obciążenia. Aby uzyskać więcej informacji na temat domyślnych ustawień zabezpieczeń usługi AKS Automatic, zobacz artykuł Co to jest usługa Azure Kubernetes Service Automatic?

Tożsamość obciążeń Microsoft Entra używa projekcji woluminu tokenu konta usługi, aby umożliwić zasobnikom korzystanie z tożsamości Kubernetes. Token Kubernetes jest wystawiany, a federacja OpenID Connect (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.

Można używać usługi Tożsamość obciążeń Microsoft Entra wraz z bibliotekami klienckimi tożsamości platformy Azure lub kolekcją Microsoft Authentication Library (MSAL) oraz rejestracją aplikacji, aby bezproblemowo uwierzytelniać i uzyskiwać dostęp do zasobów w chmurze platformy Azure.

Uwaga

Możesz użyć łącznika usługi, aby ułatwić automatyczne konfigurowanie niektórych kroków. Aby uzyskać więcej informacji, zobacz Co to jest łącznik usługi?

Wymagania wstępne

Automatyczne klastry AKS

W klastrach automatycznych usługi AKS tożsamość obciążeń i wystawca OIDC klastra są wstępnie skonfigurowane w ramach domyślnych ustawień zabezpieczeń klastra. Przed użyciem tożsamości obciążeń w Twoich zasobnikach nie jest wymagana żadna konfiguracja na poziomie klastra. Przejdź bezpośrednio do konfigurowania aplikacji.

Klastry AKS w warstwie Standard

• Usługa AKS obsługuje Identyfikator 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.
• Aby zasobniki mogły korzystać z tożsamości obciążenia, należy wcześniej włączyć w klastrze tożsamość obciążenia oraz wystawcę tokenów OIDC. Zobacz Wdrażanie i konfigurowanie tożsamości obciążenia w klastrze AKS.

Ograniczenia

• Możesz mieć maksymalnie 20 poświadczeń tożsamości federacyjnej dla tożsamości zarządzanej.
• Po dodaniu poświadczeń tożsamości federacyjnej, ich propagacja trwa kilka sekund.
• Dodatek węzłów wirtualnych oparty na projekcie typu open source 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.

Biblioteki tożsamości klienta 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.

Podczas żądania tokenów przy użyciu WorkloadIdentityCredential przekaż zakresy, używając formatu Microsoft Entra ID v2 <resource>/.default, na przykład https://management.azure.com/.default. Pierwotny identyfikator URI zasobu, taki jak https://management.azure.com/, może zakończyć się niepowodzeniem, ponieważ tożsamość obciążenia używa punktu końcowego tokenu Microsoft Entra w wersji 2, a nie przepływu IMDS resource używanego przez tożsamość zarządzaną. Aby uzyskać więcej informacji o tym, jak działają zakresy w punkcie końcowym tokenu v2, zobacz Pobieranie tokenu.

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
Go	azidentity	1.3.0
Java	azure-identity	1.9.0
Node.js	@azure/identity	3.2.0
Python	azure-identity	1.13.0

Przykłady kodu biblioteki klienta usługi Azure Identity

W poniższych przykładach kodu użyto metody DefaultAzureCredential. Ten typ poświadczeń używa zmiennych środowiskowych wstrzykiwanych przez tożsamość obciążenia modyfikowaną webhook do uwierzytelniania w usłudze Azure Key Vault. Aby wyświetlić przykłady korzystające z jednego z innych podejść, zapoznaj się z bibliotekami klienta specyficznymi dla ekosystemu.

Zastąp <key-vault-url> wartości i <secret-name> odpowiednimi wartościami dla Key Vault i wpisu tajnego.

.NET

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);

C++

#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;
}

Przejdź

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)
   }
}

Java

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);
    }
}

Node.js

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);
});

Python

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()

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
Go	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.

Jak to działa

W tym modelu zabezpieczeń klaster usługi AKS działa jako wystawca tokenu. Microsoft Entra ID używa identyfikatora OIDC do odnajdywania publicznych kluczy podpisywania i weryfikowania autentyczności tokenu konta usługi przed wymianą go dla tokenu microsoft Entra. Obciążenie może wymienić token konta usługi przewidywany na jego wolumin dla tokenu entra firmy Microsoft przy użyciu biblioteki klienta tożsamości platformy Azure lub biblioteki MSAL.

W poniższej tabeli opisano wymagane punkty końcowe wystawcy OIDC dla Tożsamość obciążeń Microsoft Entra.

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 funkcji OIDC:

Automatyczna rotacja certyfikatu webhooka

Podobnie jak w przypadku innych dodatków webhooka operacja automatycznej rotacji certyfikatu klastra powoduje rotację certyfikatu webhooka tożsamości obciążenia.

Etykiety i adnotacje konta serwisowego

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, gdzie wiele kont usług odwołuje się do tego samego obiektu Microsoft Entra.
• Jeden do wielu, gdzie konto usługi odwołuje się do wielu obiektów Firmy Microsoft Entra, zmieniając adnotację 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 zaktualizujesz adnotacje konta serwisowego, musisz ponownie uruchomić pod, aby zmiany zaczęły obowiązywać.

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órych można użyć do skonfigurowania 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. 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	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.

Etykiety podów

Uwaga

W przypadku aplikacji wykorzystujących Tożsamość obciążeń Microsoft Entra należy dodać etykietę azure.workload.identity/use: "true" do specyfikacji zasobnika w AKS, aby przesunąć tożsamość obciążenia do scenariusza awaryjnego zamknięcia, co zapewni spójne i niezawodne działanie zasobników, które muszą korzystać z tożsamości obciążenia. W przeciwnym razie zasobniki 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	Aby uzyskać szczegółowe informacje, zobacz Adnotacje konta usługi . Adnotacje zasobników mają wyższy priorytet niż adnotacje kont usługi.	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 kontener boczny serwera proxy do podu. 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.	fałszywy
azure.workload.identity/proxy-sidecar-port	Reprezentuje port przyczepki serwera proxy.	8000

Używaj powiązań tożsamości i federacji bezpośredniej w ramach tego samego obciążenia roboczego

Powiązania tożsamości to funkcja w wersji zapoznawczej, która rozszerza tożsamość obciążenia, aby obsługiwała środowiska usługi AKS na dużą skalę. Zamiast tworzyć poświadczenia tożsamości federacyjnej (FIC) dla każdego klastra, powiązania tożsamości umożliwiają wielu klastrom współużytkowanie tożsamości zarządzanej przypisanej przez jednego użytkownika za pośrednictwem jednego FIC. Po włączeniu usługa AKS kieruje żądania tokenów podów przez serwer webhook pośredniczący dla powiązania tożsamości, który obsługuje wymianę tokenów w imieniu obciążenia roboczego.

Przewidywany token konta usługi ma jedną grupę odbiorców. Po włączeniu powiązań tożsamości element webhook powiązania tożsamości ustawia domyślny token, do którego odwołuje się AZURE_FEDERATED_TOKEN_FILE odbiorca api://AKSIdentityBinding, którego używa serwer proxy powiązania tożsamości.

Bezpośrednia federacja Tożsamość obciążeń Microsoft Entra (bez powiązań tożsamości) wymaga tokenu z odbiorcą api://AzureADTokenExchange. Ponowne użycie pliku tokenu powiązania tożsamości dla federacji bezpośredniej kończy się niepowodzeniem, AADSTS700212 ponieważ odbiorcy poświadczeń tożsamości federacyjnej nie są zgodni z odbiorcami tokenu.

Aby użyć powiązań tożsamości dla jednej tożsamości zarządzanej i federacji bezpośredniej dla innego w tym samym obciążeniu, projektuj drugi token konta usługi z odbiorcami api://AzureADTokenExchange i wskaż bezpośredni kod federacyjny w tym pliku:

apiVersion: v1
kind: Pod
metadata:
  name: workload-with-ib-and-direct-fic
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: workload-sa
  containers:
  - name: app
    image: <image>
    volumeMounts:
    - name: direct-fic-token
      mountPath: /var/run/secrets/direct-fic
      readOnly: true
    env:
    - name: DIRECT_FIC_TOKEN_FILE
      value: /var/run/secrets/direct-fic/token
  volumes:
  - name: direct-fic-token
    projected:
      sources:
      - serviceAccountToken:
          path: token
          audience: api://AzureADTokenExchange
          expirationSeconds: 3600

Użyj AZURE_FEDERATED_TOKEN_FILE dla przepływu powiązania tożsamości oraz niestandardowego pliku tokenu, takiego jak DIRECT_FIC_TOKEN_FILE, dla bezpośredniego przepływu federacyjnych poświadczeń tożsamości.

Migracja do Tożsamość obciążeń Microsoft Entra

Klastry już działające z tożsamością zarządzaną przez zasobnik można skonfigurować do używania identyfikatora obciążenia Microsoft Entra na jeden z dwóch sposobów:

• Użyj tej samej konfiguracji, która została zaimplementowana dla tożsamości zarządzanej przez pod. Możesz dodać adnotacje do konta usługi w przestrzeni nazw przy użyciu tożsamości, aby włączyć identyfikator obciążeń Microsoft Entra i wstrzyknąć adnotacje do podów.
• Zapisz ponownie aplikację, aby użyć najnowszej wersji biblioteki klienta tożsamości platformy Azure.

Aby usprawnić i ułatwić proces migracji, opracowaliśmy moduł pomocniczy migracji, który konwertuje transakcje usługi metadanych wystąpień (IMDS), jakie wykonuje Twoja aplikacja, na OIDC. Przyczepka migracji nie ma być długoterminowym rozwiązaniem, ale sposobem szybkiego rozpoczęcia pracy na identyfikatorze obciążenia firmy Microsoft Entra. 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.

Poniższa tabela zawiera podsumowanie naszych zaleceń dotyczących migracji lub wdrażania klastra usługi AKS:

Scenariusz	opis
Nowy klaster AKS Automatic	Tożsamość obciążenia i wystawca OIDC są wstępnie skonfigurowane. Nie są wymagane żadne kroki migracji ani konfiguracji na poziomie klastra. Skonfiguruj konto usługi aplikacji i poświadczenia federacyjne, a następnie użyj biblioteki klienta Azure Identity.
Nowy lub istniejący klaster usługi AKS w warstwie Standard, działający z obsługiwaną wersją biblioteki klienckiej Azure Identity	Nie są wymagane żadne kroki migracji. Przykładowe zasoby wdrażania: wdrażanie i konfigurowanie identyfikatora obciążenia entra firmy Microsoft 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 biblioteki klienta Azure Identity lub użyć przyczepki migracji.

Treści powiązane

• Aby dowiedzieć się, jak skonfigurować pod do uwierzytelniania przy użyciu tożsamości zadania jako opcji migracji, zobacz Modernizowanie uwierzytelniania aplikacji przy użyciu identyfikatora obciążenia Microsoft Entra.
• Zobacz Deploy and configure an AKS cluster with Tożsamość obciążeń Microsoft Entra (Wdrażanie i konfigurowanie klastra AKS przy użyciu identyfikatora obciążenia firmy Microsoft Entra), który pomaga wdrożyć klaster i skonfigurować przykładową aplikację do korzystania z tożsamości obciążenia.
• Aby dowiedzieć się więcej o wstępnie skonfigurowanych domyślnych ustawieniach zabezpieczeń usługi AKS Automatic, w tym o tożsamości obciążenia, zobacz Co to jest usługa Azure Kubernetes Service Automatic?