Panoramica delle credenziali per Microsoft. Identity.Web

Quando l'applicazione esegue l'autenticazione con il Microsoft Identity Platform, presenta una credenziale per dimostrare la propria identità. Microsoft. Identity.Web supporta diversi tipi di credenziali, ognuno adatto a diversi ambienti e requisiti di sicurezza.

Questo articolo illustra i tipi di credenziali disponibili, sceglierne uno appropriato per lo scenario e configurare le credenziali nell'applicazione.

Perché la scelta delle credenziali è importante

Le credenziali usate dall'applicazione influiscono direttamente sul comportamento di sicurezza, sul sovraccarico operativo e sulla flessibilità di distribuzione. Una credenziale scelta in modo non appropriato può esporre segreti, richiedere rotazione manuale o limitare la posizione in cui l'applicazione può essere eseguita.

Microsoft. Identity.Web offre un modello di configurazione unificato che consente di:

• Specificare più credenziali con ripristino automatico.
• Modificare i tipi di credenziali senza modificare il codice dell'applicazione.
• Usare credenziali diverse per ambiente (sviluppo, gestione temporanea, produzione).

Tipi di credenziali supportati

Microsoft. Identity.Web supporta tre categorie di credenziali per le applicazioni client riservate:

Credenziali senza certificati (credenziali di identità federate e identità gestita)

Le credenziali senza certificati utilizzano l'Azure Managed Identity combinata con le Federated Identity Credentials (FIC) per autenticare la tua applicazione senza gestire segreti o certificati. Azure gestisce interamente il ciclo di vita delle credenziali.

Come funziona: L'applicazione usa l'identità gestita per ottenere un token, che l'Microsoft Identity Platform accetta come prova dell'identità dell'applicazione tramite un trust federativo preconfigurato.

Ideale per: carichi di lavoro di produzione in esecuzione su Azure.

Altre informazioni sull'autenticazione senza certificato

Attestati

I certificati forniscono l'autenticazione basata su chiave asimmetrica avanzata. L'applicazione dimostra la propria identità firmando un'asserzione con la chiave privata del certificato. Microsoft. Identity.Web può caricare i certificati da più origini:

• Azure Key Vault - Archiviazione centralizzata e gestita dei certificati con criteri di accesso.
• Certificate Store - archivio certificati di Windows (CurrentUser o LocalMachine).
• Percorso file : file del certificato su disco (formato pfx).
• Codifica Base64 : certificato incorporato direttamente nella configurazione.

Ideale per: Carichi di lavoro di produzione in cui le credenziali senza certificato non sono disponibili o ambienti ibridi.

Altre informazioni sulle credenziali del certificato

Segreti client

I segreti client sono stringhe condivise presentate dall'applicazione al Microsoft Identity Platform. Sono il tipo di credenziale più semplice da configurare, ma offrono la sicurezza più debole.

Ideale per: Solo sviluppo e test locali.

Altre informazioni sui segreti client

Scegliere il tipo di credenziale corretto

Usare l'albero delle decisioni seguente per determinare il tipo di credenziale appropriato per lo scenario in uso.

Is your application running on Azure?
├── Yes
│   ├── Can you use Managed Identity?
│   │   ├── Yes → Use certificateless credentials (recommended)
│   │   └── No → Use certificates from Azure Key Vault
└── No
    ├── Is this a production environment?
    │   ├── Yes → Use certificates (Key Vault, Certificate Store, or file path)
    │   └── No → Use client secrets for development/testing

Linee guida generali

• Preferisci sempre le credenziali senza certificati quando la tua applicazione viene eseguita in Azure. Eliminano completamente la gestione delle credenziali.
• Usare i certificati quando le credenziali senza certificato non sono disponibili. Archiviarli in Azure Key Vault quando possibile.
• Limitare i segreti client agli ambienti di sviluppo. Non usare mai segreti client nelle distribuzioni di produzione.

Confrontare i tipi di credenziali

La tabella seguente riepiloga le differenze principali tra i tipi di credenziali:

Configurare le credenziali in appsettings.json

Microsoft. Identity.Web usa una matrice ClientCredentials nella configurazione per specificare una o più credenziali. Ogni voce dell'array include una SourceType proprietà che indica da dove proviene la credenziale.

Struttura di configurazione

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",

    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Valori SourceType

La proprietà SourceType corrisponde all'enumerazione CredentialSource e determina la modalità di Microsoft. Identity.Web carica le credenziali:

Esempi di credenziali per tipo

Senza certificati (identità gestita)

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Per l'identità gestita assegnata dal sistema, omettere la ManagedIdentityClientId proprietà :

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity"
      }
    ]
  }
}

Certificato da Azure Key Vault

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      }
    ]
  }
}

È anche possibile usare il CredentialDescription metodo helper in C#:

var credential = CredentialDescription.FromKeyVault(
    "https://your-keyvault.vault.azure.net",
    "your-certificate-name");

Certificato dall'archivio certificati

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateThumbprint": "ABC123DEF456...",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

È anche possibile usare un nome distinto, che semplifica la rotazione dei certificati perché il nuovo certificato viene selezionato automaticamente:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateDistinguishedName": "CN=YourAppCertificate",
        "CertificateStorePath": "CurrentUser/My"
      }
    ]
  }
}

In C# usare il metodo helper:

// By thumbprint
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "ABC123DEF456...");

// By distinguished name (recommended for rotation)
var credential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=YourAppCertificate");

Certificato dal percorso del file

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/var/certs/app-cert.pfx",
        "CertificatePassword": "certificate-password"
      }
    ]
  }
}

Certificato con codifica Base64

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0..."
      }
    ]
  }
}

Segreto del cliente

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "your-client-secret"
      }
    ]
  }
}

Usare più credenziali con meccanismo di ripiego

È possibile specificare più credenziali nella ClientCredentials matrice. Microsoft.Identity.Web tenta di usarli in ordine e passa alla credenziale successiva se quella corrente non funziona. Questo modello è utile per le applicazioni eseguite in più ambienti.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "your-tenant-id",
    "ClientId": "your-client-id",
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "your-managed-identity-client-id"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name"
      },
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "development-only-secret"
      }
    ]
  }
}

In questo esempio:

1. L'applicazione tenta prima di tutto l'autenticazione senza certificati con identità gestita (funziona su Azure).
2. Se l'identità gestita non è disponibile, si passa a un certificato da Key Vault.
3. Come ultima risorsa, utilizza un segreto del client (per lo sviluppo locale).

Questo approccio consente di usare lo stesso file di configurazione in ambienti senza modifiche al codice.

Configurare le credenziali nel codice

È anche possibile configurare le credenziali a livello di codice in Program.cs o Startup.cs:

using Microsoft.Identity.Web;

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", builder.Configuration.GetSection("MyApi"))
    .AddDistributedTokenCaches();

// Or configure credentials programmatically
builder.Services.Configure<MicrosoftIdentityOptions>(options =>
{
    options.ClientCredentials = new[]
    {
        new CredentialDescription
        {
            SourceType = CredentialSource.SignedAssertionFromManagedIdentity,
            ManagedIdentityClientId = "your-managed-identity-client-id"
        }
    };
});

Credenziali di decrittografia dei token

Oltre alle credenziali client usate per l'autenticazione, Microsoft. Identity.Web supporta la configurazione delle credenziali per la decrittografia dei token. Le credenziali di decrittografia dei token vengono usate quando l'applicazione riceve token crittografati e deve decrittografarli.

Le credenziali di decrittografia dei token usano gli stessi valori e gli stessi SourceType modelli di configurazione delle credenziali client, ma vengono specificati nella TokenDecryptionCredentials matrice:

{
  "AzureAd": {
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "token-decryption-cert"
      }
    ]
  }
}

Altre informazioni sulla decrittografia dei token

Procedure consigliate

Preferisce le credenziali senza certificato nell'ambiente di produzione. Le credenziali senza certificati eliminano il rischio di esposizione delle informazioni riservate e rimuovono il costo della rotazione. Usarli ogni volta che l'applicazione viene eseguita su Azure risorse di calcolo che supportano l'identità gestita.

Usare il fallback delle credenziali per la portabilità. Configurare più credenziali in ordine di priorità in modo che l'applicazione funzioni nello sviluppo, nella gestione temporanea e nell'ambiente di produzione senza modifiche al codice.

Non usare mai segreti client nell'ambiente di produzione. I segreti client sono facili da perdere tramite log, file di configurazione o controllo del codice sorgente. Usare invece certificati o credenziali senza certificato.

Archiviare valori sensibili all'esterno dei file di configurazione. Usare Azure Key Vault, variabili di ambiente o ASP.NET Core Secret Manager per archiviare le password dei certificati e i segreti client. Non eseguire il commit dei valori sensibili nel controllo del codice sorgente.

Ruotare i certificati prima della scadenza. Configurare il monitoraggio per le date di scadenza del certificato e stabilire un processo di rotazione. Azure Key Vault può automatizzare il rinnovo del certificato.

Usare Azure Key Vault per l'archiviazione dei certificati. Key Vault offre gestione centralizzata, criteri di accesso, registrazione di controllo e rotazione automatica per i certificati.

Contenuti correlati

• Autenticazione senza certificati
• Credenziali del certificato
• Decrittografia dei token
• Segreti del client