Informazioni di riferimento sulla configurazione: impostazioni Microsoft Entra ID Auth SDK (sidecar)

Questa guida fornisce opzioni di configurazione per Microsoft Entra ID Auth SDK (sidecar), un servizio di autenticazione in contenitori che gestisce l'acquisizione e la gestione dei token per le applicazioni in ambienti in contenitori. L'SDK semplifica l'integrazione delle identità gestendo Microsoft Entra ID l'autenticazione, i flussi di token OBO (on-behalf-of) e le chiamate API downstream senza richiedere alle applicazioni di incorporare direttamente le librerie di autenticazione.

Anche se questa guida è incentrata sui modelli di distribuzione kubernetes, l'SDK può essere distribuito in qualsiasi ambiente in contenitori, tra cui Docker, Istanze di Azure Container e altre piattaforme di orchestrazione dei contenitori.

Se si esegue la distribuzione in Servizio Azure Kubernetes (AKS), si configurano ambienti di sviluppo o si configurano carichi di lavoro di produzione, questo riferimento illustra i modelli di configurazione, i tipi di credenziali e le variabili di ambiente necessari per proteggere le applicazioni con Microsoft Entra ID.

Panoramica della configurazione

Il Microsoft Entra ID Auth SDK (sidecar) viene configurato usando le origini di configurazione che seguono le convenzioni di ASP.NET Core. I valori di configurazione possono essere forniti tramite più metodi, tra cui:

• Variabili di ambiente (consigliate per Kubernetes)
• Entra ID configurazione: appsettings.json file collegato al contenitore o incorporato nel file yaml.
• Argomenti della riga di comando
• Configurazione app di Azure o Key Vault (per scenari avanzati)

Impostazioni di base Entra ID

Microsoft Entra ID distribuzioni di Auth SDK (sidecar) richiedono le impostazioni di base Entra ID per autenticare i token in ingresso e acquisire i token per le API downstream. Usare le credenziali client appropriate nel formato YAML seguente, in genere come variabili di ambiente, per garantire l'autenticazione sicura.

Configurazione richiesta

Prima di tutto, configurare le impostazioni di base Entra ID per l'SDK per autenticare i token in ingresso e acquisire i token per le API downstream.

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

Configurazione delle credenziali client

Microsoft Entra ID Auth SDK (sidecar) supporta più tipi di credenziali client per l'autenticazione con Microsoft Entra ID durante l'acquisizione di token per le API downstream. Scegliere il tipo di credenziale più adatto all'ambiente di distribuzione e ai requisiti di sicurezza e assicurarsi che la configurazione scelta sia appropriata per lo scenario in uso.

Ogni tipo di credenziale offre scenari diversi:

• Segreto client: configurazione semplice per lo sviluppo e il test (non consigliato per la produzione)
• Key Vault Certificato: ambienti di produzione con gestione centralizzata dei certificati
• Certificato file: quando i certificati vengono montati come file (ad esempio, tramite segreti Kubernetes)
• Certificate Store: ambienti Windows con archivi certificati
• Accesso di lavoro per contenitori: consigliato per il servizio Azure Kubernetes, usando ID dei carichi di lavoro di Microsoft Entra con la proiezione di token basata su file
• Identità gestita per macchine virtuali/servizi app: Macchine virtuali di Azure e servizi app con identità gestite assegnate dal sistema o dall'utente (non per i contenitori)

Configurare una o più origini credenziali nel formato YAML seguente:

Scegliere una credenziale per ambiente

Selezionare le credenziali in base alla posizione in cui viene eseguito il sidecar. Sia SignedAssertionFilePath che SignedAssertionFromManagedIdentity sono credenziali di identità federate (FIC). Differiscono in base al modo in cui il sidecar ottiene l'asserzione firmata.

Importante: SignedAssertionFromManagedIdentity non è una credenziale Kubernetes per utilizzo generico e non è un fallback per SignedAssertionFilePath. Usa Azure identità gestita e probe Azure ambienti di hosting, ad esempio Fabric del servizio, servizio app e IMDS. In un host non Azure trova nessuno di questi e alla fine la richiesta raggiunge il timeout per IMDS. Se il sidecar raggiunge in modo imprevisto IMDS, è stato selezionato questo tipo di origine. Utilizzare invece SignedAssertionFilePath.

Segreto del cliente

Questa configurazione configura Entra ID'autenticazione usando un segreto client per l'autenticazione da servizio a servizio.

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

Certificato da Key Vault

Questa configurazione configura Entra ID'autenticazione usando un certificato archiviato 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>"

Certificato dal file

Questa configurazione configura Entra ID'autenticazione usando un certificato archiviato come file.

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

Certificato dall'archivio

Questa configurazione configura Entra ID'autenticazione usando un certificato dall'archivio certificati locale.

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

Identità del carico di lavoro nel servizio Azure Kubernetes (scelta consigliata per il servizio Azure Kubernetes)

Questa configurazione configura Entra ID'autenticazione usando ID dei carichi di lavoro di Microsoft Entra nel servizio Azure Kubernetes. Questo è l'approccio consigliato nel servizio Azure Kubernetes perché i progetti webhook di identità del carico di lavoro Azure e ruotano automaticamente il token.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Nota: nel servizio Azure Kubernetes, il percorso /var/run/secrets/azure/tokens/azure-identity-token del file del token o una variabile di ambiente viene proiettato automaticamente dal webhook identità del carico di lavoro Azure quando il pod è configurato correttamente con l'annotazione dell'account del servizio e l'etichetta del pod. Per istruzioni complete sull'installazione, vedere Uso dell'identità gestita .

Identità del carico di lavoro per Kubernetes non Azure o locale

Il flusso di identità dell'agente non è limitato al servizio Azure Kubernetes. Qualsiasi piattaforma Kubernetes, inclusa l'ambiente locale e altri cloud, può essere usata SignedAssertionFilePath con la federazione delle identità del carico di lavoro. Poiché non esiste Azure webhook di identità del carico di lavoro all'esterno del servizio Azure Kubernetes, si punta il sidecar al token dell'account del servizio proiettato che la piattaforma monta.

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

Il sidecar rilegge il file in ogni richiesta di token, quindi la rotazione basata sulla piattaforma dell'asserzione proiettata viene supportata automaticamente.

Per usare queste credenziali in Kubernetes non Azure, l'ambiente deve soddisfare questi prerequisiti:

• La piattaforma Kubernetes proietta un token dell'account del servizio nel pod sidecar, ad esempio tramite un volume proiettato serviceAccountToken .
• Il cluster espone un emittente OIDC raggiungibile pubblicamente e un endpoint JWKS in modo che Microsoft Entra possa convalidare l'asserzione.
• Nell'applicazione Blueprint è configurata una credenziale di identità federata con l'autorità emittente e l'oggetto che corrispondono al token proiettato.

Se la piattaforma non può fornire un token OIDC proiettato o un'autorità emittente pubblica, usare invece credenziali del certificato, ad esempio Certificato da Key Vault o Certificato dal file.

Identità gestita per macchine virtuali e servizi app

Per gli scenari classici di identità gestita di Azure in Macchine virtuali o servizi app (non contenitori), usare SignedAssertionFromManagedIdentity:

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

Importante: non usare SignedAssertionFromManagedIdentity in ambienti non Azure o locali. Usa Azure'identità gestita tramite IMDS e funziona solo sul calcolo Azure che fornisce l'identità gestita. In un host non Azure, esegue il probe Azure endpoint di hosting e quindi verifica il timeout rispetto a IMDS, che può essere simile all'SDK hardcoded in IMDS. Per Kubernetes ovunque, incluso il servizio Azure Kubernetes, usare SignedAssertionFilePath. Per informazioni dettagliate, vedere https://aka.ms/idweb/client-credentials

Risorse aggiuntive

Per informazioni dettagliate su tutte le opzioni di configurazione delle credenziali e sul relativo utilizzo, vedere la specifica CredentialDescription nel repository microsoft-identity-abstractions-for-dotnet.

Priorità delle credenziali

Configurare più credenziali con selezione basata su priorità:

# 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

Il Microsoft Entra ID Auth SDK (sidecar) valuta le credenziali in ordine numerico (0, 1, 2 e così via) e usa le prime credenziali che eseguono correttamente l'autenticazione.

Configurazione delle API downstream

Configurare le API downstream che l'applicazione deve chiamare usando flussi di token OBO (on-behalf-of). Il Microsoft Entra ID Auth SDK (sidecar) gestisce l'acquisizione dei token e fornisce intestazioni di autenticazione per queste chiamate API. Ogni API downstream richiede un nome di configurazione univoco e parametri specifici per l'acquisizione di token e la gestione delle richieste HTTP.

Definire ogni API downstream con l'URL di base, gli ambiti obbligatori e i parametri facoltativi. L'SDK gestirà automaticamente l'acquisizione di token usando il token utente in ingresso e fornirà le intestazioni di autorizzazione appropriate per le chiamate API dell'applicazione.

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

Opzioni di acquisizione dei token

Ottimizzare il comportamento di acquisizione dei 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>"

Configurazione della richiesta HTTP firmata

Abilitare le richieste HTTP firmate per una sicurezza avanzata:

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

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

Configurazione della registrazione

Configurare i livelli di registrazione:

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

impostazioni di ASP.NET Core

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

override della configurazione Per-Request

Tutti gli endpoint di acquisizione di token accettano parametri di query per eseguire l'override della configurazione:

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

Override dell'identità dell'agente

Specificare l'identità dell'agente in fase di richiesta:

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

Regole importanti:

• AgentUsername e AgentUserId richiedono AgentIdentity
• AgentUsername e AgentUserId si escludono a vicenda

Per informazioni dettagliate sulla semantica, vedere Identità agente .

Esempio di configurazione completo

Di seguito è riportato un esempio pronto per la produzione che illustra come distribuire l'SDK con una separazione corretta di configurazione e segreti. Questo esempio illustra la configurazione di più API downstream, l'uso di Kubernetes ConfigMaps per impostazioni non sensibili, l'archiviazione sicura delle credenziali nei segreti e l'applicazione di configurazioni specifiche dell'ambiente per la distribuzione sicura.

Questo modello segue le procedure consigliate di Kubernetes separando i dati di configurazione dalle credenziali sensibili, consentendo una gestione efficace di ambienti diversi mantenendo al contempo la sicurezza.

Kubernetes ConfigMap

ConfigMap archivia le impostazioni di configurazione non sensibili per l'SDK, incluse le impostazioni Entra ID, le API downstream e i livelli di registrazione.

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"

Segreto Kubernetes

Il segreto archivia le credenziali riservate, ad esempio i segreti client, separatamente da ConfigMap.

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

Distribuzione con ConfigMap e segreto

La distribuzione monta sia ConfigMap che Secret nel contenitore SDK, assicurandosi che la configurazione e le credenziali siano separate correttamente.

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

Configurazione specifica dell'ambiente

Configurare impostazioni specifiche dell'ambiente per personalizzare la sicurezza, la registrazione e l'isolamento del tenant per gli ambienti di distribuzione. Ogni ambiente richiede approcci di configurazione diversi per bilanciare l'efficienza dello sviluppo, la convalida di staging e i requisiti di sicurezza di produzione.

Sviluppo

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

Produzione

- 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

Il Microsoft Entra ID Auth SDK (sidecar) convalida la configurazione all'avvio e registra gli errori per:

• Impostazioni obbligatorie mancanti (TenantId, ClientId)
• Configurazioni delle credenziali non valide
• Definizioni di API downstream in formato non valido
• URL o formati di ambito non validi

Controllare i log dei contenitori per i messaggi di convalida:

kubectl logs <pod-name> -c sidecar

Risoluzione dei problemi relativi alle credenziali

Le richieste raggiungono in modo imprevisto IMDS o il timeout

Sintomo: il sidecar si blocca o si verifica il timeout dell'acquisizione di un token downstream e i log mostrano le richieste all'endpoint IMDS (169.254.169.254), anche in un host non Azure.

Causa: la credenziale è configurata come SignedAssertionFromManagedIdentity. Tale tipo di origine esegue intenzionalmente il probe Azure ambienti di hosting e IMDS, che non esistono all'esterno di Azure. Si tratta di una scelta di configurazione, non di un fallback da SignedAssertionFilePath.

Risoluzione:

1. Verificare che l'oggetto effettivo SourceType sia SignedAssertionFilePath, non SignedAssertionFromManagedIdentity.
2. Verificare che nessuna variabile di ambiente o l'override di ConfigMap reintroduca SignedAssertionFromManagedIdentity.
3. Verificare che SignedAssertionFileDiskPath punti al token proiettato montato nel contenitore sidecar.
4. In kubernetes non Azure verificare che l'emittente OIDC e JWKS del cluster siano raggiungibili pubblicamente e che nell'applicazione Blueprint esista un FIC corrispondente.

Quando si segnala un problema persistente, acquisire la versione sidecar, la configurazione di runtime effettiva e i log del contenitore da una richiesta non riuscita.

Procedure consigliate

1. Usare i segreti per le credenziali: archiviare i segreti e i certificati client nei segreti kubernetes o nei Azure Key Vault. Vedere anche https://aka.ms/msidweb/client-credentials
2. Configurazione separata per ambiente: usare ConfigMaps per gestire le impostazioni specifiche dell'ambiente
3. Abilitare la registrazione appropriata: usare la registrazione di debug in fase di sviluppo, informazioni/avviso nell'ambiente di produzione
4. Configurare i controlli di integrità: verificare che gli endpoint di controllo integrità siano configurati correttamente
5. Usare l'identità del carico di lavoro per contenitori: per le distribuzioni in contenitori, preferire ID dei carichi di lavoro di Microsoft Entra con SignedAssertionFilePath sui segreti client per una sicurezza avanzata
6. Usare l'identità gestita per macchine virtuali/servizi app: per le macchine virtuali Azure e i servizi app, usare identità gestite assegnate dal sistema o dall'utente
7. Convalida in fase di distribuzione: Testare la configurazione nella gestione temporanea prima della distribuzione di produzione

Contenuti correlati

• Identità agente
• Informazioni di riferimento sugli endpoint
• Procedure consigliate per la sicurezza
• Risoluzione dei problemi