Usare i certificati con Microsoft. Identity.Web

Microsoft. Identity.Web supporta l'autenticazione basata su certificati come alternativa sicura ai segreti client per le applicazioni client riservate. I certificati offrono garanzie di sicurezza più avanzate perché usano la crittografia asimmetrica, ma solo il titolare della chiave privata può eseguire l'autenticazione e il certificato stesso può essere verificato in modo indipendente.

Questo articolo illustra come configurare le credenziali del certificato da varie origini, registrarle con l'app e gestirle nell'ambiente di produzione.

Perché usare i certificati?

Come funziona

1. Generare o ottenere un certificato X.509 con una chiave privata.
2. Registrare la chiave pubblica del certificato (o impronta) con la registrazione dell'app Microsoft Entra.
3. In fase di esecuzione, Microsoft. Identity.Web carica il certificato (inclusa la chiave privata) dall'origine configurata.
4. La libreria usa la chiave privata per firmare un'asserzione client inviata a Microsoft Entra ID per ottenere i token.

Origini certificato

Microsoft. Identity.Web supporta il caricamento di certificati da più origini:

Configura le credenziali del certificato nella matrice all'interno della sezione di configurazione ClientCertificates (o AzureAdB2C). È possibile specificare più certificati per scenari di rotazione, Microsoft. Identity.Web usa il primo certificato valido trovato.

Da Azure Key Vault (scelta consigliata)

Azure Key Vault è l'origine consigliata per i certificati nell'ambiente di produzione. Offre gestione centralizzata, controllo di accesso, audit e capacità di rotazione automatica.

Configurazione

Aggiungi la configurazione del certificato a appsettings.json:

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

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

Configurare i criteri di accesso Key Vault

L'identità dell'applicazione deve essere autorizzata a leggere i certificati dal Key Vault. Il modo in cui si concede dipende dal fatto che si utilizzi il modello di criteri di accesso al vault o il controllo degli accessi basato su ruoli di Azure (RBAC).

Opzione 1: Politica di accesso alla cassaforte

az keyvault set-policy \
  --name your-keyvault-name \
  --object-id <app-or-managed-identity-object-id> \
  --certificate-permissions get list \
  --secret-permissions get

Opzione 2: Azure RBAC

Assegnare all'identità dell'applicazione il ruolo Utente del certificato di Key Vault:

az role assignment create \
  --role "Key Vault Certificate User" \
  --assignee <app-or-managed-identity-object-id> \
  --scope /subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault-name>

Usare l'identità gestita per accedere alle Key Vault

Quando l'app viene eseguita in Azure (servizio app, Funzioni di Azure, servizio Azure Kubernetes, macchine virtuali), usare l'identità gestita per eseguire l'autenticazione per Key Vault. In questo modo si elimina la necessità di qualsiasi credenziale per accedere al vault stesso.

Identità gestita assegnata dal sistema

Se l'app dispone di un'identità gestita assegnata dal sistema abilitata, Microsoft. Identity.Web usa automaticamente DefaultAzureCredential per eseguire l'autenticazione per Key Vault. Non è necessaria alcuna configurazione aggiuntiva oltre la ClientCertificates voce:

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

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

Identità gestita assegnata dall'utente

Per un'identità gestita assegnata dall'utente, specificare il ManagedIdentityClientId nel descrittore di certificato Key Vault:

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

    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault-name.vault.azure.net",
        "KeyVaultCertificateName": "your-certificate-name",
        "ManagedIdentityClientId": "user-assigned-managed-identity-client-id"
      }
    ]
  }
}

Dall'archivio certificati (solo Windows)

In Windows è possibile caricare i certificati dall'archivio certificati Windows. Questa operazione è comune per le distribuzioni locali o ospitate in IIS.

Per identificazione personale

Usare StoreWithThumbprint per identificare il certificato in base all'impronta digitale SHA-1:

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

    "ClientCertificates": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateThumbprint": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2"
      }
    ]
  }
}

Per nome distinto

Usare StoreWithDistinguishedName per identificare il certificato in base al nome del soggetto:

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

    "ClientCertificates": [
      {
        "SourceType": "StoreWithDistinguishedName",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateDistinguishedName": "CN=MyAppCertificate"
      }
    ]
  }
}

Posizioni dell'archivio certificati

Dal percorso del file

È possibile caricare un certificato direttamente da un .pfx file (PKCS#12) su disco.

Configurazione

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

    "ClientCertificates": [
      {
        "SourceType": "Path",
        "CertificateDiskPath": "/path/to/certificate.pfx",
        "CertificatePassword": "your-certificate-password"
      }
    ]
  }
}

dotnet user-secrets set "AzureAd:ClientCertificates:0:CertificatePassword" "your-password"

export AzureAd__ClientCertificates__0__CertificatePassword="your-password"

Dal valore codificato in Base64

È possibile specificare il certificato come stringa con codifica Base64. Questo approccio è utile quando si inserisce certificati tramite variabili di ambiente, segreti Kubernetes o variabili della pipeline CI/CD.

Configurazione

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

    "ClientCertificates": [
      {
        "SourceType": "Base64Encoded",
        "Base64EncodedValue": "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg..."
      }
    ]
  }
}

Generare il valore Base64

Convertire un .pfx file in una stringa Base64:

PowerShell:

$certBytes = [System.IO.File]::ReadAllBytes("path/to/certificate.pfx")
$base64 = [System.Convert]::ToBase64String($certBytes)
$base64 | Set-Clipboard  # Copies to clipboard

Bash:

base64 -w 0 path/to/certificate.pfx

Uso con i secret di Kubernetes

Archiviare il certificato con codifica Base64 in un segreto Kubernetes ed eseguirne il mapping a una variabile di ambiente:

apiVersion: v1
kind: Secret
metadata:
  name: app-cert-secret
type: Opaque
data:
  AzureAd__ClientCertificates__0__Base64EncodedValue: <base64-encoded-pfx>

Fare riferimento al segreto nell'implementazione.

env:
  - name: AzureAd__ClientCertificates__0__SourceType
    value: "Base64Encoded"
  - name: AzureAd__ClientCertificates__0__Base64EncodedValue
    valueFrom:
      secretKeyRef:
        name: app-cert-secret
        key: AzureAd__ClientCertificates__0__Base64EncodedValue

Utilizzo nelle pipeline CI/CD

In Azure DevOps o GitHub Actions archiviare il certificato con codifica Base64 come variabile privata, quindi impostarlo come variabile di ambiente in fase di esecuzione.

Esempio di GitHub Actions:

env:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: ${{ secrets.APP_CERTIFICATE_BASE64 }}

Azure DevOps esempio:

variables:
  AzureAd__ClientCertificates__0__SourceType: "Base64Encoded"
  AzureAd__ClientCertificates__0__Base64EncodedValue: $(AppCertificateBase64)

Configurare i certificati nel codice C#

Oltre alla configurazione JSON, è possibile configurare le credenziali del certificato a livello di codice usando la classe CredentialDescription da Microsoft.Identity.Abstractions. La classe fornisce metodi helper statici per ogni tipo di origine del certificato:

Metodi di supporto

using Microsoft.Identity.Abstractions;

// From Azure Key Vault
var kvCredential = CredentialDescription.FromKeyVault(
    "https://your-keyvault-name.vault.azure.net",
    "your-certificate-name");

// From certificate store (by thumbprint)
var thumbprintCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    thumbprint: "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6A1B2");

// From certificate store (by distinguished name)
var dnCredential = CredentialDescription.FromCertificateStore(
    "CurrentUser/My",
    distinguishedName: "CN=MyAppCertificate");

// From file path
var pathCredential = CredentialDescription.FromCertificatePath(
    "/path/to/certificate.pfx",
    "your-certificate-password");

// From Base64-encoded string
var base64Credential = CredentialDescription.FromBase64String(
    "MIIKcQIBAzCCCi0GCSqGSIb3DQEHAaCCCh4Egg...");

Usare in ASP.NET Core

Passare le descrizioni delle credenziali direttamente durante la configurazione dell'autenticazione:

builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApp(options =>
    {
        options.Instance = "https://login.microsoftonline.com/";
        options.TenantId = "your-tenant-id";
        options.ClientId = "your-client-id";
        options.ClientCredentials = new[]
        {
            CredentialDescription.FromKeyVault(
                "https://your-keyvault-name.vault.azure.net",
                "your-certificate-name")
        };
    });

Creare un certificato autofirmato per lo sviluppo

Per lo sviluppo e il test locali, è possibile creare un certificato autofirmato. Non usare certificati autofirmato nell'ambiente di produzione.

Uso di PowerShell (Windows)

$cert = New-SelfSignedCertificate `
  -Subject "CN=MyDevCertificate" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable `
  -KeySpec Signature `
  -KeyLength 2048 `
  -KeyAlgorithm RSA `
  -HashAlgorithm SHA256 `
  -NotAfter (Get-Date).AddYears(2)

# Export the .pfx file (with private key)
$password = ConvertTo-SecureString -String "YourPassword123!" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\MyDevCertificate.pfx" -Password $password

# Export the .cer file (public key only — for app registration)
Export-Certificate -Cert $cert -FilePath ".\MyDevCertificate.cer"

# Display the thumbprint
Write-Host "Thumbprint: $($cert.Thumbprint)"

Uso di OpenSSL (multipiattaforma)

# Generate a self-signed certificate and private key
openssl req -x509 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -days 730 -nodes \
  -subj "/CN=MyDevCertificate"

# Package into a .pfx file
openssl pkcs12 -export \
  -out MyDevCertificate.pfx \
  -inkey key.pem -in cert.pem \
  -passout pass:YourPassword123!

# Get the thumbprint
openssl x509 -in cert.pem -noout -fingerprint -sha1

Utilizzo di .NET CLI

dotnet dev-certs https --export-path ./MyDevCertificate.pfx --password YourPassword123!

Registrare il certificato in Microsoft Entra ID

Dopo aver creato o ottenuto un certificato, è necessario registrarne la chiave pubblica con la registrazione dell'app in Microsoft Entra ID.

Uso del portale di Azure

1. Passare al portale Azure e passare a Microsoft Entra ID>Registrazioni app.
2. Selezionare l'applicazione.
3. Selezionare Certificati e segreti>Certificati>Carica certificato.
4. Caricare il .cer file o .pem contenente solo la chiave pubblica. Non caricare il .pfx file, che contiene la chiave privata.
5. Si noti il valore impronta digitale visualizzato dopo il caricamento — potrebbe essere necessario per la configurazione.

Uso di interfaccia della riga di comando di Azure

az ad app credential reset \
  --id <application-client-id> \
  --cert @/path/to/certificate.pem \
  --append

Il --append flag aggiunge il certificato senza rimuovere le credenziali esistenti.

Uso di Microsoft Graph PowerShell

$certData = [System.IO.File]::ReadAllBytes(".\MyDevCertificate.cer")
$base64Cert = [System.Convert]::ToBase64String($certData)

$keyCredential = @{
    type = "AsymmetricX509Cert"
    usage = "Verify"
    key = [System.Convert]::FromBase64String($base64Cert)
    displayName = "MyAppCertificate"
}

Update-MgApplication -ApplicationId <app-object-id> -KeyCredentials @($keyCredential)

Rotazione dei certificati

La rotazione dei certificati è la procedura di sostituzione di un certificato in scadenza con un nuovo certificato prima della scadenza, garantendo un servizio ininterrotto.

Strategia: certificati sovrapposti

L'approccio consigliato usa periodi di validità sovrapposti:

1. Generare un nuovo certificato prima della scadenza corrente(ad esempio, 30-60 giorni in anticipo).
2. Registrare il nuovo certificato nella registrazione dell'app Microsoft Entra insieme a quella esistente. Microsoft Entra ID accetta token firmati da qualsiasi certificato registrato.
3. Distribuire il nuovo certificato all'origine del certificato dell'applicazione (Key Vault, archivio certificati e così via).
4. Aggiornare la configurazione (se necessario) in modo che punti al nuovo certificato.
5. Rimuovere il certificato precedente dalla registrazione dell'app dopo aver confermato che tutte le istanze usano quella nuova.

Più certificati nella configurazione

Microsoft. Identity.Web supporta la specifica di più certificati. La libreria li prova nell'ordine e usa il primo certificato valido.

{
  "AzureAd": {
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "new-cert-2026"
      },
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://your-keyvault.vault.azure.net",
        "KeyVaultCertificateName": "current-cert-2025"
      }
    ]
  }
}

Rotazione automatica con Azure Key Vault

Azure Key Vault supporta il rinnovo automatico dei certificati. Quando si abilita la rotazione automatica:

1. Key Vault genera una nuova versione del certificato prima della scadenza.
2. Microsoft. Identity.Web seleziona automaticamente la versione più recente (al recupero del certificato successivo).
3. La versione precedente del certificato rimane valida fino alla scadenza.

Per configurare la rotazione automatica in Key Vault:

az keyvault certificate set-attributes \
  --vault-name your-keyvault-name \
  --name your-certificate-name \
  --policy @rotation-policy.json

Risoluzione dei problemi

Errori comuni

Certificato non trovato

Messaggio di errore:

System.Security.Cryptography.CryptographicException: The certificate cannot be found.

Possibili cause e soluzioni:

Accesso negato a Key Vault

Messaggio di errore:

Azure.RequestFailedException: The user, group or application '...' does not have certificates get permission on key vault '...'

Soluzioni:

• Verificare che i criteri di accesso concedano get l'autorizzazione sia per i certificati che per i segreti.
• Se si usa Azure Controllo degli Accessi in base al Ruolo (RBAC), verificare che l'identità abbia il ruolo Utente Certificate di Key Vault.
• Per Identità gestita verificare che l'identità sia abilitata e che venga usato l'ID oggetto corretto nei criteri.

Chiave privata del certificato non accessibile

Messaggio di errore:

System.Security.Cryptography.CryptographicException: Keyset does not exist.

Soluzioni:

• Su Windows/IIS, verificare che l'identità del pool di applicazioni abbia accesso in lettura alla chiave privata. Usare lo snap-in MMC Certificati per concedere l'accesso tramite Gestisci chiavi private.
• In Linux verificare che il .pfx file disponga delle autorizzazioni di file appropriate (chmod 600).
• Verificare che il certificato sia stato esportato con la chiave privata (Export-PfxCertificate o openssl pkcs12 -export).

Certificato scaduto

Messaggio di errore:

AADSTS700027: Client assertion contains an invalid signature. The key was expired.

Soluzioni:

• Controllare il periodo di validità del certificato: openssl x509 -in cert.pem -noout -dates.
• Generare un nuovo certificato e aggiornare sia la registrazione dell'app che la configurazione dell'applicazione.
• Implementare la rotazione dei certificati per evitare problemi di scadenza futuri. Vedere Rotazione dei certificati.

Password del certificato errata

Messaggio di errore:

System.Security.Cryptography.CryptographicException: The specified network password is not correct.

Soluzioni:

• Verificare che CertificatePassword corrisponda alla password usata durante l'esportazione del file .pfx.
• Se si usano variabili di ambiente, verificare la presenza di problemi di codifica (nuove righe finali, caratteri speciali).
• Esportare nuovamente il certificato con una password nota.

Elenco di controllo diagnostico

Usare questo elenco di controllo quando l'autenticazione del certificato non funziona:

• [ ] Validità del certificato : il certificato rientra nel periodo di validità? Controlla le date NotBefore e NotAfter.
• [ ] Registrazione dell'app : la chiave pubblica del certificato viene caricata nella registrazione dell'app corretta?
• [ ] Corrispondenza thumbprint : l'impronta digitale nella configurazione corrisponde al certificato nella registrazione dell'app?
• [ ] Accesso alla chiave privata : il processo dell'applicazione può leggere la chiave privata del certificato?
• [ ] Autorizzazioni del Key Vault — Per le origini Key Vault, l'identità dispone di autorizzazioni sia certificates/get che secrets/get?
• [ ] Sezione di configurazione : la configurazione del certificato è nella sezione corretta (AzureAd o AzureAdB2C)?
• [ ] Pacchetti NuGet — Microsoft.Identity.Web è aggiornato? Le versioni precedenti potrebbero non supportare determinati tipi di origine del certificato.

Abilitare la registrazione

Per ottenere informazioni di diagnostica dettagliate, abilitare la registrazione MSAL nell'applicazione:

builder.Services.AddMicrosoftIdentityWebAppAuthentication(builder.Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();

builder.Logging.AddFilter("Microsoft.Identity", LogLevel.Debug);

Esaminare i log per i messaggi relativi al caricamento dei certificati, alla creazione di asserzioni client e agli errori di acquisizione dei token.

Contenuti correlati

• Panoramica delle credenziali
• Autenticazione senza certificati - Identità gestita e Federazione dell'identità dei carichi di lavoro
• Segreti client : tipo di credenziale alternativo per le app riservate
• Decrittografia dei token : uso di certificati per la decrittografia dei token
• Registrazione e diagnostica