Configurare la decrittografia dei token in Microsoft. Identity.Web

Questa guida illustra come configurare i certificati di decrittografia dei token in Microsoft. Identity.Web in modo che l'applicazione possa ricevere e decrittografare i token crittografati emessi dal Microsoft Identity Platform.

Che cos'è la decrittografia dei token?

Per impostazione predefinita, il Microsoft Identity Platform rilascia token (token ID, token SAML) come JWT firmati ma non crittografati. Qualsiasi intermediario che intercetta un token può leggere le attestazioni contenute. Per le applicazioni che gestiscono attestazioni sensibili o operano in ambienti con requisiti di conformità rigorosi, il Microsoft Identity Platform supporta la crittografia token. Quando la crittografia dei token è abilitata, Identity Platform crittografa il payload del token usando una chiave pubblica registrata nell'applicazione e solo l'applicazione, che contiene la chiave privata corrispondente, può decrittografare e leggere il token.

Funzionamento della crittografia dei token

1. Si genera un certificato con una coppia di chiavi pubblica/privata.
2. Carica la chiave pubblica (il file .cer) nella registrazione dell'app in Microsoft Entra ID.
3. Quando il Microsoft Identity Platform rilascia un token per l'applicazione, crittografa il token usando la chiave pubblica.
4. L'applicazione usa la chiave privata per decrittografare il token prima di elaborare le attestazioni.

La crittografia utilizza uno schema a due livelli: il payload del token viene crittografato con una chiave di crittografia simmetrica del contenuto, che viene avvolta (wrappata) con la tua chiave pubblica. Microsoft Entra ID supporta algoritmi di wrapping delle chiavi RSA-OAEP e RSA-OAEP-256.

Quando è necessaria la decrittografia dei token

Configurare i certificati di decrittazione dei token quando l'applicazione:

• Riceve token SAML crittografati : applicazioni aziendali che usano l'accesso Single Sign-On basato su SAML e richiedono asserzioni SAML crittografate per motivi normativi o di conformità.
• Riceve token ID crittografati : applicazioni Web che acconsentono alla crittografia del token ID per proteggere le attestazioni sensibili (appartenenze ai gruppi, attestazioni personalizzate) dalla lettura in transito.
• Opera in ambienti a sicurezza elevata : applicazioni in scenari pubblici, finanziari o sanitari in cui la riservatezza dei token è imposto dai criteri.

Prerequisiti

Prima di configurare la decrittografia dei token, verificare quanto segue:

• Un certificato X.509 con una chiave privata — È necessario un certificato in formato .pfx (PKCS#12) o memorizzato in una posizione accessibile alla tua applicazione (Azure Key Vault, archivio certificati o file system). La chiave privata è necessaria per decrittografare i token.
• Registrazione dell'app configurata per la crittografia del token: è necessario caricare la chiave pubblica del certificato nella registrazione dell'app in Microsoft Entra ID. Vedere Registrare il certificato di decrittografia più avanti in questo articolo.
• Microsoft. Identity.Web 2.1.0 o versione successiva : la proprietà di configurazione />

Configurare la decrittografia dei token in appsettings.json

Microsoft. Identity.Web usa la matrice TokenDecryptionCredentials nella sezione di configurazione AzureAd. Questa matrice segue lo stesso formato di descrizione delle credenziali di ClientCredentials, quindi è possibile caricare i certificati di decrittografia da Azure Key Vault, dall'archivio certificati, da un percorso di file o da una stringa con codifica Base64.

Configurazione di base

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

    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "MyCertificate"
      }
    ]
  }
}

Non è necessario alcun codice aggiuntivo. Quando Microsoft. Identity.Web rileva la configurazione TokenDecryptionCredentials, carica automaticamente il certificato specificato e lo registra con il gestore di autenticazione OpenID Connect per la decrittografia del token.

Fonti di credenziali supportate

La TokenDecryptionCredentials matrice supporta gli stessi tipi di origine di ClientCredentials. La tabella seguente riepiloga ogni opzione:

Key Vault (consigliato per la produzione)

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert"
    }
  ]
}

L'identità gestita o l'entità servizio dell'applicazione devono avere autorizzazioni Get e List per i certificati Key Vault.

Archivio certificati (Windows)

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "StoreWithThumbprint",
      "CertificateStorePath": "CurrentUser/My",
      "CertificateThumbprint": "A1B2C3D4E5F6..."
    }
  ]
}

Percorso del file

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Path",
      "CertificateDiskPath": "/var/ssl/private/decrypt-cert.pfx",
      "CertificatePassword": "your-certificate-password"
    }
  ]
}

Codifica Base64

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "Base64Encoded",
      "Base64EncodedValue": "MIIJ..."
    }
  ]
}

Questa opzione è utile quando si inserisce il certificato tramite una variabile di ambiente o un segreto della pipeline CI/CD.

Più certificati di decrittografia

È possibile specificare più certificati nella TokenDecryptionCredentials matrice. Microsoft. Identity.Web prova ogni certificato in ordine fino a quando non ne viene decrittografato correttamente uno. Questa funzionalità è essenziale per la rotazione dei certificati (vedere Rotazione dei certificati).

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-New"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-Old"
    }
  ]
}

Registrare il certificato di decrittografia in Microsoft Entra ID

Affinché il Microsoft Identity Platform crittografi i token per l'applicazione, è necessario caricare la chiave pubblica del certificato nella registrazione dell'app:

1. Accedere al Interfaccia di amministrazione di Microsoft Entra.
2. Passare a Identity>Applications>Registrazioni app e selezionare l'applicazione.
3. Selezionare Certificati e segreti>Certificati>Carica certificato.
4. Caricare il .cer file (solo chiave pubblica) del certificato di decrittografia.
5. Dopo il caricamento, prendere nota del valore impronta digitale, che deve corrispondere al certificato usato dall'applicazione.

Abilitare la crittografia dei token per l'applicazione

Dopo aver caricato il certificato, è necessario configurare l'applicazione per ricevere token crittografati. Questa configurazione è attualmente disponibile tramite Microsoft API Graph o PowerShell:

Using Microsoft Graph PowerShell:

# Get the key credential ID of the uploaded certificate
$app = Get-MgApplication -Filter "appId eq 'your-client-id'"
$keyId = ($app.KeyCredentials | Where-Object { $_.DisplayName -eq "CN=TokenDecryptionCert" }).KeyId

# Set the token encryption key ID
Update-MgApplication -ApplicationId $app.Id -BodyParameter @{
    "tokenEncryptionKeyId" = $keyId
}

Rotazione dei certificati per la decrittografia dei token

La rotazione dei certificati per la decrittografia dei token richiede un approccio attento e in più fasi per evitare tempi di inattività:

Passaggi di rotazione

1. Generare un nuovo certificato : creare un nuovo certificato X.509 con una chiave privata.
2. Aggiungere il nuovo certificato alla configurazione dell'applicazione : aggiungere il nuovo certificato alla matrice insieme al TokenDecryptionCredentials certificato esistente. Posizionare il nuovo certificato prima nella matrice.
3. Carica la nuova chiave pubblica — Carica il file del nuovo certificato nella registrazione dell'app in Microsoft Entra ID.
4. Distribuire l'applicazione : distribuire la configurazione aggiornata in modo che l'applicazione possa decrittografare i token con entrambi i certificati.
5. Cambiare la chiave di crittografia attiva — aggiornare l'oggetto dell'applicazione tokenEncryptionKeyId in modo che punti al nuovo certificato keyId.
6. Verifica : verificare che l'applicazione decrittografi correttamente i token crittografati con il nuovo certificato.
7. Rimuovere il certificato precedente : dopo un periodo di tolleranza (almeno 24 ore per consentire la scadenza dei token memorizzati nella cache), rimuovere il certificato precedente dalla registrazione dell'app e dalla configurazione dell'applicazione.

Configurazione durante la rotazione

Durante la finestra di rotazione, l'oggetto TokenDecryptionCredentials deve contenere entrambi i certificati:

{
  "TokenDecryptionCredentials": [
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2026"
    },
    {
      "SourceType": "KeyVault",
      "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
      "KeyVaultCertificateName": "TokenDecryptionCert-2025"
    }
  ]
}

Risoluzione dei problemi

Errori di decrittografia dei token

Sintomo: L'applicazione genera o SecurityTokenDecryptionFailedException restituisce un errore 401/500 durante l'elaborazione dei token.

Cause comuni:

Chiave privata mancante

Sintomo:CryptographicException: The certificate key is not accessible o InvalidOperationException: Certificate does not have a private key.

Cause e soluzioni:

• Certificato esportato senza chiave privata : esportare nuovamente il certificato in .pfx formato e assicurarsi di includere la chiave privata durante l'esportazione.
• Politica di accesso di Key Vault - Quando si usa Azure Key Vault, verificare che l'identità dell'applicazione disponga dell'autorizzazione Get su Certificates e Secrets. La chiave privata viene archiviata come segreto in Key Vault.
• Autorizzazioni dello store dei certificati — Su Windows, verificare che l'identità del pool di applicazioni o l'account del servizio abbia diritti di lettura alla chiave privata. Usare l'opzione Gestisci chiavi private nello snap-in MMC dell'archivio certificati.

Incompatibilità dell'algoritmo

Sintomo:SecurityTokenDecryptionFailedException con un messaggio che indica un algoritmo non supportato.

Cause e soluzioni:

• Tipo di chiave non supportato: Microsoft Entra ID supporta i certificati RSA per la crittografia dei token. Assicurarsi che il certificato usi una coppia di chiavi RSA (non EC/ECDSA).
• Dimensioni della chiave troppo piccole : usare una dimensione della chiave di almeno 2048 bit. Le chiavi RSA inferiori a 2048 bit potrebbero essere rifiutate.
• Algorithm non supportato: Microsoft Entra ID usa RSA-OAEP per il wrapping delle chiavi. Verificare che il certificato e l'infrastruttura dell'applicazione supportino questo algoritmo.

Token crittografati non emessi

Sintomo: L'applicazione riceve token non crittografati anche se è stata configurata la decrittografia dei token.

Cause e soluzioni:

• tokenEncryptionKeyId non configurato : è necessario impostare in modo esplicito questa proprietà tramite Microsoft Graph. Il caricamento del certificato da solo non è sufficiente.
• Certificato scaduto nella registrazione dell'app : verificare che il certificato caricato nella registrazione dell'app non sia scaduto. Caricare un nuovo certificato, se necessario.
• I token di accesso non sono crittografati : la crittografia dei token si applica solo ai token ID e ai token SAML . I token di accesso da Microsoft Entra ID non vengono crittografati con il certificato.

Decrittografia dei token e credenziali client

Le credenziali di decrittografia dei token servono a uno scopo diverso dalle credenziali client. L'applicazione può usare lo stesso certificato per entrambi o usare certificati separati:

{
  "AzureAd": {
    "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ],
    "TokenDecryptionCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://mykeyvault.vault.azure.net",
        "KeyVaultCertificateName": "AppAuthCert"
      }
    ]
  }
}

Procedure consigliate

Use Azure Key Vault : archiviare i certificati di decrittografia in Key Vault per la gestione centralizzata, il controllo di accesso e la registrazione di controllo.

Pianificare la rotazione : è sempre disponibile una strategia di rotazione prima di distribuire la crittografia dei token. Includere sia i certificati nuovi che quelli precedenti durante la finestra di rotazione.

Usare chiavi RSA a 2048 bit o di dimensioni maggiori : assicurarsi che i certificati usino chiavi RSA di almeno 2048 bit per una sicurezza adeguata.

Monitorare la scadenza del certificato : configurare gli avvisi in Azure Key Vault o nel sistema di monitoraggio per ricevere una notifica prima della scadenza dei certificati.

Testare in un ambiente di gestione temporanea : verificare la crittografia e la decrittografia dei token in un ambiente non di produzione prima di abilitarla nell'ambiente di produzione.

Non archiviare chiavi private nel controllo del codice sorgente: usare Key Vault, variabili di ambiente o un gestore segreti per l'archiviazione dei certificati.

Non rimuovere il certificato precedente troppo presto durante la rotazione : mantenere attivi entrambi i certificati per almeno 24 ore per consentire la scadenza dei token memorizzati nella cache.

Non abilitare la crittografia dei token senza un certificato di decrittografia configurato : l'applicazione non riuscirà a elaborare i token se non riesce a decrittografarli.

Contenuti correlati

• Panoramica delle credenziali
• Panoramica della cache dei token
• Autorizzazione nelle API Web
• Credenziali del certificato