Configuratiereferentie: Microsoft Entra ID Auth SDK-instellingen (sidecar)

Deze handleiding bevat configuratieopties voor de Microsoft Entra ID Auth SDK (sidecar), een containerverificatieservice die tokenverwerving en -beheer verwerkt voor toepassingen in gecontaineriseerde omgevingen. De SDK vereenvoudigt identiteitsintegratie door Microsoft Entra ID verificatie te beheren, namens (OBO)-tokenstromen en downstream-API-aanroepen zonder dat toepassingen verificatiebibliotheken rechtstreeks hoeven in te sluiten.

Hoewel deze handleiding gericht is op Kubernetes-implementatiepatronen, kan de SDK worden geïmplementeerd in elke containeromgeving, waaronder Docker, Azure Container Instances en andere platformen voor containerindeling.

Als u implementeert in Azure Kubernetes Service (AKS), ontwikkelomgevingen instelt of productieworkloads configureert, bevat deze verwijzing configuratiepatronen, referentietypen en omgevingsvariabelen die nodig zijn om uw toepassingen te beveiligen met Microsoft Entra ID.

Overzicht van configuratie

De Microsoft Entra ID Auth SDK (sidecar) wordt geconfigureerd met behulp van configuratiebronnen volgens ASP.NET Core conventies. Configuratiewaarden kunnen worden opgegeven via meerdere methoden, waaronder:

• Omgevingsvariabelen (aanbevolen voor Kubernetes)
• Entra ID configuratie: appsettings.json bestand dat is gekoppeld aan de container of is ingesloten in het YAML-bestand.
• Opdrachtregelargumenten
• Azure App Configuration of Key Vault (voor geavanceerde scenario's)

Basisinstellingen voor Entra ID

voor Microsoft Entra ID Auth SDK-implementaties (sidecar) zijn kerninstellingen van Entra ID vereist voor het verifiëren van binnenkomende tokens en het verkrijgen van tokens voor downstream-API's. Gebruik de juiste clientreferenties in de volgende YAML-indeling, meestal als omgevingsvariabelen, om veilige verificatie te garanderen.

Vereiste configuratie

Configureer eerst de belangrijkste Entra ID-instellingen voor de SDK om binnenkomende tokens te verifiëren en tokens voor downstream-API's te verkrijgen.

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

Configuratie van clientreferenties

De Microsoft Entra ID Auth SDK (sidecar) ondersteunt meerdere clientreferentietypen voor verificatie met Microsoft Entra ID bij het verkrijgen van tokens voor downstream-API's. Kies het referentietype dat het beste past bij uw implementatieomgeving en beveiligingsvereisten en zorg ervoor dat de configuratie die u kiest geschikt is voor uw scenario.

Elk referentietype dient voor verschillende scenario's:

• Clientgeheim: Eenvoudige installatie voor ontwikkeling en testen (niet aanbevolen voor productie)
• Key Vault Certificate: Productieomgevingen met gecentraliseerd certificaatbeheer
• Bestandscertificaat: wanneer certificaten worden gekoppeld als bestanden (bijvoorbeeld via Kubernetes-geheimen)
• Certificate Store: Windows omgevingen met certificaatarchieven
• Workload Identity for Containers: Aanbevolen voor AKS, met behulp van Microsoft Entra Workload-id met projectie van tokens op basis van bestanden
• Beheerde identiteit voor VM's/App Services: Azure Virtuele Machines en App Services met door het systeem of de gebruiker toegewezen beheerde identiteiten (niet voor containers)

Configureer een of meer referentiebronnen in de volgende YAML-indeling:

Kies een referentie per omgeving

Selecteer de referentie op basis van waar de sidecar wordt uitgevoerd. Beide SignedAssertionFilePath en SignedAssertionFromManagedIdentity zijn federatieve identiteitsreferenties (FIC). Ze verschillen in de wijze waarop de sidecar de ondertekende verklaring verkrijgt.

Belangrijk: SignedAssertionFromManagedIdentity is geen Kubernetes-referentie voor algemeen gebruik en is geen terugval voor SignedAssertionFilePath. Het maakt gebruik van Azure Beheerde identiteit en test Azure hostingomgevingen zoals Service Fabric, App Service en IMDS. Op een niet-Azure host vindt deze geen van deze, en de aanvraag treedt uiteindelijk een time-out op tegen IMDS. Als uw sidecar onverwacht IMDS bereikt, hebt u dit brontype geselecteerd. Gebruik in plaats daarvan SignedAssertionFilePath.

Clientgeheim

Met deze configuratie stelt u Entra ID verificatie in met behulp van een clientgeheim voor service-naar-service-verificatie.

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

Certificaat van Key Vault

Met deze configuratie wordt Entra ID verificatie ingesteld met behulp van een certificaat dat is opgeslagen in 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>"

Certificaat uit bestand

Met deze configuratie wordt Entra ID verificatie ingesteld met behulp van een certificaat dat is opgeslagen als een bestand.

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

Certificaat uit archief

Met deze configuratie wordt Entra ID verificatie ingesteld met behulp van een certificaat uit het lokale certificaatarchief.

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

Workloadidentiteit op AKS (aanbevolen voor AKS)

Met deze configuratie wordt Entra ID verificatie ingesteld met behulp van Microsoft Entra Workload-id op AKS. Dit is de aanbevolen methode voor AKS, omdat de Azure Webhook-webhookprojecten voor workloadidentiteit het token voor u roteert.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Opmerking: op AKS wordt het pad naar het tokenbestand /var/run/secrets/azure/tokens/azure-identity-token of een omgevingsvariabele automatisch geprojecteerd door de Azure workloadidentiteitswebhook wanneer uw pod correct is geconfigureerd met de aantekening van het serviceaccount en het podlabel. Zie Managed Identity gebruiken voor volledige installatie-instructies.

Workloadidentiteit voor niet-Azure of on-premises Kubernetes

De agentidentiteitsstroom is niet beperkt tot AKS. Elk Kubernetes-platform, inclusief on-premises en andere clouds, kan worden gebruikt SignedAssertionFilePath met federatie van workloadidentiteit. Omdat er geen Azure workloadidentiteitswebhook buiten AKS is, wijst u de sidecar aan bij het geprojecteerde serviceaccounttoken dat uw platform koppelt.

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

De sidecar herleest het bestand op elke tokenaanvraag, zodat platformgestuurde rotatie van de verwachte assertie automatisch wordt ondersteund.

Als u deze referentie wilt gebruiken voor niet-Azure Kubernetes, moet uw omgeving voldoen aan deze vereisten:

• Uw Kubernetes-platform projecteert een serviceaccounttoken in de sidecar-pod, bijvoorbeeld via een geprojecteerd serviceAccountToken volume.
• Het cluster maakt een openbaar bereikbaar OIDC-verlener en JWKS-eindpunt beschikbaar, zodat Microsoft Entra de assertie kan valideren.
• Een federatieve identiteitsreferentie (FIC) wordt geconfigureerd in de Blauwdruktoepassing, met de verlener en het onderwerp dat overeenkomt met het verwachte token.

Als uw platform geen geprojecteerd OIDC-token of een openbare verlener kan opgeven, gebruikt u in plaats daarvan een certificaatreferentie zoals Certificaat van Key Vault of Certificaat uit bestand.

Beheerde identiteit voor VM's en App Services

Gebruik SignedAssertionFromManagedIdentity voor klassieke Azure Managed Identity-scenario's op Virtual Machines of App Services (niet containers):

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

Belangrijk: gebruik niet SignedAssertionFromManagedIdentity in niet-Azure of on-premises omgevingen. Het maakt gebruik van Azure Managed Identity via IMDS en werkt alleen op Azure compute die beheerde identiteit biedt. Op een niet-Azure host test deze Azure hosteindpunten en treedt er vervolgens een time-out op tegen IMDS. Dit kan eruitzien als de SDK wordt vastgelegd in IMDS. Gebruik voor Kubernetes overal, inclusief AKS.SignedAssertionFilePath Zie voor meer informatie https://aka.ms/idweb/client-credentials

Aanvullende bronnen

Zie de CredentialDescription-specificatie in de opslagplaats microsoft-identity-abstractions-for-dotnet voor meer informatie over alle configuratieopties voor referenties en hun gebruik.

Prioriteit van referenties

Configureer meerdere referenties met selectie op basis van prioriteit:

# 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

De Microsoft Entra ID Auth SDK (sidecar) evalueert referenties in numerieke volgorde (0, 1, 2, enzovoort) en gebruikt de eerste referentie die is geverifieerd.

Configuratie van downstream-API's

Configureer downstream-API's die uw toepassing moet aanroepen met behulp van tokenstromen namens (OBO). De Microsoft Entra ID Auth SDK (sidecar) beheert het verkrijgen van tokens en biedt verificatieheaders voor deze API-aanroepen. Elke downstream-API vereist een unieke configuratienaam en specifieke parameters voor het verkrijgen van tokens en het verwerken van HTTP-aanvragen.

Definieer elke downstream-API met de basis-URL, vereiste bereiken en optionele parameters. De SDK verwerkt het ophalen van tokens automatisch met behulp van het binnenkomende gebruikerstoken en levert de juiste autorisatieheaders voor de API-aanroepen van uw toepassing.

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

Opties voor het verkrijgen van tokens

Het gedrag voor het verkrijgen van tokens verfijnen:

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

- name: DownstreamApis__Graph__AcquireTokenOptions__AuthenticationScheme
  value: "Bearer"

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

Configuratie van ondertekende HTTP-aanvraag (SHR)

Ondertekende HTTP-aanvragen inschakelen voor verbeterde beveiliging:

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

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

Configuratie van logboekregistratie

Logboekregistratieniveaus configureren:

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

instellingen voor ASP.NET Core

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

Per-Request configuratie-onderdrukkingen

Alle eindpunten voor het verkrijgen van tokens accepteren queryparameters om de configuratie te overschrijven:

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

Overschrijvingen van agentidentiteit

Geef de identiteit van de agent op aanvraag op:

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

Belangrijke regels:

• AgentUsername en AgentUserId vereisen AgentIdentity
• AgentUsername en AgentUserId sluiten elkaar wederzijds uit

Zie Agentidentiteiten voor gedetailleerde semantiek.

Volledig configuratievoorbeeld

Hieronder vindt u een voorbeeld dat gereed is voor productie waarin wordt getoond hoe u de SDK implementeert met de juiste scheiding van configuratie en geheimen. In dit voorbeeld ziet u hoe u meerdere downstream-API's configureert met behulp van Kubernetes ConfigMaps voor niet-gevoelige instellingen, het veilig opslaan van referenties in Geheimen en het toepassen van omgevingsspecifieke configuraties voor beveiligde implementatie.

Dit patroon volgt aanbevolen procedures voor Kubernetes door configuratiegegevens te scheiden van gevoelige referenties, waardoor effectief beheer van verschillende omgevingen mogelijk is, terwijl de beveiliging behouden blijft.

Kubernetes ConfigMap

In de ConfigMap worden niet-gevoelige configuratie-instellingen voor de SDK opgeslagen, waaronder Entra ID-instellingen, downstream-API's en logboekregistratieniveaus.

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

In het geheim worden gevoelige referenties, zoals clientgeheimen, afzonderlijk van de ConfigMap opgeslagen.

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

Implementatie met ConfigMap en geheim

De implementatie koppelt zowel de ConfigMap als het geheim aan de SDK-container, zodat de configuratie en referenties correct worden gescheiden.

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

Omgevingsspecifieke configuratie

Configureer omgevingsspecifieke instellingen om beveiliging, logboekregistratie en tenantisolatie aan te passen voor uw implementatieomgevingen. Elke omgeving vereist verschillende configuratiemethoden om de efficiëntie van ontwikkeling, faseringsvalidatie en productiebeveiligingsvereisten te verdelen.

Ontwikkeling

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

Productie

- 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

De Microsoft Entra ID Auth SDK (sidecar) valideert de configuratie bij het opstarten en registreert fouten voor:

• Vereiste instellingen ontbreken (TenantId, ClientId)
• Ongeldige referentieconfiguraties
• Ongeldige downstream-API-definities
• Ongeldige URL's of bereikindelingen

Controleer containerlogboeken op validatieberichten:

kubectl logs <pod-name> -c sidecar

Problemen met referenties oplossen

Aanvragen bereiken onverwacht IMDS of time-out

Symptoom: De sidecar loopt vast of treedt een time-out op bij het verkrijgen van een downstreamtoken en logboeken tonen aanvragen aan het IMDS-eindpunt (169.254.169.254), zelfs op een niet-Azure host.

Oorzaak: De referentie is geconfigureerd als SignedAssertionFromManagedIdentity. Dit brontype test opzettelijk Azure hostingomgevingen en IMDS, die niet buiten Azure bestaan. Dit is een configuratiekeuze, geen terugval van SignedAssertionFilePath.

Oplossing:

1. Bevestig dat de effectieve SourceType is SignedAssertionFilePath, niet SignedAssertionFromManagedIdentity.
2. Controleer of er geen omgevingsvariabele of ConfigMap opnieuw wordt geïntroduceerd SignedAssertionFromManagedIdentity.
3. SignedAssertionFileDiskPath Controleer of dit verwijst naar het verwachte token dat is gekoppeld in de sidecarcontainer.
4. Controleer op niet-Azure Kubernetes of de OIDC-verlener en JWKS van het cluster openbaar bereikbaar zijn en of er een overeenkomende FIC bestaat in de Blauwdruktoepassing.

Wanneer u een permanent probleem rapporteert, legt u de sidecar-versie, de effectieve runtimeconfiguratie en de containerlogboeken vast van één mislukte aanvraag.

Beste praktijken

1. Geheimen gebruiken voor referenties: clientgeheimen en -certificaten opslaan in Kubernetes Secrets of Azure Key Vault. Zie ook https://aka.ms/msidweb/client-credentials
2. Afzonderlijke configuratie per omgeving: ConfigMaps gebruiken om omgevingsspecifieke instellingen te beheren
3. Geschikte logboekregistratie inschakelen: logboekregistratie voor foutopsporing gebruiken in ontwikkeling, informatie/waarschuwing in productie
4. Statuscontroles configureren: zorg ervoor dat de eindpunten van de statuscontrole correct zijn geconfigureerd
5. Werkbelastingidentiteit voor containers: Voor containerimplementaties (AKS) geeft u de voorkeur aan Microsoft Entra Workload-id met SignedAssertionFilePath via clientgeheimen voor verbeterde beveiliging
6. Managed Identity gebruiken voor VM's/App Services: Gebruik voor Azure VM's en App Services systeem- of door de gebruiker toegewezen beheerde identiteiten
7. Valideren tijdens implementatietijd: configuratie testen in fasering vóór productie-implementatie

Verwante inhoud

• Agentidentiteiten
• Naslaginformatie over eindpunten
• Aanbevolen beveiligingsprocedures
• Troubleshooting