Rollover della chiave di firma in Microsoft Identity Platform

Articolo
10/24/2023

Questo articolo illustra cosa è necessario conoscere sulle chiavi pubbliche usate da Microsoft Identity Platform per firmare i token di sicurezza. È importante notare che questi tasti vengono distribuiti periodicamente e, in caso di emergenza, potrebbero essere distribuiti immediatamente. Tutte le applicazioni che usano Microsoft Identity Platform devono essere in grado di gestire a livello di codice il processo di rollover delle chiavi. Si apprenderà come funzionano le chiavi, come valutare l'impatto del rollover nell'applicazione e come aggiornare l'applicazione o stabilire un processo di rollover manuale periodico per gestire il rollover delle chiavi, se necessario.

Panoramica delle chiavi di firma in Microsoft Identity Platform

Microsoft Identity Platform usa la crittografia a chiave pubblica basata su standard di settore per stabilire una relazione di trust tra se stessa e le applicazioni che lo usano. In termini pratici, questa operazione funziona nel modo seguente: Microsoft Identity Platform usa una chiave di firma costituita da una coppia di chiavi pubblica e privata. Quando un utente accede a un'applicazione che usa Microsoft Identity Platform per l'autenticazione, Microsoft Identity Platform crea un token di sicurezza che contiene informazioni sull'utente. Questo token viene firmato da Microsoft Identity Platform usando la chiave privata prima che venga inviato all'applicazione. Per verificare che il token sia valido e originato da Microsoft Identity Platform, l'applicazione deve convalidare la firma del token usando le chiavi pubbliche esposte da Microsoft Identity Platform contenute nel documento di individuazione openID Connessione del tenant o nel documento dei metadati di federazione SAML/WS-Fed.

Ai fini della sicurezza, la chiave di firma di Microsoft Identity Platform viene eseguita periodicamente e, in caso di emergenza, potrebbe essere eseguito immediatamente il roll over. Non esiste alcun tempo impostato o garantito tra questi rollback delle chiavi: qualsiasi applicazione che si integra con Microsoft Identity Platform deve essere preparata per gestire un evento di rollover delle chiavi indipendentemente dalla frequenza con cui può verificarsi. Se l'applicazione non gestisce gli aggiornamenti improvvisi e tenta di usare una chiave scaduta per verificare la firma in un token, l'applicazione rifiuta erroneamente il token. Il controllo ogni 24 ore per gli aggiornamenti è una procedura consigliata, con aggiornamenti immediati (una volta ogni cinque minuti al massimo) del documento della chiave se viene rilevato un token che non convalida con le chiavi nella cache dell'applicazione.

È sempre disponibile più di una chiave valida nel documento di individuazione Connessione OpenID e nel documento dei metadati della federazione. L'applicazione deve essere pronta a usare qualsiasi chiave e tutte le chiavi specificate nel documento, poiché una chiave potrebbe essere implementata a breve, un'altra potrebbe essere la sostituzione e così via. Il numero di chiavi presenti può cambiare nel tempo in base all'architettura interna di Microsoft Identity Platform perché supportiamo nuove piattaforme, nuovi cloud o nuovi protocolli di autenticazione. Né l'ordine delle chiavi nella risposta JSON né l'ordine in cui sono stati esposti devono essere considerati significativi per l'app.

Le applicazioni che supportano solo una sola chiave di firma o quelle che richiedono aggiornamenti manuali alle chiavi di firma sono intrinsecamente meno sicure e meno affidabili. Devono essere aggiornati per usare librerie standard per assicurarsi che usino sempre chiavi di firma aggiornate, tra le altre procedure consigliate.

Come valutare se l'applicazione sarà interessata e come intervenire

Il modo in cui l'applicazione gestisce il rollover della chiave dipende da variabili come il tipo di applicazione o la libreria e il protocollo di identità usati. Le sezioni seguenti valutano se i tipi di applicazioni più comuni sono interessati dal rollover della chiave e offrono indicazioni su come aggiornare l'applicazione per supportare il rollover automatico o aggiornare la chiave manualmente.

Applicazioni client native che accedono alle risorse
API / applicazioni Web che accedono alle risorse
API / applicazioni Web che proteggono le risorse e sono state compilate con i servizi app di Azure
Applicazioni Web/API che proteggono le risorse usando ASP.NET middleware OWIN OpenID Connessione, WS-Fed o WindowsAzureActiveDirectoryBearerAuthentication
Applicazioni Web/API che proteggono le risorse usando ASP.NET middleware Core OpenID Connessione o JwtBearerAuthentication
Applicazioni Web/API che proteggono le risorse usando Node.js passport-azure-ad modulo
Applicazioni Web/API che proteggono le risorse e create con Visual Studio 2015 o versione successiva
Applicazioni Web che proteggono le risorse e sono state create con Visual Studio 2013
API Web che proteggono le risorse e sono state create con Visual Studio 2013
Applicazioni Web che proteggono le risorse e sono state create con Visual Studio 2012
API / applicazioni Web che proteggono le risorse usando qualsiasi altra libreria o con implementazione manuale di qualsiasi protocollo supportato

Queste indicazioni non sono valide per:

Le applicazioni aggiunte da Microsoft Entra Application Gallery (incluso Custom) includono indicazioni separate relative alle chiavi di firma. Altre informazioni.
Applicazioni locali pubblicate tramite il proxy di applicazione, che non prevedono le chiavi di firma.

Applicazioni client native che accedono alle risorse

Le applicazioni che accedono solo alle risorse (ad esempio, Microsoft Graph, KeyVault, API Outlook e altre API Microsoft) ottengono solo un token e lo passano al proprietario della risorsa. Dato che non proteggono alcuna risorsa, non controllano il token e pertanto non devono assicurarsi che sia firmato correttamente.

Le applicazioni client native, sia per desktop che per dispositivi mobili, rientrano in questa categoria e quindi non sono interessate dal rollover.

API / applicazioni Web che accedono alle risorse

Le applicazioni che accedono solo alle risorse (ad esempio Microsoft Graph, KeyVault, API Outlook e altre API Microsoft) ottengono solo un token e lo passano al proprietario della risorsa. Dato che non proteggono alcuna risorsa, non controllano il token e pertanto non devono assicurarsi che sia firmato correttamente.

Le applicazioni Web e le API Web che usano il flusso solo app (credenziali client/certificato client) per richiedere i token rientrano in questa categoria e pertanto non sono interessati dal rollover.

API / applicazioni Web che proteggono le risorse e sono state compilate con i servizi app di Azure

La funzionalità di autenticazione / autorizzazione (EasyAuth) dei servizi app di Azure ha già la logica necessaria per gestire automaticamente il rollover della chiave.

Applicazioni Web/API che proteggono le risorse usando ASP.NET middleware OWIN OpenID Connessione, WS-Fed o WindowsAzureActiveDirectoryBearerAuthentication

Se l'applicazione usa il ASP.NET middleware OWIN OpenID Connessione, WS-Fed o WindowsAzureActiveDirectoryBearerAuthentication, ha già la logica necessaria per gestire automaticamente il rollover delle chiavi.

È possibile verificare che l'applicazione usi uno di questi elementi cercando uno dei frammenti di codice seguenti nei file Startup.cs o Startup.Auth.cs dell'applicazione.

app.UseOpenIdConnectAuthentication(
    new OpenIdConnectAuthenticationOptions
    {
        // ...
    });

app.UseWsFederationAuthentication(
    new WsFederationAuthenticationOptions
    {
        // ...
    });

app.UseWindowsAzureActiveDirectoryBearerAuthentication(
    new WindowsAzureActiveDirectoryBearerAuthenticationOptions
    {
        // ...
    });

API / applicazioni Web che proteggono le risorse usando middleware .NET Core OpenID Connect o JwtBearerAuthentication

Se l'applicazione usa il middleware OWIN OpenID Connessione o JwtBearerAuthentication ASP.NET, ha già la logica necessaria per gestire automaticamente il rollover delle chiavi.

È possibile verificare che l'applicazione usi middleware di questo tipo cercando uno dei frammenti seguenti nei file Startup.cs o Startup.Auth.cs dell'applicazione

app.UseOpenIdConnectAuthentication(
     new OpenIdConnectAuthenticationOptions
     {
         // ...
     });

app.UseJwtBearerAuthentication(
    new JwtBearerAuthenticationOptions
    {
     // ...
     });

Applicazioni Web/API che proteggono le risorse usando Node.js `passport-azure-ad` modulo

Se l'applicazione usa il modulo Node.js passport-ad, ha già la logica necessaria per gestire automaticamente il rollover della chiave.

È possibile verificare che l'applicazione usi il modulo passport-ad cercando il frammento seguente nel file app.js dell'applicazione

var OIDCStrategy = require('passport-azure-ad').OIDCStrategy;

passport.use(new OIDCStrategy({
    //...
));

Applicazioni Web/API che proteggono le risorse e create con Visual Studio 2015 o versione successiva

Se l'applicazione è stata compilata usando un modello di applicazione Web in Visual Studio 2015 o versione successiva ed è stato selezionato Account aziendali o dell'istituto di istruzione dal menu Modifica autenticazione , è già disponibile la logica necessaria per gestire automaticamente il rollover delle chiavi. Questa logica, incorporata nel middleware OWIN OpenID Connessione, recupera e memorizza nella cache le chiavi dal documento di individuazione Connessione OpenID e le aggiorna periodicamente.

Se l'autenticazione è stata aggiunta alla soluzione manualmente, l'applicazione potrebbe non avare la logica di rollover della chiave necessaria. È possibile scriverlo manualmente o seguire la procedura descritta in Applicazioni Web/API usando qualsiasi altra libreria o implementando manualmente uno dei protocolli supportati.

Applicazioni Web che proteggono le risorse e sono state create con Visual Studio 2013

Se l'applicazione è stata creata usando un modello di applicazione Web in Visual Studio 2013 e sono stati selezionati account aziendali dal menu Modifica autenticazione, l'applicazione ha già la logica necessaria per gestire automaticamente il rollover della chiave. Questa logica archivia l'identificatore univoco dell'organizzazione e informazioni sulla chiave di firma in due tabelle di database associate al progetto. La stringa di connessione per il database si trova nel file Web.config del progetto.

Se l'autenticazione è stata aggiunta alla soluzione manualmente, l'applicazione potrebbe non avare la logica di rollover della chiave necessaria. Sarà necessario scriverlo manualmente o seguire la procedura descritta in Applicazioni Web/API usando qualsiasi altra libreria o implementando manualmente uno dei protocolli supportati.

I passaggi seguenti consentono di verificare che la logica funzioni correttamente nell'applicazione.

In Visual Studio 2013 aprire la soluzione e quindi selezionare nella scheda Esplora server nella finestra a destra.
Espandere Connessioni dati, DefaultConnection e quindi Tabelle. Individuare la tabella IssuingAuthorityKeys , fare clic con il pulsante destro del mouse e quindi selezionare Mostra dati tabella.
Nella tabella IssuingAuthorityKeys sarà presente almeno una riga che corrisponde al valore di identificazione personale per la chiave. Eliminare tutte le righe nella tabella.
Fare clic con il pulsante destro del mouse sulla tabella Tenant e quindi scegliere Mostra dati tabella.
Nella tabella Tenant sarà presente almeno una riga che corrisponde a un identificatore di tenant directory univoco. Eliminare tutte le righe nella tabella. Se non si eliminano le righe nella tabella Tenants e nella tabella IssuingAuthorityKeys , verrà visualizzato un errore in fase di esecuzione.
Compilare ed eseguire l'applicazione. Dopo aver effettuato l'accesso al proprio account sarà possibile arrestare l'applicazione.
Tornare a Esplora Server ed esaminare i valori nelle tabelle IssuingAuthorityKeys e Tenant. Si noterà che sono stati popolati automaticamente con le informazioni appropriate dal documento di metadati della federazione.

API Web che proteggono le risorse e sono state create con Visual Studio 2013

Se è stata creata un'applicazione API Web in Visual Studio 2013 usando il modello API Web e sono stati selezionati account aziendali dal menu Modifica autenticazione, l'applicazione ha già la logica necessaria.

Se l'autenticazione è stata configurata manualmente, seguire le istruzioni riportate di seguito per informazioni su come configurare l'API Web per aggiornare automaticamente le informazioni sulla chiave.

Il frammento di codice seguente illustra come ottenere le chiavi più recenti dal documento dei metadati della federazione e quindi usa il gestore token JWT per convalidare il token. Il frammento di codice presuppone che si userà il proprio meccanismo di memorizzazione nella cache per rendere persistente la chiave per convalidare i token futuri da Microsoft Identity Platform, sia che si trovi in un database, in un file di configurazione o altrove.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.IdentityModel.Tokens;
using System.Configuration;
using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.IdentityModel.Metadata;
using System.ServiceModel.Security;
using System.Threading;

namespace JWTValidation
{
    public class JWTValidator
    {
        private string MetadataAddress = "[Your Federation Metadata document address goes here]";

        // Validates the JWT Token that's part of the Authorization header in an HTTP request.
        public void ValidateJwtToken(string token)
        {
            JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler()
            {
                // Do not disable for production code
                CertificateValidator = X509CertificateValidator.None
            };

            TokenValidationParameters validationParams = new TokenValidationParameters()
            {
                AllowedAudience = "[Your App ID URI goes here]",
                ValidIssuer = "[The issuer for the token goes here, such as https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/]",
                SigningTokens = GetSigningCertificates(MetadataAddress)

                // Cache the signing tokens by your desired mechanism
            };

            Thread.CurrentPrincipal = tokenHandler.ValidateToken(token, validationParams);
        }

        // Returns a list of certificates from the specified metadata document.
        public List<X509SecurityToken> GetSigningCertificates(string metadataAddress)
        {
            List<X509SecurityToken> tokens = new List<X509SecurityToken>();

            if (metadataAddress == null)
            {
                throw new ArgumentNullException(metadataAddress);
            }

            using (XmlReader metadataReader = XmlReader.Create(metadataAddress))
            {
                MetadataSerializer serializer = new MetadataSerializer()
                {
                    // Do not disable for production code
                    CertificateValidationMode = X509CertificateValidationMode.None
                };

                EntityDescriptor metadata = serializer.ReadMetadata(metadataReader) as EntityDescriptor;

                if (metadata != null)
                {
                    SecurityTokenServiceDescriptor stsd = metadata.RoleDescriptors.OfType<SecurityTokenServiceDescriptor>().First();

                    if (stsd != null)
                    {
                        IEnumerable<X509RawDataKeyIdentifierClause> x509DataClauses = stsd.Keys.Where(key => key.KeyInfo != null && (key.Use == KeyType.Signing || key.Use == KeyType.Unspecified)).
                                                             Select(key => key.KeyInfo.OfType<X509RawDataKeyIdentifierClause>().First());

                        tokens.AddRange(x509DataClauses.Select(token => new X509SecurityToken(new X509Certificate2(token.GetX509RawData()))));
                    }
                    else
                    {
                        throw new InvalidOperationException("There is no RoleDescriptor of type SecurityTokenServiceType in the metadata");
                    }
                }
                else
                {
                    throw new Exception("Invalid Federation Metadata document");
                }
            }
            return tokens;
        }
    }
}

Applicazioni Web che proteggono le risorse e sono state create con Visual Studio 2012

Se l'applicazione è stata creata in Visual Studio 2012 è stato probabilmente usato lo strumento Identità e accesso per configurare l'applicazione. È anche probabile che si usi Validating Issuer Name Registry (VINR). VINR è responsabile della gestione delle informazioni sui provider di identità attendibili (Microsoft Identity Platform) e sulle chiavi usate per convalidare i token rilasciati da tali provider. VINR semplifica anche l'aggiornamento automatico delle informazioni sulla chiave archiviate in un file Web.config, scaricando il documento di metadati della federazione più recente associato alla directory, verificando se la configurazione è aggiornata con il documento più recente e aggiornando l'applicazione per l'uso della nuova chiave se necessario.

Se l'applicazione è stata creata usando uno degli esempi di codice o le procedure dettagliate offerte da Microsoft, la logica di rollover della chiave è già inclusa nel progetto. Si noterà che il codice seguente esiste già nel progetto. Se l'applicazione non ha questa logica, seguire questa procedura per aggiungerla e verificarne il corretto funzionamento.

In Esplora soluzioni aggiungere un riferimento all'assembly System.IdentityModel per il progetto appropriato.
Aprire il file Global.asax.cs e aggiungere le direttive using seguenti:
```
using System.Configuration;
using System.IdentityModel.Tokens;
```

Aggiungere il metodo seguente al file Global.asax.cs :

protected void RefreshValidationSettings()
{
 string configPath = AppDomain.CurrentDomain.BaseDirectory + "\\" + "Web.config";
 string metadataAddress =
               ConfigurationManager.AppSettings["ida:FederationMetadataLocation"];
 ValidatingIssuerNameRegistry.WriteToConfig(metadataAddress, configPath);
}

Richiamare il metodo RefreshValidation Impostazioni() nel metodo Application_Start() in Global.asax.cs come illustrato:

protected void Application_Start()
{
 AreaRegistration.RegisterAllAreas();
 ...
 RefreshValidationSettings();
}

Dopo aver eseguito questi passaggi, il file Web.config dell'applicazione verrà aggiornato con le informazioni più recenti del documento di metadati della federazione, incluse le chiavi più recenti. Questo aggiornamento verrà eseguito ogni volta che il pool di applicazioni viene riciclato in IIS. Per impostazione predefinita, IIS è impostato per il riciclo delle applicazioni ogni 29 ore.

Seguire questa procedura per verificare che la logica di rollover della chiave funzioni.

Dopo aver verificato che l'applicazione stia usando il codice precedente, aprire il file Web.config e passare al <blocco issuerNameRegistry> , in particolare cercando le poche righe seguenti:

<issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry">
     <authority name="https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/">
       <keys>
         <add thumbprint="3A38FA984E8560F19AADC9F86FE9594BB6AD049B" />
       </keys>

Nell'impostazione <add thumbprint=""> modificare il valore di identificazione personale sostituendo qualsiasi carattere con uno diverso. Salvare il file Web.config .
Compilare l'applicazione ed eseguirla. Se è possibile completare il processo di accesso, l'applicazione aggiorna in modo corretto la chiave scaricando le informazioni necessarie dal documento di metadati della federazione della directory. Se si verificano problemi di accesso, assicurarsi che le modifiche nell'applicazione siano corrette leggendo l'articolo Aggiunta dell'accesso all'applicazione Web tramite Microsoft Identity Platform o il download e l'ispezione dell'esempio di codice seguente: Multi-Tenant Cloud Application for Microsoft Entra ID.

API / applicazioni Web che proteggono le risorse usando qualsiasi altra libreria o con implementazione manuale di qualsiasi protocollo supportato

Se si usano altre librerie o si implementa manualmente qualsiasi protocollo supportato, sarà necessario esaminare la libreria o l'implementazione per verificare che la chiave venga recuperata dal documento di individuazione di OpenID Connect o dal documento di metadati della federazione. Un modo per eseguire la verifica è cercare nel codice o nel codice della libreria chiamate al documento di individuazione di OpenID o al documento di metadati della federazione.

Se la chiave viene archiviata in un punto qualsiasi o hardcoded nell'applicazione, è possibile recuperare manualmente la chiave e aggiornarla di conseguenza eseguendo un rollover manuale in base alle istruzioni alla fine di questo documento sussidiario. È vivamente consigliabile migliorare l'applicazione per supportare il rollover automatico usando uno degli approcci descritti in questo articolo per evitare interruzioni future e sovraccarichi se Microsoft Identity Platform aumenta la frequenza di rollover o ha un rollover fuori banda di emergenza.

Come testare l'applicazione per stabilire se sarà interessata

È possibile verificare se l'applicazione supporta il rollover automatico delle chiavi usando gli script di PowerShell seguenti.

Per controllare e aggiornare le chiavi di firma con PowerShell, è necessario il modulo MSIdentityTools di PowerShell.

Installare il modulo POWERShell MSIdentityTools :
```
Install-Module -Name MSIdentityTools
```
Accedere usando il comando Connessione-MgGraph con un account amministratore per fornire il consenso agli ambiti necessari:
```
 Connect-MgGraph -Scope "Application.ReadWrite.All"
```
Ottenere l'elenco delle identificazioni personali della chiave di firma disponibili:
```
Get-MsIdSigningKeyThumbprint
```
Selezionare una delle identificazioni personali della chiave e configurare Microsoft Entra ID per l'uso di tale chiave con l'applicazione (ottenere l'ID app dall'interfaccia di amministrazione di Microsoft Entra):
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>
```
Testare l'applicazione Web accedendo per ottenere un nuovo token. La modifica dell'aggiornamento della chiave è istantanea, ma assicurarsi di usare una nuova sessione del browser (usando, ad esempio, "InPrivate" di Internet Explorer, "In incognito" di Chrome o la modalità "Privata" di Firefox) per assicurarsi che venga rilasciato un nuovo token.
Per ognuna delle identificazioni personali della chiave di firma restituite, eseguire il cmdlet e testare il Update-MsIdApplicationSigningKeyThumbprint processo di accesso dell'applicazione Web.
Se l'applicazione Web esegue correttamente l'accesso, supporta il rollover automatico. In caso contrario, modificare l'applicazione per supportare il rollover manuale. Per altre informazioni, vedere Definizione di un processo di rollover manuale.

Eseguire lo script seguente per ripristinare il comportamento normale:

Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default

Come eseguire un rollover manuale se l'applicazione non supporta il rollover automatico

Se l'applicazione non supporta il rollover automatico, è necessario stabilire un processo che monitora periodicamente le chiavi di firma di Microsoft Identity Platform ed esegue di conseguenza un rollover manuale.

Per controllare e aggiornare le chiavi di firma con PowerShell, è necessario il MSIdentityTools modulo PowerShell.

Installare il MSIdentityTools modulo PowerShell:
```
Install-Module -Name MSIdentityTools
```
Ottenere la chiave di firma più recente (ottenere l'ID tenant dall'interfaccia di amministrazione di Microsoft Entra):
```
Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
```
Confrontare questa chiave con la chiave attualmente impostata come hardcoded o configurata per l'uso.
Se la chiave più recente è diversa dalla chiave usata dall'applicazione, scaricare la chiave di firma più recente:
```
Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
```
Aggiornare il codice o la configurazione dell'applicazione per usare la nuova chiave.
Configurare l'ID Microsoft Entra per l'uso di tale chiave più recente con l'applicazione (ottenere l'ID app dall'interfaccia di amministrazione di Microsoft Entra):
```
Get-MsIdSigningKeyThumbprint -Latest | Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId>
```
Testare l'applicazione Web accedendo per ottenere un nuovo token. La modifica dell'aggiornamento della chiave è istantanea, ma assicurarsi di usare una nuova sessione del browser (usando, ad esempio, "InPrivate" di Internet Explorer, "In incognito" di Chrome o la modalità "Privata" di Firefox) per assicurarsi che venga rilasciato un nuovo token.

In caso di problemi, ripristinare la chiave precedente usata e contattare supporto tecnico di Azure:

Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <PreviousKeyThumbprint>

Dopo aver aggiornato l'applicazione per supportare il rollover manuale, ripristinare il comportamento normale:
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
```