Rollover della chiave di firma in Microsoft Identity Platform

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. Si apprenderà anche 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 è firmato da Microsoft Identity Platform usando la chiave privata prima di essere 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 contenuto nel documento di individuazione OpenID Connect del tenant o nel documento di metadati della 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 c'è tempo impostato o garantito tra questi rotoli chiave. 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. È consigliabile usare librerie standard per assicurarsi che i metadati delle chiavi vengano aggiornati correttamente e che siano aggiornati. Nei casi in cui le librerie standard non vengono usate, assicurarsi che l'implementazione segua la sezione procedure consigliate .

Sono sempre disponibili più chiavi valide nel documento di individuazione openID Connect 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'applicazione. Per altre informazioni sulla struttura dei dati della chiave Web JSON, è possibile fare riferimento RFC7517.

Le applicazioni che supportano solo una singola chiave di firma o applicazioni 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.

Procedure consigliate per la memorizzazione nella cache e la convalida dei metadati delle chiavi

• Individuare le chiavi usando l'endpoint specifico del tenant, come descritto in OpenID Connect (OIDC) e metadati di federazione
• Anche se l'applicazione viene distribuita in più tenant, è consigliabile individuare sempre e memorizzare nella cache le chiavi in modo indipendente per ogni tenant usato dall'applicazione (usando l'endpoint specifico del tenant). Una chiave comune tra i tenant può oggi diventare distinta tra i tenant in futuro.
• Usare l'algoritmo di memorizzazione nella cache seguente per assicurarsi che la memorizzazione nella cache sia resiliente e sicura

Algoritmo di memorizzazione nella cache dei metadati delle chiavi:

Le librerie standard implementano la memorizzazione nella cache resiliente e sicura delle chiavi. È consigliabile usarli per evitare piccoli difetti nell'implementazione. Per le implementazioni personalizzate, ecco l'algoritmo approssimativo:

Considerazioni generali:

• Il servizio che convalida i token deve avere una cache in grado di archiviare molte chiavi distinte (10-1000).
• Le chiavi devono essere memorizzate nella cache singolarmente, usando l'ID chiave ("kid" nella specifica dei metadati delle chiavi OIDC) come chiave della cache.
• La durata delle chiavi nella cache deve essere configurata su 24 ore, con aggiornamenti che si verificano ogni ora. In questo modo il sistema può rispondere rapidamente alle chiavi da rimuovere, ma ha una durata della cache sufficiente per non essere influenzata dai problemi nel recupero delle chiavi.
• Le chiavi devono essere aggiornate:
  • Una volta all'avvio del processo o quando la cache è vuota
  • Periodicamente (consigliato ogni 1 ora) come processo in background
  • In modo dinamico se un token ricevuto è stato firmato con una chiave sconosciuta (elemento figlio sconosciuto o tid nell'intestazione)

Procedura KeyRefresh (algoritmo concettuale di IdentityModel)

1. Inizializzazione

   Configuration Manager viene configurato con un indirizzo specifico per recuperare i dati di configurazione e le interfacce necessarie per recuperare e convalidare questi dati.

2. Controllo configurazione

   Prima di recuperare nuovi dati, il sistema controlla innanzitutto se i dati esistenti sono ancora validi in base a un intervallo di aggiornamento predefinito.

3. Recupero dati Se i dati sono obsoleti o mancanti, il sistema si blocca per garantire che un solo thread recupera i nuovi dati per evitare la duplicazione (e l'esaurimento del thread). Il sistema tenta quindi di recuperare i dati di configurazione più recenti da un endpoint specificato.

4. Convalida

   Dopo aver recuperato i nuovi dati, viene convalidato per assicurarsi che soddisfi gli standard richiesti e non sia danneggiato. I metadati vengono accettati solo quando una richiesta in ingresso è stata convalidata correttamente con le nuove chiavi.

5. Gestione degli errori

   Se si verificano errori durante il recupero dei dati, vengono registrati. Il sistema continua a funzionare con l'ultima configurazione valida nota se non è possibile recuperare nuovi dati

6. Aggiornamenti automatici Il sistema controlla periodicamente e aggiorna automaticamente i dati di configurazione in base all'intervallo di aggiornamento (consigliare 12 h con un instabilità più o meno 1 h). Può anche richiedere manualmente un aggiornamento, se necessario, assicurandosi che i dati siano sempre aggiornati.

7. Convalida di un token con una nuova chiave Se un token arriva con una chiave di firma non ancora nota dalla configurazione, il sistema tenta di recuperare la configurazione con una chiamata di sincronizzazione sul percorso critico per gestire nuove chiavi nei metadati al di fuori degli aggiornamenti previsti regolari(ma non più di 5 minuti)

Questo approccio garantisce che il sistema usi sempre i dati di configurazione più aggiornati e validi, gestendo normalmente gli errori ed evitando operazioni ridondanti.

L'implementazione .NET di questo algoritmo è disponibile da BaseConfigurationManager. È soggetto a modifiche in base alla resilienza e alle valutazioni della sicurezza. Vedere anche una spiegazione qui

Procedura KeyRefresh (pseudocode):

Questa procedura usa un timestamp globale (lastSuccessfulRefreshTime) per evitare condizioni che aggiornano le chiavi troppo spesso.

• OpenID Connect (OIDC)

KeyRefresh(issuer)
{
  // Store cache entries and last successful refresh timestamp per distinct 'issuer'
 
  if (LastSuccessfulRefreshTime is set and more recent than 5 minutes ago) 
    return // without refreshing
 
  // Load keys URI using the tenant-specific OIDC configuration endpoint ('issuer' is the input parameter)
  oidcConfiguration = download JSON from "{issuer}/.well-known/openid-configuration"
 
  // Load list of keys from keys URI
  keyList = download JSON from jwks_uri property of oidcConfiguration
 
  foreach (key in keyList) 
  {
    cache entry = lookup in cache by kid property of key
    if (cache entry found) 
      set expiration of cache entry to now + 24h 
    else 
      add key to cache with expiration set to now + 24h
  }
 
  set LastSuccessfulRefreshTime to now // current timestamp
}

Procedura di avvio del servizio:

• KeyRefresh per aggiornare le chiavi
• Avviare un processo in background che chiama KeyRefresh ogni ora

Procedura TokenValidation per convalidare la chiave (pseudocode):

ValidateToken(token)
{
  kid = token.header.kid // get key id from token header
  issuer = token.body.iss // get issuer from 'iss' claim in token body
 
  key = lookup in cache by issuer and kid
  if (key found)
  {
     validate token with key and return
  }
  else // key is not found in the cache
  {
    call KeyRefresh(issuer) // to opportunistically refresh the keys for the issuer
    key = lookup in cache by issuer and kid
    if (key found)
    {
      validate token with key and return
    }
    else // key is not found in the cache even after refresh
    {
      return token validation error
    }
  }
}

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 Connect, WS-Fed o WindowsAzureActiveDirectoryBearerAuthentication
• Applicazioni Web/API che proteggono le risorse usando ASP.NET middleware Core OpenID Connect 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 Connect, WS-Fed o WindowsAzureActiveDirectoryBearerAuthentication

Se l'applicazione usa il middleware OWIN OpenID Connect, WS-Fed o WindowsAzureActiveDirectoryBearerAuthentication ASP.NET, 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 Connect 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 Connect, recupera e memorizza nella cache le chiavi dal documento di individuazione di OpenID Connect 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. È 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.

1. In Visual Studio 2013 aprire la soluzione e quindi selezionare nella scheda Esplora server nella finestra a destra.
2. 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.
3. Nella tabella IssuingAuthorityKeys sarà presente almeno una riga che corrisponde al valore di identificazione personale per la chiave. Eliminare tutte le righe nella tabella.
4. Fare clic con il pulsante destro del mouse sulla tabella Tenant e quindi scegliere Mostra dati tabella.
5. 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 , viene visualizzato un errore in fase di esecuzione.
6. Compilare ed eseguire l'applicazione. Dopo aver effettuato l'accesso al proprio account sarà possibile arrestare l'applicazione.
7. Tornare a Esplora Server ed esaminare i valori nelle tabelle IssuingAuthorityKeys e Tenant. Si noterà che sono stati ripopolati automaticamente con le informazioni appropriate dal documento dei 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 stia usando il Registro dei nomi dell'autorità di certificazione di convalida (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 già questa logica, seguire questa procedura per aggiungerla e verificare che funzioni correttamente.

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

   using System.Configuration;
   using System.IdentityModel.Tokens;
   

3. 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);
   }
   

4. Richiamare il metodo RefreshValidationSettings() 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.

1. 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="AA11BB22CC33DD44EE55FF66AA77BB88CC99DD00" />
          </keys>
   

2. Nell'impostazione <add thumbprint=""> modificare il valore di identificazione personale sostituendo qualsiasi carattere con uno diverso. Salvare il file Web.config .
3. 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'analisi dell'esempio di codice seguente: Multitenant 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 usa un'altra raccolta o si implementa manualmente uno dei protocolli supportati, è necessario esaminare la raccolta o l'implementazione per assicurarsi che la chiave venga recuperata dal documento di individuazione openID Connect o dal documento dei 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.

1. Installare il modulo POWERShell MSIdentityTools :

   Install-Module -Name MSIdentityTools
   

2. Accedere usando il comando Connect-MgGraph con un account amministratore per fornire il consenso agli ambiti necessari:

    Connect-MgGraph -Scope "Application.ReadWrite.All"
   

3. Ottenere l'elenco delle identificazioni personali della chiave di firma disponibili:

   Get-MsIdSigningKeyThumbprint
   

4. 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>
   

5. 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.

6. Per ognuna delle identificazioni personali della chiave di firma restituite, eseguire il cmdlet e testare il Update-MsIdApplicationSigningKeyThumbprint processo di accesso dell'applicazione Web.

7. 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.

8. 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.

1. Installare il MSIdentityTools modulo PowerShell:

   Install-Module -Name MSIdentityTools
   

2. Ottenere la chiave di firma più recente (ottenere l'ID tenant dall'interfaccia di amministrazione di Microsoft Entra):

   Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
   

3. Confrontare questa chiave con la chiave attualmente impostata come hardcoded o configurata per l'uso.

4. Se la chiave più recente è diversa dalla chiave usata dall'applicazione, scaricare la chiave di firma più recente:

   Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
   

5. Aggiornare il codice o la configurazione dell'applicazione per usare la nuova chiave.

6. 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>
   

7. 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 per assicurarsi che venga rilasciato un nuovo token. Ad esempio, usa la modalità "InPrivate" di Microsoft Edge, "In incognito" di Chrome o "Privata" di Firefox.

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

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

9. Dopo aver aggiornato l'applicazione per supportare il rollover manuale, ripristinare il comportamento normale:

   Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default