Informazioni di riferimento sulla configurazione: Microsoft Entra SDK per le impostazioni dell'ID agente

Questa guida fornisce opzioni di configurazione per Microsoft Entra SDK per AgentID, 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

L'SDK di Microsoft Entra per l'ID agente viene configurato usando le origini di configurazione seguenti ASP.NET Core convenzioni. 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 SDK per le distribuzioni di ID agente 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

L'SDK di Microsoft Entra per l'ID agente 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:

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 per i contenitori (scelta consigliata per il servizio Azure Kubernetes)

Questa configurazione configura Entra ID'autenticazione usando ID dei carichi di lavoro di Microsoft Entra per le distribuzioni in contenitori.This configuration set up Entra ID authentication using ID dei carichi di lavoro di Microsoft Entra for containerized deployments (AKS). Questo è l'approccio consigliato per gli scenari basati su contenitori perché usa la proiezione di token basata su file.

- name: AzureAd__ClientCredentials__0__SourceType
  value: "SignedAssertionFilePath"

Note: il percorso del file del token /var/run/secrets/azure/tokens/azure-identity-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à 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 per gli ambienti in contenitori (Kubernetes, servizio Azure Kubernetes, Docker). Per il servizio Azure Kubernetes, usare SignedAssertionFilePath come illustrato in precedenza. Per Kubernetes e Docker, usare i certificati client. 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

L'SDK Microsoft Entra per l'ID agente 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). L'SDK Microsoft Entra per l'ID agente 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

L'SDK di Microsoft Entra per l'ID agente 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

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