Konfigurationsreferenz: Microsoft Entra SDK für Agent-ID-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, indem Microsoft Entra ID Authentifizierung, OBO-Tokenflüsse und nachgeschaltete API-Aufrufe verwaltet werden, 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 Container Instances 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 erforderlich sind, um Ihre Anwendungen mit Microsoft Entra ID zu sichern.

Übersicht über die Konfiguration

Das Microsoft Entra SDK für Die Agent-ID 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 Configuration oder Key Vault (für erweiterte Szenarien)

Kerneinstellungen für Entra ID

Microsoft Entra SDK für Agent-ID-Bereitstellungen erfordern grundlegende Entra ID Einstellungen zum Authentifizieren eingehender Token und Abrufen von Token für nachgeschaltete APIs. 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 Agent-ID 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 Certificate: Produktionsumgebungen mit zentralisierter Zertifikatverwaltung
• Dateizertifikat: Wenn Zertifikate als Dateien bereitgestellt werden (z. B. über Kubernetes geheime Schlüssel)
• Certificate Store: Windows Umgebungen mit Zertifikatspeichern
• Workload Identity for Containers: Recommended for AKS, using Microsoft Entra Workload ID with file-based token projection
• Managed Identity for VMs/App Services: Azure Virtual Machines und App Services mit system- oder vom Benutzer zugewiesenen verwalteten Identitäten (nicht für Container)

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

Geheimer Clientschlüssel

Diese Konfiguration richtet 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 von Key Vault

Diese Konfiguration richtet 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 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 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 Entra ID Authentifizierung mithilfe von Microsoft Entra Workload ID 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"

Note: 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 für klassische Azure Szenarien mit verwalteter Identität in Virtual Machines oder App Services (keine Container) SignedAssertionFromManagedIdentity:

- 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

Weitere 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 Agent-ID 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 Agent-ID 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 Agent-ID ü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. Use Secrets for Credentials: Speichern geheimer Clientschlüssel und Zertifikate 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. Use Workload Identity for Containers: For containerized deployments (AKS), prefer Microsoft Entra Workload ID with SignedAssertionFilePath over client secrets for enhanced security
6. Use Managed Identity for VMs/App Services: For Azure VMs and App Services, use system or user-assigned managed identity
7. Überprüfen zur Bereitstellungszeit: Testen der Konfiguration im Staging vor der Produktionsbereitstellung

Verwandte Inhalte

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