Dokumentacja konfiguracji: ustawienia zestawu SDK uwierzytelniania Microsoft Entra ID (przyczepki)

Ten przewodnik zawiera opcje konfiguracji dla zestawu SDK uwierzytelniania Microsoft Entra ID (przyczepki), konteneryzowanej usługi uwierzytelniania obsługującej pozyskiwanie tokenów i zarządzanie aplikacjami w środowiskach konteneryzowanych. Zestaw SDK upraszcza integrację tożsamości, zarządzając Microsoft Entra ID uwierzytelnianiem, przepływami tokenów w imieniu (OBO) i wywołaniami interfejsu API podrzędnego bez konieczności bezpośredniego osadzania bibliotek uwierzytelniania przez aplikacje.

Chociaż ten przewodnik koncentruje się na wzorcach wdrażania platformy Kubernetes, zestaw SDK można wdrożyć w dowolnym konteneryzowanym środowisku, w tym docker, Azure Container Instances i innych platformach aranżacji kontenerów.

Jeśli wdrażasz w Azure Kubernetes Service (AKS), konfigurowaniu środowisk deweloperskich lub konfigurowaniu obciążeń produkcyjnych, ta dokumentacja obejmuje wzorce konfiguracji, typy poświadczeń i zmienne środowiskowe potrzebne do zabezpieczenia aplikacji przy użyciu Microsoft Entra ID.

Omówienie konfiguracji

Zestaw SDK uwierzytelniania Microsoft Entra ID (przyczepka) jest konfigurowany przy użyciu źródeł konfiguracji zgodnie z konwencjami ASP.NET Core. Wartości konfiguracji można podać za pomocą wielu metod, w tym:

• Zmienne środowiskowe (zalecane dla platformy Kubernetes)
• Entra ID konfiguracji — plik appsettings.json dołączony do kontenera lub osadzony w pliku yaml.
• Argumenty wiersza polecenia
• Azure App Configuration lub Key Vault (w przypadku scenariuszy zaawansowanych)

Podstawowe ustawienia Entra ID

Microsoft Entra ID wdrożenia zestawu SDK uwierzytelniania (przyczepki) wymagają podstawowych ustawień Entra ID w celu uwierzytelniania tokenów przychodzących i uzyskiwania tokenów dla podrzędnych interfejsów API. Użyj odpowiednich poświadczeń klienta w następującym formacie YAML, zazwyczaj jako zmienne środowiskowe, aby zapewnić bezpieczne uwierzytelnianie.

Wymagana konfiguracja

Najpierw skonfiguruj podstawowe ustawienia Entra ID zestawu SDK w celu uwierzytelniania tokenów przychodzących i uzyskiwania tokenów dla podrzędnych interfejsów API.

env:
- name: AzureAd__Instance
  value: "https://login.microsoftonline.com/"
- name: AzureAd__TenantId
  value: "<your-tenant-id>"
- name: AzureAd__ClientId
  value: "<your-client-id>"

Konfiguracja poświadczeń klienta

Zestaw MICROSOFT ENTRA ID Auth SDK (przyczepka) obsługuje wiele typów poświadczeń klienta do uwierzytelniania przy użyciu Microsoft Entra ID podczas uzyskiwania tokenów dla podrzędnych interfejsów API. Wybierz typ poświadczeń, który najlepiej pasuje do wymagań dotyczących środowiska wdrażania i zabezpieczeń, i upewnij się, że wybrana konfiguracja jest odpowiednia dla danego scenariusza.

Każdy typ poświadczeń obsługuje różne scenariusze:

• Klucz tajny klienta: prosta konfiguracja programowania i testowania (nie jest zalecana w środowisku produkcyjnym)
• certyfikat Key Vault: środowiska produkcyjne ze scentralizowanym zarządzaniem certyfikatami
• Certyfikat pliku: gdy certyfikaty są instalowane jako pliki (np. za pośrednictwem wpisów tajnych platformy Kubernetes)
• Certificate Store: Windows środowiska z magazynami certyfikatów
• Workload Identity for Containers: Zalecane w przypadku usługi AKS przy użyciu Tożsamość obciążeń Microsoft Entra z projekcją tokenu opartego na plikach
• Managed Identity for VMs/App Services: Azure Virtual Machines i App Services z tożsamościami zarządzanymi przypisanymi przez użytkownika (nie dla kontenerów)

Skonfiguruj co najmniej jedno źródło poświadczeń w następującym formacie YAML:

Wybieranie poświadczeń według środowiska

Wybierz poświadczenie w zależności od tego, gdzie działa przyczepka. Zarówno SignedAssertionFilePath , jak i SignedAssertionFromManagedIdentity są poświadczeniami tożsamości federacyjnej (FIC). Różnią się one sposobem uzyskania podpisanej asercji przez przyczepkę.

Ważne: SignedAssertionFromManagedIdentity nie jest poświadczenie kubernetes ogólnego przeznaczenia i nie jest rezerwą dla usługi SignedAssertionFilePath. Używa Azure tożsamości zarządzanej i sond Azure środowiska hostingu, takich jak service Fabric, App Service i IMDS. Na hoście innym niż Azure znajduje się żaden z nich, a żądanie ostatecznie zostanie upłynął limit czasu względem usługi IMDS. Jeśli przyczepka nieoczekiwanie osiągnie identyfikatorY IMDS, wybrano ten typ źródła. Użyj SignedAssertionFilePath zamiast tego.

Tajemnica klienta

Ta konfiguracja konfiguruje Entra ID uwierzytelniania przy użyciu klucza tajnego klienta na potrzeby uwierzytelniania typu service-to-service.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__0__ClientSecret
  value: "<your-client-secret>"

Certyfikat z Key Vault

Ta konfiguracja konfiguruje Entra ID uwierzytelniania przy użyciu certyfikatu przechowywanego w Azure Key Vault.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://<your-keyvault>.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "<certificate-name>"

Certyfikat z pliku

Ta konfiguracja konfiguruje Entra ID uwierzytelniania przy użyciu certyfikatu przechowywanego jako plik.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "Path"
- name: AzureAd__ClientCredentials__0__CertificateDiskPath
  value: "/path/to/certificate.pfx"
- name: AzureAd__ClientCredentials__0__CertificatePassword
  value: "<certificate-password>"

Certyfikat z magazynu

Ta konfiguracja konfiguruje Entra ID uwierzytelniania przy użyciu certyfikatu z lokalnego magazynu certyfikatów.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "StoreWithThumbprint"
- name: AzureAd__ClientCredentials__0__CertificateStorePath
  value: "CurrentUser/My"
- name: AzureAd__ClientCredentials__0__CertificateThumbprint
  value: "<thumbprint>"

Tożsamość obciążenia w usłudze AKS (zalecana dla usługi AKS)

Ta konfiguracja konfiguruje uwierzytelnianie Entra ID przy użyciu Tożsamość obciążeń Microsoft Entra w usłudze AKS. Jest to zalecane podejście w usłudze AKS, ponieważ projekty elementu webhook tożsamości obciążenia Azure i obracają token.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Uwaga: w usłudze AKS ścieżka /var/run/secrets/azure/tokens/azure-identity-token pliku tokenu lub zmienna środowiskowa jest automatycznie projektowana przez element webhook Azure Workload Identity, gdy zasobnik jest prawidłowo skonfigurowany z adnotacją konta usługi i etykietą zasobnika. Aby uzyskać pełne instrukcje dotyczące konfiguracji, zobacz Używanie tożsamości zarządzanej .

Tożsamość obciążenia dla platformy Kubernetes innej niż Azure lub lokalna

Przepływ tożsamości agenta nie jest ograniczony do usługi AKS. Każda platforma Kubernetes, w tym lokalna i inna chmura, może używać z SignedAssertionFilePath federacją tożsamości obciążeń. Ponieważ nie ma elementu webhook tożsamości obciążenia Azure poza usługą AKS, wskazujesz przyczepkę na przewidywany token konta usługi zainstalowany przez platformę.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"
- name: AzureAd__ClientCredentials__0__SignedAssertionFileDiskPath
  value: "/var/run/secrets/tokens/sa-token"

Przyczepka ponownie odczytuje plik w każdym żądaniu tokenu, więc sterowana platformą rotacja przewidywanej asercji jest obsługiwana automatycznie.

Aby użyć tego poświadczenia na platformie Kubernetes spoza Azure, środowisko musi spełniać następujące wymagania wstępne:

• Platforma Kubernetes projektuje token konta usługi do zasobnika przyczepki, na przykład za pośrednictwem przewidywanego serviceAccountToken woluminu.
• Klaster uwidacznia publicznie dostępny wystawcę OIDC i punkt końcowy JWKS, aby Microsoft Entra mógł zweryfikować potwierdzenie.
• Poświadczenie tożsamości federacyjnej (FIC) jest konfigurowane w aplikacji strategii z wystawcą i podmiotem zgodnym z przewidywanym tokenem.

Jeśli platforma nie może podać przewidywanego tokenu OIDC lub publicznego wystawcy, użyj poświadczeń certyfikatu, takich jak certyfikat z Key Vault lub certyfikatu z pliku.

Tożsamość zarządzana dla maszyn wirtualnych i usług App Services

W przypadku klasycznych scenariuszy tożsamości zarządzanej Azure w usługach Virtual Machines lub App Services (nie kontenerach) użyj SignedAssertionFromManagedIdentity:

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFromManagedIdentity"
- name: AzureAd__ClientCredentials__0__ManagedIdentityClientId
  value: "<managed-identity-client-id>"

Ważne: nie należy używać SignedAssertionFromManagedIdentity w środowiskach innych niż Azure ani w środowiskach lokalnych. Używa ona Azure tożsamości zarządzanej za pośrednictwem usług IMDS i działa tylko w przypadku Azure zasobów obliczeniowych zapewniających tożsamość zarządzaną. Na hoście innym niż Azure sonduje Azure hostowanie punktów końcowych, a następnie limit czasu względem usługi IMDS, który może wyglądać tak, jakby zestaw SDK był zakodowany na stałe w usłudze IMDS. W przypadku rozwiązania Kubernetes w dowolnym miejscu, w tym usługi AKS, użyj polecenia SignedAssertionFilePath. Aby uzyskać szczegółowe informacje, zobacz https://aka.ms/idweb/client-credentials

Dodatkowe zasoby

Aby uzyskać szczegółowe informacje na temat wszystkich opcji konfiguracji poświadczeń i ich użycia, zobacz specyfikację CredentialDescription w repozytorium microsoft-identity-abstractions-for-dotnet.

Priorytet poświadczeń

Skonfiguruj wiele poświadczeń z wyborem opartym na priorytcie:

# First priority - Key Vault certificate
- name: AzureAd__ClientCredentials__0__SourceType
  value: "KeyVault"
- name: AzureAd__ClientCredentials__0__KeyVaultUrl
  value: "https://prod-keyvault.vault.azure.net"
- name: AzureAd__ClientCredentials__0__KeyVaultCertificateName
  value: "prod-cert"

# Second priority - Client secret (fallback)
- name: AzureAd__ClientCredentials__1__SourceType
  value: "ClientSecret"
- name: AzureAd__ClientCredentials__1__ClientSecret
  valueFrom:
    secretKeyRef:
      name: app-secrets
      key: client-secret

Zestaw MICROSOFT ENTRA ID Auth SDK (przyczepka) ocenia poświadczenia w kolejności liczbowej (0, 1, 2 itp.) i używa pierwszego poświadczenia, które pomyślnie się uwierzytelnia.

Konfiguracja podrzędnych interfejsów API

Skonfiguruj podrzędne interfejsy API, które aplikacja musi wywoływać przy użyciu przepływów tokenów on-behalf-of (OBO). Zestaw MICROSOFT ENTRA ID Auth SDK (przyczepka) zarządza pozyskiwaniem tokenów i udostępnia nagłówki uwierzytelniania dla tych wywołań interfejsu API. Każdy podrzędny interfejs API wymaga unikatowej nazwy konfiguracji i określonych parametrów na potrzeby uzyskiwania tokenu i obsługi żądań HTTP.

Zdefiniuj każdy podrzędny interfejs API przy użyciu podstawowego adresu URL, wymaganych zakresów i parametrów opcjonalnych. Zestaw SDK automatycznie obsługuje pozyskiwanie tokenów przy użyciu tokenu przychodzącego użytkownika i udostępnia odpowiednie nagłówki autoryzacji dla wywołań interfejsu API aplikacji.

- name: DownstreamApis__Graph__BaseUrl
  value: "https://graph.microsoft.com/v1.0"
- name: DownstreamApis__Graph__Scopes
  value: "User.Read Mail.Read"
- name: DownstreamApis__Graph__RelativePath
  value: "/me"

- name: DownstreamApis__MyApi__BaseUrl
  value: "https://api.contoso.com"
- name: DownstreamApis__MyApi__Scopes
  value: "api://myapi/.default"

Opcje pozyskiwania tokenów

Dostrajanie zachowania pozyskiwania tokenów:

- name: DownstreamApis__Graph__AcquireTokenOptions__Tenant
  value: "<specific-tenant-id>"

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

- name: DownstreamApis__Graph__AcquireTokenOptions__CorrelationId
  value: "<correlation-id>"

Konfiguracja podpisanego żądania HTTP (SHR) na potrzeby pozyskiwania tokenu wychodzącego

Włącz podpisane żądania HTTP dla zwiększonych zabezpieczeń:

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopPublicKey
  value: "<base64-encoded-public-key>"

- name: DownstreamApis__SecureApi__AcquireTokenOptions__PopClaims
  value: '{"custom_claim": "value"}'

Konfiguracja rejestrowania

Konfigurowanie poziomów rejestrowania:

- name: Logging__LogLevel__Default
  value: "Information"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Debug"
- name: Logging__LogLevel__Microsoft.AspNetCore
  value: "Warning"

ustawienia ASP.NET Core

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: ASPNETCORE_URLS
  value: "http://+:5000"

Per-Request przesłonięcia konfiguracji

Wszystkie punkty końcowe pozyskiwania tokenu akceptują parametry zapytania w celu zastąpienia konfiguracji:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read&optionsOverride.Scopes=Mail.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

GET /AuthorizationHeaderUnauthenticated/Graph?optionsOverride.RequestAppToken=true

# Override tenant
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.Tenant=<tenant-id>

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

# Enable SHR for this request
GET /AuthorizationHeader/Graph?optionsOverride.AcquireTokenOptions.PopPublicKey=<base64-key>

Przesłonięcia tożsamości agenta

Określ tożsamość agenta w momencie żądania:

# Autonomous agent
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

# Autonomous agent with specific agent user identity (by username)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

# Autonomous agent with specific agent user identity (by object ID)
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUserId=<user-object-id>

Ważne reguły:

• AgentUsername i AgentUserId wymagaj AgentIdentity
• AgentUsername i AgentUserId wzajemnie się wykluczają

Zobacz Tożsamości agentów , aby uzyskać szczegółowe informacje na temat semantyki.

Kompletny przykład konfiguracji

Poniżej przedstawiono przykład gotowy do produkcji pokazujący sposób wdrażania zestawu SDK z odpowiednim rozdzieleniem konfiguracji i wpisów tajnych. W tym przykładzie pokazano konfigurowanie wielu podrzędnych interfejsów API przy użyciu interfejsów ConfigMap platformy Kubernetes dla ustawień niewrażliwych, bezpiecznego przechowywania poświadczeń w wpisach tajnych i stosowania konfiguracji specyficznych dla środowiska w celu bezpiecznego wdrożenia.

Ten wzorzec jest zgodny z najlepszymi rozwiązaniami platformy Kubernetes, oddzielając dane konfiguracji od poufnych poświadczeń, umożliwiając efektywne zarządzanie różnymi środowiskami przy zachowaniu zabezpieczeń.

Kubernetes ConfigMap

Narzędzie ConfigMap przechowuje niewrażliwe ustawienia konfiguracji zestawu SDK, w tym ustawienia Entra ID, podrzędne interfejsy API i poziomy rejestrowania.

apiVersion: v1
kind: ConfigMap
metadata:
  name: sidecar-config
data:
  ASPNETCORE_ENVIRONMENT: "Production"
  ASPNETCORE_URLS: "http://+:5000"
  
  AzureAd__Instance: "https://login.microsoftonline.com/"
  AzureAd__TenantId: "common"
  AzureAd__ClientId: "your-app-client-id"
  AzureAd__Scopes: "access_as_user"
  
  DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
  DownstreamApis__Graph__Scopes: "User.Read Mail.Read"
  
  DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
  DownstreamApis__MyApi__Scopes: "api://myapi/.default"
  
  Logging__LogLevel__Default: "Information"
  Logging__LogLevel__Microsoft.Identity.Web: "Debug"

Wpis tajny platformy Kubernetes

Wpis tajny przechowuje poufne poświadczenia, takie jak wpisy tajne klienta, niezależnie od obiektu ConfigMap.

apiVersion: v1
kind: Secret
metadata:
  name: sidecar-secrets
type: Opaque
stringData:
  AzureAd__ClientCredentials__0__ClientSecret: "your-client-secret"

Wdrażanie za pomocą narzędzia ConfigMap i wpisu tajnego

Wdrożenie instaluje zarówno ConfigMap, jak i Secret w kontenerze zestawu SDK, zapewniając prawidłowe oddzielenie konfiguracji i poświadczeń.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: sidecar
        image: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0
        envFrom:
        - configMapRef:
            name: sidecar-config
        - secretRef:
            name: sidecar-secrets

Konfiguracja specyficzna dla środowiska

Skonfiguruj ustawienia specyficzne dla środowiska, aby dostosować zabezpieczenia, rejestrowanie i izolację dzierżawy dla środowisk wdrażania. Każde środowisko wymaga różnych metod konfiguracji w celu zrównoważenia wydajności programowania, przejściowej weryfikacji i wymagań dotyczących zabezpieczeń produkcyjnych.

Rozwój

- name: ASPNETCORE_ENVIRONMENT
  value: "Development"
- name: Logging__LogLevel__Default
  value: "Debug"
- name: AzureAd__TenantId
  value: "<dev-tenant-id>"

Staging

- name: ASPNETCORE_ENVIRONMENT
  value: "Staging"
- name: Logging__LogLevel__Default
  value: "Information"
- name: AzureAd__TenantId
  value: "<staging-tenant-id>"

Produkcja

- name: ASPNETCORE_ENVIRONMENT
  value: "Production"
- name: Logging__LogLevel__Default
  value: "Warning"
- name: Logging__LogLevel__Microsoft.Identity.Web
  value: "Information"
- name: AzureAd__TenantId
  value: "<prod-tenant-id>"
- name: ApplicationInsights__ConnectionString
  value: "<app-insights-connection>"

Validation

Zestaw MICROSOFT ENTRA ID Auth SDK (sidecar) weryfikuje konfigurację podczas uruchamiania i rejestruje błędy dla:

• Brak wymaganych ustawień (TenantId, ClientId)
• Nieprawidłowe konfiguracje poświadczeń
• Źle sformułowane definicje podrzędnego interfejsu API
• Nieprawidłowe adresy URL lub formaty zakresu

Sprawdź dzienniki kontenera pod kątem komunikatów sprawdzania poprawności:

kubectl logs <pod-name> -c sidecar

Rozwiązywanie problemów z poświadczeniami

Nieoczekiwane dotarcie żądań do imDS lub przekroczenie limitu czasu

Objaw: przyczepka zawiesza się lub przekracza limit czasu uzyskiwania tokenu podrzędnego, a dzienniki pokazują żądania do punktu końcowego IMDS (169.254.169.254), nawet na hoście innym niż Azure.

Przyczyna: Poświadczenie jest skonfigurowane jako SignedAssertionFromManagedIdentity. Ten typ źródłowy celowo sonduje Azure środowiska hostingu i usług IMDS, które nie istnieją poza Azure. Jest to wybór konfiguracji, a nie powrót z klasy SignedAssertionFilePath.

Rozwiązanie:

1. Upewnij się, że wartość obowiązująca SourceType to SignedAssertionFilePath, a nie SignedAssertionFromManagedIdentity.
2. Sprawdź, czy żadna zmienna środowiskowa ani ConfigMap nie zastępują ponownie funkcji SignedAssertionFromManagedIdentity.
3. Sprawdź, czy SignedAssertionFileDiskPath wskazuje przewidywany token zainstalowany w kontenerze przyczepki.
4. Na platformie Kubernetes bez Azure upewnij się, że wystawca OIDC klastra i zestaw JWKS są publicznie dostępne i że w aplikacji Blueprint istnieje pasujący kod FIC.

W przypadku zgłaszania trwałego problemu przechwyć wersję przyczepki, efektywną konfigurację środowiska uruchomieniowego i dzienniki kontenera z jednego żądania zakończonego niepowodzeniem.

Najlepsze rozwiązania

1. Użyj wpisy tajne dla poświadczeń: Przechowywanie wpisów tajnych i certyfikatów klienta w wpisach tajnych platformy Kubernetes lub Azure Key Vault. Zobacz też https://aka.ms/msidweb/client-credentials
2. Oddzielna konfiguracja na środowisko: użyj obiektów ConfigMap do zarządzania ustawieniami specyficznymi dla środowiska
3. Włącz odpowiednie rejestrowanie: użyj rejestrowania debugowania w programowania, informacje/ostrzeżenie w środowisku produkcyjnym
4. Konfigurowanie kontroli kondycji: upewnij się, że punkty końcowe sprawdzania kondycji są prawidłowo skonfigurowane
5. Użyj tożsamości obciążenia dla kontenerów: w przypadku wdrożeń konteneryzowanych (AKS) preferuj Tożsamość obciążeń Microsoft Entra z SignedAssertionFilePath za pośrednictwem wpisów tajnych klienta w celu zwiększenia bezpieczeństwa
6. Użyj tożsamości zarządzanej dla maszyn wirtualnych/usług App Services: w przypadku maszyn wirtualnych Azure i usług App Services użyj tożsamości zarządzanych przypisanych przez użytkownika lub systemu
7. Weryfikowanie w czasie wdrażania: Testowanie konfiguracji w środowisku przejściowym przed wdrożeniem produkcyjnym

Treści powiązane

• Tożsamości agenta
• Dokumentacja punktów końcowych
• Najlepsze rozwiązania w zakresie zabezpieczeń
• Troubleshooting