Dokumentacja konfiguracji: Zestaw Microsoft Entra SDK dla ustawień identyfikatora agenta

Ten przewodnik zawiera opcje konfiguracji zestawu Microsoft Entra SDK dla agentID, konteneryzowanej usługi uwierzytelniania, która obsługuje pozyskiwanie tokenów i zarządzanie aplikacjami w środowiskach konteneryzowanych. Zestaw SDK upraszcza integrację tożsamości, zarządzając uwierzytelnianiem identyfikatora Entra firmy Microsoft, przepływami tokenów on-behalf-of (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 usłudze Azure Kubernetes Service (AKS), konfigurujesz środowiska deweloperskie lub konfigurujesz obciążenia produkcyjne, ta dokumentacja obejmuje wzorce konfiguracji, typy poświadczeń i zmienne środowiskowe potrzebne do zabezpieczenia aplikacji za pomocą identyfikatora Entra firmy Microsoft.

Omówienie konfiguracji

Zestaw Microsoft Entra SDK for AgentID jest skonfigurowany 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)
• Konfiguracja identyfikatora entra — appsettings.json plik dołączony do kontenera lub osadzony w pliku yaml.
• Argumenty wiersza polecenia
• Usługa Azure App Configuration lub Key Vault (w przypadku zaawansowanych scenariuszy)

Ustawienia podstawowego identyfikatora entra

Zestaw Microsoft Entra SDK dla wdrożeń identyfikatora AgentID wymaga podstawowych ustawień identyfikatora Entra 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 identyfikatora entra dla 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 SDK for AgentID obsługuje wiele typów poświadczeń klienta na potrzeby uwierzytelniania za pomocą identyfikatora Entra firmy Microsoft 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 usługi 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)
• Magazyn certyfikatów: środowiska systemu Windows z magazynami certyfikatów
• Tożsamość obciążenia dla kontenerów: zalecane w przypadku usługi AKS przy użyciu tożsamości obciążenia usługi Azure AD z projekcją tokenu opartą na plikach
• Tożsamość zarządzana dla maszyn wirtualnych/usług 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:

Tajemnica klienta

Ta konfiguracja konfiguruje uwierzytelnianie entra ID 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 usługi Key Vault

Ta konfiguracja konfiguruje uwierzytelnianie entra ID przy użyciu certyfikatu przechowywanego w usłudze 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 uwierzytelnianie entra ID 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 uwierzytelnianie entra ID 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 dla kontenerów (zalecana dla usługi AKS)

Ta konfiguracja konfiguruje uwierzytelnianie identyfikatora entra przy użyciu tożsamości obciążenia usługi Azure AD dla wdrożeń konteneryzowanych (AKS). Jest to zalecane podejście do scenariuszy opartych na kontenerach, ponieważ używa projekcji tokenu opartego na plikach.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Uwaga: ścieżka /var/run/secrets/azure/tokens/azure-identity-token pliku tokenu lub zmienna środowiskowa jest automatycznie projektowana przez element webhook tożsamości obciążenia platformy Azure, 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ść zarządzana dla maszyn wirtualnych i usług App Services

W przypadku klasycznych scenariuszy tożsamości zarządzanej platformy Azure na maszynach wirtualnych lub w usługach App Services (nie kontenerach) użyj polecenia 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 konteneryzowanych (Kubernetes, AKS, Docker). W przypadku usługi AKS użyj polecenia SignedAssertionFilePath , jak pokazano powyżej. W przypadku platform Kubernetes i Docker użyj certyfikatów klienta. 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 SDK for AgentID ocenia poświadczenia w kolejności liczbowej (0, 1, 2 itp.) i używa pierwszego poświadczenia, które pomyślnie się uwierzytelniają.

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 SDK for AgentID 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)

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 identyfikatora Entra, 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 SDK dla identyfikatora AgentID 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

Najlepsze rozwiązania

1. Użyj wpisów tajnych dla poświadczeń: przechowywanie wpisów tajnych klienta i certyfikatów w wpisach tajnych platformy Kubernetes lub w usłudze 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żywanie tożsamości obciążenia dla kontenerów: w przypadku wdrożeń konteneryzowanych (AKS) preferuj tożsamość obciążenia usługi Azure AD z SignedAssertionFilePath użyciem 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 platformy Azure i usług App Services użyj tożsamości zarządzanych przypisanych przez system lub użytkownika
7. Weryfikowanie w czasie wdrażania: Testowanie konfiguracji w środowisku przejściowym przed wdrożeniem produkcyjnym

Zobacz też

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