Konfigurationsreferenz: Microsoft Entra SDK für AgentID-Einstellungen

Dieses Handbuch enthält Konfigurationsoptionen für das Microsoft Entra SDK für AgentID, einen containerisierten Authentifizierungsdienst, der die Tokenerfassung und -verwaltung für Anwendungen in containerisierten Umgebungen verarbeitet. Das SDK vereinfacht die Identitätsintegration durch die Verwaltung der Microsoft Entra ID-Authentifizierung, im Auftrag von (OBO)-Tokenflüssen und nachgeschalteten API-Aufrufen, ohne dass Anwendungen Authentifizierungsbibliotheken direkt einbetten müssen.

Während sich dieses Handbuch auf Kubernetes-Bereitstellungsmuster konzentriert, kann das SDK in jeder containerisierten Umgebung bereitgestellt werden, einschließlich Docker, Azure-Containerinstanzen und anderen Container-Orchestrierungsplattformen.

Wenn Sie in Azure Kubernetes Service (AKS) bereitstellen, Entwicklungsumgebungen einrichten oder Produktionsworkloads konfigurieren, umfasst diese Referenz Konfigurationsmuster, Anmeldeinformationstypen und Umgebungsvariablen, die zum Sichern Ihrer Anwendungen mit Microsoft Entra ID erforderlich sind.

Übersicht über die Konfiguration

Das Microsoft Entra SDK für AgentID wird mithilfe von Konfigurationsquellen konfiguriert, die ASP.NET Core-Konventionen folgen. Konfigurationswerte können über mehrere Methoden bereitgestellt werden, darunter:

• Umgebungsvariablen (empfohlen für Kubernetes)
• Entra-ID-Konfiguration – appsettings.json Datei, die an den Container angefügt oder in die Yaml-Datei eingebettet ist.
• Befehlszeilenargumente
• Azure App-Konfiguration oder Key Vault (für erweiterte Szenarien)

Core Entra ID-Einstellungen

Microsoft Entra SDK für AgentID-Bereitstellungen erfordert grundlegende Entra-ID-Einstellungen, um eingehende Token zu authentifizieren und Token für downstream-APIs zu erwerben. Verwenden Sie die entsprechenden Clientanmeldeinformationen im folgenden YAML-Format, in der Regel als Umgebungsvariablen, um die sichere Authentifizierung sicherzustellen.

Erforderliche Konfiguration

Konfigurieren Sie zunächst die wichtigsten Entra-ID-Einstellungen für das SDK, um eingehende Token zu authentifizieren und Token für downstream-APIs zu erwerben.

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

Konfiguration von Clientanmeldeinformationen

Das Microsoft Entra SDK für AgentID unterstützt mehrere Clientanmeldeinformationstypen für die Authentifizierung mit Microsoft Entra ID beim Abrufen von Token für downstream-APIs. Wählen Sie den Anmeldeinformationstyp aus, der ihrer Bereitstellungsumgebung und den Sicherheitsanforderungen am besten entspricht, und stellen Sie sicher, dass die ausgewählte Konfiguration für Ihr Szenario geeignet ist.

Jeder Anmeldeinformationstyp dient verschiedenen Szenarien:

• Geheimer Clientschlüssel: Einfaches Setup für Entwicklung und Tests (nicht für die Produktion empfohlen)
• Key Vault-Zertifikat: Produktionsumgebungen mit zentraler Zertifikatverwaltung
• Dateizertifikat: Wenn Zertifikate als Dateien bereitgestellt werden (z. B. über Kubernetes geheime Schlüssel)
• Zertifikatspeicher: Windows-Umgebungen mit Zertifikatspeichern
• Workload Identity for Containers: Recommended for AKS, using Azure AD Workload Identity with file-based token projection
• Managed Identity for VMs/App Services: Azure Virtual Machines and App Services with system or user-assigned managed identity (not for containers)

Konfigurieren Sie eine oder mehrere Anmeldeinformationsquellen im folgenden YAML-Format:

Geheimer Clientschlüssel

Diese Konfiguration richtet die Entra-ID-Authentifizierung mithilfe eines geheimen Clientschlüssels für die Dienst-zu-Dienst-Authentifizierung ein.

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

Zertifikat aus Key Vault

Diese Konfiguration richtet die Entra-ID-Authentifizierung mithilfe eines zertifikats ein, das in Azure Key Vault gespeichert ist.

- 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>"

Zertifikat aus Datei

Diese Konfiguration richtet die Entra-ID-Authentifizierung mithilfe eines Zertifikats ein, das als Datei gespeichert ist.

- 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>"

Zertifikat aus Speicher

Diese Konfiguration richtet die Entra-ID-Authentifizierung mithilfe eines Zertifikats aus dem lokalen Zertifikatspeicher ein.

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

Workload Identity for containers (recommended for AKS)

Diese Konfiguration richtet die Entra-ID-Authentifizierung mithilfe der Azure AD Workload Identity für containerisierte Bereitstellungen (AKS) ein. Dies ist der empfohlene Ansatz für containerbasierte Szenarien, da sie dateibasierte Tokenprojektion verwendet.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Hinweis: Der Tokendateipfad /var/run/secrets/azure/tokens/azure-identity-token oder eine Umgebungsvariable wird automatisch vom Azure Workload Identity-Webhook projiziert, wenn Ihr Pod ordnungsgemäß mit der Dienstkontoanmerkung und der Podbezeichnung konfiguriert ist. Vollständige Einrichtungsanweisungen finden Sie unter Verwenden der verwalteten Identität .

Verwaltete Identität für VMs und App-Dienste

Verwenden Sie SignedAssertionFromManagedIdentityfür klassische Azure Managed Identity-Szenarien auf virtuellen Computern oder App Services (keine Container) Folgendes:

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

Wichtig: Verwenden SignedAssertionFromManagedIdentity Sie nicht für containerisierte Umgebungen (Kubernetes, AKS, Docker). Verwenden Sie SignedAssertionFilePath für AKS wie oben dargestellt. Verwenden Sie für Kubernetes und Docker Clientzertifikate. Weitere Informationen finden Sie unter https://aka.ms/idweb/client-credentials

Zusätzliche Ressourcen

Ausführliche Informationen zu allen Konfigurationsoptionen für Anmeldeinformationen und deren Verwendung finden Sie in der Spezifikation "CredentialDescription " im Repository "microsoft-identity-abstractions-for-dotnet".

Priorität der Anmeldeinformationen

Konfigurieren mehrerer Anmeldeinformationen mit prioritätsbasierter Auswahl:

# 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

Das Microsoft Entra SDK für AgentID wertet Anmeldeinformationen in numerischer Reihenfolge (0, 1, 2 usw.) aus und verwendet die ersten Anmeldeinformationen, die sich erfolgreich authentifizieren.

Konfiguration nachgeschalteter APIs

Konfigurieren Sie downstream-APIs, die Ihre Anwendung mithilfe von OBO-Tokenflüssen aufrufen muss. Das Microsoft Entra SDK für AgentID verwaltet die Tokenerfassung und stellt Authentifizierungsheader für diese API-Aufrufe bereit. Jede downstream-API erfordert einen eindeutigen Konfigurationsnamen und spezifische Parameter für die Tokenerfassung und die HTTP-Anforderungsverarbeitung.

Definieren Sie jede downstream-API mit ihrer Basis-URL, erforderlichen Bereichen und optionalen Parametern. Das SDK verarbeitet automatisch den Tokenerwerb mithilfe des eingehenden Benutzertokens und stellt die entsprechenden Autorisierungsheader für die API-Aufrufe Ihrer Anwendung bereit.

- 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"

Tokenakquisitionsoptionen

Optimieren des Tokenakquisitionsverhaltens:

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

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

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

Konfiguration der signierten HTTP-Anforderung (SHR)

Signierte HTTP-Anforderungen für erhöhte Sicherheit aktivieren:

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

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

Protokollierungskonfiguration

Protokollierungsebenen konfigurieren:

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

ASP.NET Core-Einstellungen

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

Per-Request-Konfigurationsüberschreibungen

Alle Tokenerfassungsendpunkte akzeptieren Abfrageparameter, um die Konfiguration außer Kraft zu setzen:

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

Außerkraftsetzungen der Agentidentität

Angeben der Agentidentität zur Anforderungszeit:

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

Wichtige Regeln:

• AgentUsername und AgentUserId erfordern AgentIdentity
• AgentUsername und AgentUserId schließen sich gegenseitig aus

Ausführliche Semantik finden Sie unter Agentidentitäten .

Vollständiges Konfigurationsbeispiel

Im Folgenden finden Sie ein produktionsbereites Beispiel, das zeigt, wie das SDK mit der richtigen Trennung von Konfiguration und geheimen Schlüsseln bereitgestellt wird. In diesem Beispiel wird das Konfigurieren mehrerer downstreamer APIs veranschaulicht, die Kubernetes ConfigMaps für nicht vertrauliche Einstellungen verwenden, Anmeldeinformationen sicher in geheimen Schlüsseln speichern und umgebungsspezifische Konfigurationen für die sichere Bereitstellung anwenden.

Dieses Muster folgt kubernetes bewährten Methoden, indem Konfigurationsdaten von vertraulichen Anmeldeinformationen getrennt werden, wodurch eine effektive Verwaltung verschiedener Umgebungen und gleichzeitig die Sicherheit ermöglicht wird.

Kubernetes ConfigMap

Die ConfigMap speichert nicht vertrauliche Konfigurationseinstellungen für das SDK, einschließlich Entra-ID-Einstellungen, downstream-APIs und Protokollierungsebenen.

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"

Kubernetes Geheimnis

Der geheime Schlüssel speichert vertrauliche Anmeldeinformationen, z. B. geheime Clientschlüssel, getrennt von der ConfigMap.

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

Bereitstellung mit ConfigMap und geheimen Schlüsseln

Die Bereitstellung stellt sowohl die ConfigMap als auch den geheimen Schlüssel im SDK-Container bereit, um sicherzustellen, dass Konfiguration und Anmeldeinformationen ordnungsgemäß getrennt sind.

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

Umgebungsspezifische Konfiguration

Konfigurieren Sie umgebungsspezifische Einstellungen, um Die Sicherheit, Protokollierung und Mandantenisolation für Ihre Bereitstellungsumgebungen anzupassen. Jede Umgebung erfordert unterschiedliche Konfigurationsansätze, um entwicklungseffizienz, Stagingüberprüfung und Produktionssicherheitsanforderungen auszugleichen.

Entwicklung

- 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>"

Produktion

- 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

Das Microsoft Entra SDK für AgentID überprüft die Konfiguration beim Start und protokolliert Fehler für:

• Fehlende erforderliche Einstellungen (TenantId, ClientId)
• Ungültige Konfigurationen für Anmeldeinformationen
• Falsch formatierte nachgeschaltete API-Definitionen
• Ungültige URLs oder Bereichsformate

Überprüfen sie Containerprotokolle auf Überprüfungsmeldungen:

kubectl logs <pod-name> -c sidecar

Bewährte Methoden

1. Verwenden Sie geheime Schlüssel für Anmeldeinformationen: Speichern von geheimen Clientschlüsseln und Zertifikaten in Kubernetes Secrets oder Azure Key Vault. Siehe auch https://aka.ms/msidweb/client-credentials
2. Separate Konfiguration pro Umgebung: Verwenden von ConfigMaps zum Verwalten von umgebungsspezifischen Einstellungen
3. Aktivieren der geeigneten Protokollierung: Verwenden der Debugprotokollierung in der Entwicklung, Information/Warnung in der Produktion
4. Konfigurieren von Integritätsprüfungen: Sicherstellen, dass Endpunkte für die Integritätsprüfung ordnungsgemäß konfiguriert sind
5. Verwenden sie Workload Identity für Container: Für containerisierte Bereitstellungen (AKS) bevorzugen Sie die Azure AD Workload Identity mit SignedAssertionFilePath mehr geheimen Clientschlüsseln für erhöhte Sicherheit.
6. Verwenden der verwalteten Identität für VMs/App Services: Verwenden Sie für Azure-VMs und App-Dienste systembasierte oder vom Benutzer zugewiesene verwaltete Identitäten.
7. Überprüfen zur Bereitstellungszeit: Testen der Konfiguration im Staging vor der Produktionsbereitstellung

Siehe auch

• Agentidentitäten
• Endpunktreferenz
• Bewährte Methoden für Sicherheit
• Problembehandlung