Konfigurationsreferens: Microsoft Entra ID inställningar för Auth SDK (sidovagn)

Den här guiden innehåller konfigurationsalternativ för Microsoft Entra ID Auth SDK (sidovagn), en containerbaserad autentiseringstjänst som hanterar tokenanskaffning och hantering för program i containerbaserade miljöer. SDK förenklar identitetsintegrering genom att hantera Microsoft Entra ID autentisering, OBO-tokenflöden (å OBO)-flöden och underordnade API-anrop utan att kräva att program bäddar in autentiseringsbibliotek direkt.

Den här guiden fokuserar på Kubernetes-distributionsmönster, men SDK:t kan distribueras i alla containerbaserade miljöer, inklusive Docker, Azure Container Instances och andra plattformar för containerorkestrering.

Om du distribuerar till Azure Kubernetes Service (AKS), konfigurerar utvecklingsmiljöer eller konfigurerar produktionsarbetsbelastningar omfattar den här referensen konfigurationsmönster, typer av autentiseringsuppgifter och miljövariabler som behövs för att skydda dina program med Microsoft Entra ID.

Konfiguration – översikt

Microsoft Entra ID Auth SDK (sidovagn) konfigureras med hjälp av konfigurationskällor enligt ASP.NET Core konventioner. Konfigurationsvärden kan anges via flera metoder, inklusive:

• Miljövariabler (rekommenderas för Kubernetes)
• Entra ID konfiguration – appsettings.json fil som är kopplad till containern eller inbäddad i yaml-filen.
• Kommandoradsargument
• Azure App Configuration eller Key Vault (för avancerade scenarier)

Core Entra ID-inställningar

Microsoft Entra ID Auth SDK-distributioner (sidovagn) kräver grundläggande Entra ID inställningar för att autentisera inkommande token och hämta token för underordnade API:er. Använd lämpliga klientautentiseringsuppgifter i följande YAML-format, vanligtvis som miljövariabler, för att säkerställa säker autentisering.

Nödvändig konfiguration

Konfigurera först kärninställningarna för Entra ID för SDK för att autentisera inkommande token och hämta token för underordnade API:er.

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

Konfiguration av klientautentiseringsuppgifter

Microsoft Entra ID Auth SDK (sidovagn) stöder flera typer av klientautentiseringsuppgifter för autentisering med Microsoft Entra ID när token hämtas för underordnade API:er. Välj den typ av autentiseringsuppgifter som passar bäst för din distributionsmiljö och säkerhetskrav och se till att den konfiguration du väljer är lämplig för ditt scenario.

Varje typ av autentiseringsuppgifter har olika scenarier:

• Klienthemlighet: Enkel installation för utveckling och testning (rekommenderas inte för produktion)
• Key Vault Certificate: Produktionsmiljöer med centraliserad certifikathantering
• Filcertifikat: När certifikat monteras som filer (t.ex. via Kubernetes-hemligheter)
• Certificate Store: Windows miljöer med certifikatarkiv
• Workload Identity for Containers: Rekommenderas för AKS med Microsoft Entra Workload ID med filbaserad tokenprojektion
• Hanterad identitet för virtuella datorer/App Services: Azure Virtual Machines och App Services med system- eller användartilldelade hanterade identiteter (inte för containrar)

Konfigurera en eller flera autentiseringskällor i följande YAML-format:

Välj en autentiseringsuppgift efter miljö

Välj autentiseringsuppgifterna baserat på var sidovagnen körs. Både SignedAssertionFilePath och SignedAssertionFromManagedIdentity är federerade identitetsautentiseringsuppgifter (FIC). De skiljer sig åt i hur sidovagnen får det signerade försäkran.

Viktigt: SignedAssertionFromManagedIdentity är inte en generell Kubernetes-autentiseringsuppgift och det är inte en reserv för SignedAssertionFilePath. Den använder Azure hanterad identitet och avsökningar Azure värdmiljöer som Service Fabric, App Service och IMDS. På en icke-Azure värd hittar den ingen av dessa, och begäran överskrider slutligen tidsgränsen mot IMDS. Om sidovagnen oväntat når IMDS valde du den här källtypen. Använd SignedAssertionFilePath i stället.

Klienthemlighet

Den här konfigurationen konfigurerar Entra ID autentisering med hjälp av en klienthemlighet för tjänst-till-tjänst-autentisering.

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

Certifikat från Key Vault

Den här konfigurationen konfigurerar Entra ID autentisering med hjälp av ett certifikat som lagras i 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>"

Certifikat från fil

Den här konfigurationen konfigurerar Entra ID autentisering med hjälp av ett certifikat som lagras som en fil.

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

Certifikat från arkivet

Den här konfigurationen konfigurerar Entra ID autentisering med hjälp av ett certifikat från det lokala certifikatarkivet.

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

Arbetsbelastningsidentitet på AKS (rekommenderas för AKS)

Den här konfigurationen konfigurerar Entra ID autentisering med hjälp av Microsoft Entra Workload ID på AKS. Det här är den rekommenderade metoden för AKS eftersom webhooken Azure Workload Identity och roterar token åt dig.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Obs! På AKS projiceras tokenfilsökvägen /var/run/secrets/azure/tokens/azure-identity-token eller en miljövariabel automatiskt av webhooken Azure Workload Identity när podden är korrekt konfigurerad med anteckningen och poddetiketten för tjänstkontot. Se Använda hanterad identitet för fullständiga installationsinstruktioner.

Arbetsbelastningsidentitet för icke-Azure eller lokal Kubernetes

Agentidentitetsflödet är inte begränsat till AKS. Alla Kubernetes-plattformar, inklusive lokala och andra moln, kan använda SignedAssertionFilePath med arbetsbelastningsidentitetsfederation. Eftersom det inte finns någon webhook för Azure arbetsbelastningsidentitet utanför AKS pekar du sidovagnen på den beräknade tjänstkontotoken som plattformen monterar.

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

Sidovagnen läser om filen på varje tokenbegäran, så plattformsdriven rotation av den projicerade försäkran stöds automatiskt.

Om du vill använda den här autentiseringsuppgiften på kubernetes som inte Azure måste din miljö uppfylla följande krav:

• Kubernetes-plattformen projicerar en tjänstkontotoken i sidovagnspodden, till exempel via en beräknad serviceAccountToken volym.
• Klustret exponerar en offentligt nåbar OIDC-utfärdare och JWKS-slutpunkt så att Microsoft Entra kan verifiera försäkran.
• En federerad identitetsautentiseringsuppgift (FIC) konfigureras i Blueprint-programmet, med utfärdaren och ämnet som matchar den planerade token.

Om din plattform inte kan tillhandahålla en projicerad OIDC-token eller en offentlig utfärdare använder du ett certifikatautentiseringsuppgifter som Certifikat från Key Vault eller Certifikat från filen i stället.

Hanterad identitet för virtuella datorer och App Services

Använd SignedAssertionFromManagedIdentity för klassiska Azure hanterade identitetsscenarier på Virtual Machines eller App Services (inte containrar):

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

Viktigt: Använd SignedAssertionFromManagedIdentity inte i icke-Azure eller lokala miljöer. Den använder Azure hanterad identitet via IMDS och fungerar endast på Azure beräkning som tillhandahåller hanterad identitet. På en icke-Azure värd avsöker den Azure värdslutpunkter och överskrider sedan tidsgränsen mot IMDS, vilket kan se ut som att SDK:et hårdkodas till IMDS. För Kubernetes var som helst, inklusive AKS, använder du SignedAssertionFilePath. Mer information finns i https://aka.ms/idweb/client-credentials

Ytterligare resurser

Fullständig information om alla konfigurationsalternativ för autentiseringsuppgifter och deras användning finns i specifikationen credentialDescription i lagringsplatsen microsoft-identity-abstractions-for-dotnet.

Prioritet för autentiseringsuppgifter

Konfigurera flera autentiseringsuppgifter med prioritetsbaserad markering:

# 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

Microsoft Entra ID Auth SDK (sidovagn) utvärderar autentiseringsuppgifter i numerisk ordning (0, 1, 2 osv.) och använder den första autentiseringsuppgiften som autentiserar.

Konfiguration av underordnade API:er

Konfigurera underordnade API:er som programmet behöver anropa med hjälp av OBO-tokenflöden (å OBO:s vägnar). Microsoft Entra ID Auth SDK (sidovagn) hanterar tokenförvärv och tillhandahåller autentiseringshuvuden för dessa API-anrop. Varje underordnade API kräver ett unikt konfigurationsnamn och specifika parametrar för tokenförvärv och HANTERING av HTTP-begäranden.

Definiera varje underordnade API med dess bas-URL, nödvändiga omfång och valfria parametrar. SDK hanterar automatiskt tokenförvärv med hjälp av den inkommande användartoken och tillhandahåller lämpliga auktoriseringshuvuden för programmets API-anrop.

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

Alternativ för tokenförvärv

Finjustera anskaffningsbeteendet för token:

- 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 av signerad HTTP-begäran (SHR)

Aktivera signerade HTTP-begäranden för förbättrad säkerhet:

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

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

Loggningskonfiguration

Konfigurera loggningsnivåer:

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

ASP.NET Core inställningar

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

Per-Request konfigurations åsidosättningar

Alla slutpunkter för tokenförvärv accepterar frågeparametrar för att åsidosätta konfigurationen:

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

Åsidosättningar av agentidentitet

Ange agentidentitet vid begäran:

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

Viktiga regler:

• AgentUsername och AgentUserId kräver AgentIdentity
• AgentUsername och AgentUserId är ömsesidigt uteslutande

Se Agentidentiteter för detaljerad semantik.

Komplett konfigurationsexempel

Följande innehåller ett produktionsklart exempel som visar hur du distribuerar SDK med korrekt separation av konfiguration och hemligheter. Det här exemplet visar hur du konfigurerar flera underordnade API:er, använder Kubernetes ConfigMaps för icke-känsliga inställningar, lagrar autentiseringsuppgifter på ett säkert sätt i Hemligheter och tillämpar miljöspecifika konfigurationer för säker distribution.

Det här mönstret följer Kubernetes metodtips genom att separera konfigurationsdata från känsliga autentiseringsuppgifter, möjliggöra effektiv hantering av olika miljöer samtidigt som säkerheten upprätthålls.

Kubernetes ConfigMap

ConfigMap lagrar icke-känsliga konfigurationsinställningar för SDK, inklusive Entra ID inställningar, underordnade API:er och loggningsnivåer.

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

Hemligheten lagrar känsliga autentiseringsuppgifter, till exempel klienthemligheter, separat från ConfigMap.

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

Distribution med ConfigMap och hemlighet

Distributionen monterar både ConfigMap och Secret i SDK-containern, vilket säkerställer att konfigurationen och autentiseringsuppgifterna är korrekt avgränsade.

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

Miljöspecifik konfiguration

Konfigurera miljöspecifika inställningar för att skräddarsy säkerhet, loggning och klientisolering för dina distributionsmiljöer. Varje miljö kräver olika konfigurationsmetoder för att balansera utvecklingseffektivitet, mellanlagringsvalidering och säkerhetskrav för produktion.

Utveckling

- 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

Microsoft Entra ID Auth SDK (sidovagn) verifierar konfigurationen vid start och loggar fel för:

• Nödvändiga inställningar saknas (TenantId, ClientId)
• Ogiltiga konfigurationer av autentiseringsuppgifter
• Felaktigt underordnad API-definition
• Ogiltiga URL:er eller omfångsformat

Kontrollera containerloggarna för valideringsmeddelanden:

kubectl logs <pod-name> -c sidecar

Felsöka autentiseringsuppgifter

Begäranden når oväntat IMDS eller tidsgräns

Symptom: Sidovagnen låser sig eller överskrider tidsgränsen för att hämta en nedströmstoken och loggar visar begäranden till IMDS-slutpunkten (169.254.169.254), även på en värd som inte är Azure.

Orsak: Autentiseringsuppgifterna har konfigurerats som SignedAssertionFromManagedIdentity. Den källtypen avsöker avsiktligt Azure värdmiljöer och IMDS, som inte finns utanför Azure. Det här är ett konfigurationsalternativ, inte en återställning från SignedAssertionFilePath.

Lösning:

1. Bekräfta att det effektiva SourceType är SignedAssertionFilePath, inte SignedAssertionFromManagedIdentity.
2. Kontrollera att ingen miljövariabel eller ConfigMap åsidosätter återinför .SignedAssertionFromManagedIdentity
3. Kontrollera att SignedAssertionFileDiskPath pekar på den projicerade token som är monterad i sidovagnscontainern.
4. På icke-Azure Kubernetes kontrollerar du att klustrets OIDC-utfärdare och JWKS kan nås offentligt och att det finns en matchande FIC i Blueprint-programmet.

När du rapporterar ett beständigt problem samlar du in sidovagnsversionen, den effektiva körningskonfigurationen och containerloggarna från en misslyckad begäran.

Metodtips

1. Använd hemligheter för autentiseringsuppgifter: Lagra klienthemligheter och certifikat i Kubernetes-hemligheter eller Azure Key Vault. Se även https://aka.ms/msidweb/client-credentials
2. Separat konfiguration per miljö: Använd ConfigMaps för att hantera miljöspecifika inställningar
3. Aktivera lämplig loggning: Använd felsökningsloggning under utveckling, information/varning i produktion
4. Konfigurera hälsokontroller: Kontrollera att slutpunkterna för hälsokontroll är korrekt konfigurerade
5. Använd arbetsbelastningsidentitet för containrar: För containerbaserade distributioner (AKS) föredrar du Microsoft Entra Workload ID med SignedAssertionFilePath framför klienthemligheter för ökad säkerhet
6. Använd hanterad identitet för virtuella datorer/App Services: För Azure virtuella datorer och App Services använder du system- eller användartilldelade hanterade identiteter
7. Verifiera vid distributionstid: Testa konfigurationen i mellanlagringen före produktionsdistributionen

Relaterat innehåll

• Agentidentiteter
• Referens för slutpunkter
• Metodtips för säkerhet
• Troubleshooting