Usare i segreti client con Microsoft Identity.Web

Un segreto client è un valore stringa usato dall'applicazione per dimostrare la propria identità quando si richiedono token dal Microsoft Identity Platform. Microsoft. Identity.Web supporta i segreti client come uno dei diversi tipi di credenziali per le applicazioni client riservate.

Informazioni generali

Le applicazioni client riservate necessitano di credenziali per l'autenticazione con il Microsoft Identity Platform. Microsoft. Identity.Web supporta i tipi di credenziali seguenti tramite la sezione di configurazione ClientCredentials:

I segreti client sono stringhe semplici registrate nell'app in Microsoft Entra ID. Anche se sono il tipo di credenziale più semplice da configurare, presentano anche limitazioni di sicurezza significative:

• Possono essere accidentalmente esposti nel codice sorgente, nei log o nei file di configurazione.
• Hanno una data di scadenza e devono essere ruotate manualmente.
• Non forniscono alcuna prova crittografica dell'identità del chiamante oltre il possesso del segreto.

Configurare un segreto del client nel file appsettings.json

Per configurare un segreto client, aggiungere una ClientCredentials matrice alla AzureAd sezione del appsettings.json file:

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret",
        "ClientSecret": "YOUR_SECRET_VALUE"
      }
    ]
  }
}

La ClientCredentials matrice supporta più voci. Microsoft.Identity.Web prova ciascuna credenziale in ordine finché una ha successo, il che è utile per gli scenari di rotazione dei segreti.

Archiviazione sicura per lo sviluppo

.NET segreti dell'utente

L'approccio consigliato per l'archiviazione dei segreti durante lo sviluppo locale è lo strumento Secret Manager. I segreti utente archiviano i dati sensibili all'esterno dell'albero del progetto, impedendo il commit accidentale nel controllo del codice sorgente.

1. Inizializzare i segreti utente per il progetto:

   dotnet user-secrets init
   

2. Configurare il valore della chiave segreta del cliente:

   dotnet user-secrets set "AzureAd:ClientCredentials:0:ClientSecret" "your-secret-value"
   

3. Verificare che il segreto sia stato archiviato:

   dotnet user-secrets list
   

I segreti utente vengono caricati automaticamente nell'ambiente Development quando si usa WebApplication.CreateBuilder() o Host.CreateDefaultBuilder().

Il tuo appsettings.json dovrebbe contenere la struttura senza il valore effettivo del segreto.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "YOUR_TENANT_ID",
    "ClientId": "YOUR_CLIENT_ID",
    "ClientCredentials": [
      {
        "SourceType": "ClientSecret"
      }
    ]
  }
}

Variabili di ambiente

È anche possibile usare le variabili di ambiente per fornire il segreto client. La configurazione di .NET esegue automaticamente la mappatura delle variabili di ambiente con il separatore __ (doppio carattere di sottolineatura) nella gerarchia di configurazione.

$env:AzureAd__ClientCredentials__0__ClientSecret = "your-secret-value"

export AzureAd__ClientCredentials__0__ClientSecret="your-secret-value"

Le variabili di ambiente hanno la precedenza sui valori in appsettings.json, quindi il valore del segreto nel file di configurazione può essere vuoto o omesso.

Archiviazione sicura per ambienti più elevati

Per la gestione temporanea, il controllo di qualità o qualsiasi ambiente condiviso, usare Azure Key Vault come origine di configurazione. Questo approccio mantiene i segreti dai file di configurazione e dalle variabili di ambiente, fornendo al tempo stesso funzionalità di controllo, criteri di accesso e rotazione automatica.

Aggiungere Azure Key Vault come origine di configurazione

1. Installare il pacchetto NuGet necessario:

   dotnet add package Azure.Extensions.AspNetCore.Configuration.Secrets
   

2. Archiviare il segreto client in Azure Key Vault con un nome mappato al percorso di configurazione. Usare -- (trattino doppio) come separatore:

   az keyvault secret set \
     --vault-name "your-keyvault-name" \
     --name "AzureAd--ClientCredentials--0--ClientSecret" \
     --value "your-secret-value"
   

3. Aggiungere Key Vault come origine di configurazione in Program.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Configuration.AddAzureKeyVault(
       new Uri("https://your-keyvault-name.vault.azure.net/"),
       new DefaultAzureCredential());
   

Il nome del segreto di Key Vault AzureAd--ClientCredentials--0--ClientSecret mappa automaticamente al percorso di configurazione AzureAd:ClientCredentials:0:ClientSecret.

Creare un segreto client nel portale di Azure

Seguire questa procedura per registrare un segreto client per l'applicazione in Microsoft Entra ID:

1. Accedere al Interfaccia di amministrazione di Microsoft Entra.
2. Passare a Identity>Applications>Registrazioni delle app.
3. Selezionare l'applicazione dall'elenco.
4. Nel menu a sinistra selezionare Certificati e segreti.
5. Selezionare la scheda Segreti client .
6. Selezionare Nuova chiave segreta del client.
7. Nel riquadro Aggiungi un segreto client :
   • Immettere una descrizione per il segreto, ad esempio "Segreto di sviluppo".
   • Selezionare una durata di scadenza . Le opzioni disponibili includono 180 giorni, 365 giorni, 730 giorni o una data personalizzata.
   • Seleziona Aggiungi.
8. Copia il valore segreto immediatamente. Il valore viene visualizzato una sola volta e non può essere recuperato dopo la navigazione dalla pagina.

Scadenza e rotazione delle credenziali riservate

I segreti client hanno una durata massima e scadono alla data specificata durante la creazione. Pianificare la rotazione dei segreti per evitare interruzioni dell'applicazione.

Monitorare la scadenza

• Controllare la colonna Scadenza nella pagina Certificati e segreti della registrazione dell'app.
• Configurare Microsoft Entra raccomandazioni per ricevere avvisi prima della scadenza delle credenziali.

Strategia di rotazione

Usare l'array ClientCredentials per supportare la rotazione senza tempi di inattività.

1. Creare un nuovo segreto client nel portale di Azure.

2. Aggiungere il nuovo segreto come voce aggiuntiva nella ClientCredentials matrice:

   {
     "AzureAd": {
       "ClientCredentials": [
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[NEW_SECRET_REFERENCE]"
         },
         {
           "SourceType": "ClientSecret",
           "ClientSecret": "[OLD_SECRET_REFERENCE]"
         }
       ]
     }
   }
   

3. Distribuire la configurazione aggiornata. Microsoft.Identity.Web prova la prima credenziale e passa alla seconda se la prima fallisce.

4. Dopo aver confermato il funzionamento del nuovo segreto, rimuovere il segreto precedente dalla configurazione e dal portale di Azure.

Migrare alle credenziali di produzione

Prima di eseguire la distribuzione nell'ambiente di produzione, eseguire la migrazione dai segreti client a un tipo di credenziale più sicuro:

Autenticazione basata su certificati

I certificati forniscono la prova crittografica dell'identità e sono il tipo di credenziale consigliato per l'ambiente di produzione:

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

Per i passaggi dettagliati, vedere Usare i certificati con Microsoft. Identity.Web.

Identità gestita (senza certificato)

Per le applicazioni ospitate in Azure, le identità gestite eliminano la necessità di gestire completamente le credenziali:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "SignedAssertionFromManagedIdentity",
        "ManagedIdentityClientId": "YOUR_MANAGED_IDENTITY_CLIENT_ID"
      }
    ]
  }
}

Per i passaggi dettagliati, vedere Autenticazione senza certificati con Microsoft. Identity.Web.

Elenco di controllo per la migrazione

• [ ] Generare o effettuare il provisioning delle nuove credenziali (certificato o identità gestita).
• [ ] Aggiornare la configurazione dell'applicazione per usare il nuovo tipo di credenziale.
• [ ] Testare le nuove credenziali in un ambiente di staging.
• [ ] Distribuire nell'ambiente di produzione.
• [ ] Rimuovere il segreto client precedente dal portale di Azure.
• [ ] Verificare che l'applicazione funzioni correttamente senza il segreto precedente.

Errori comuni e anti-pattern di sicurezza

Evitare questi errori comuni quando si lavora con i segreti client:

Risoluzione dei problemi

Segreto del client non valido

Errore:AADSTS7000215: Invalid client secret provided.

Possibili cause:

• Il valore del segreto è stato copiato in modo non corretto. I valori dei segreti possono contenere caratteri speciali che vengono troncati durante le operazioni di copia/incolla.
• Il segreto è stato creato per una registrazione di app diversa da quella configurata in ClientId.
• Il percorso di configurazione non è corretto e il valore del segreto non viene letto dall'applicazione.

Risoluzione:

1. Creare un nuovo segreto del client nel portale di Azure e copiare attentamente il valore completo.

2. Verificare che ClientId e TenantId nella configurazione corrispondano alla registrazione dell'app in cui è stato creato il segreto.

3. Aggiungere un punto di interruzione o un'istruzione di log per verificare che la configurazione venga caricata correttamente:

   // For debugging only — remove before committing
   var config = builder.Configuration.GetSection("AzureAd:ClientCredentials:0:ClientSecret").Value;
   Console.WriteLine($"Secret loaded: {!string.IsNullOrEmpty(config)}");
   

Codice segreto del client scaduto

Errore:AADSTS7000222: The provided client secret keys for app '{app-id}' are expired.

Risoluzione:

1. Passare alla registrazione dell'app nel Interfaccia di amministrazione di Microsoft Entra.
2. Controllare la data di scadenza in Certificati e segreti>Client secrets.
3. Creare un nuovo segreto e aggiornare la configurazione dell'applicazione.
4. Eliminare il segreto scaduto dal portale.

Segreto non trovato nella configurazione

Sintomo: L'applicazione genera un'eccezione NullReferenceException o non riesce a eseguire l'autenticazione perché il valore del segreto è null.

Possibili cause:

• I segreti utente non vengono inizializzati per il progetto.
• Il nome della variabile di ambiente non corrisponde al percorso di configurazione previsto.
• Key Vault non è configurato come origine di configurazione.
• L'applicazione è in esecuzione in un ambiente non di sviluppo in cui i segreti utente non vengono caricati.

Risoluzione:

1. Verificare che i segreti utente siano inizializzati controllando la presenza di un UserSecretsId nel file .csproj.
2. Verificare che il segreto sia impostato eseguendo dotnet user-secrets list.
3. Verificare che il percorso di configurazione corrisponda esattamente a : AzureAd:ClientCredentials:0:ClientSecret.
4. Se è in esecuzione all'esterno dell'ambiente di sviluppo, verificare che sia disponibile l'origine di configurazione appropriata (variabile di ambiente o Key Vault).

Contenuti correlati

• Certificates con Microsoft.Identity.Web
• Autenticazione senza certificati
• Panoramica della cache dei token
• Archiviazione sicura dei segreti dell'app in fase di sviluppo in ASP.NET Core
• Provider di configurazione di Azure Key Vault in ASP.NET Core