Rollover della chiave di firma in Azure Active DirectorySigning key rollover in Azure Active Directory

Questo argomento illustra che cosa è necessario sapere sulle chiavi pubbliche usate per la firma dei token di sicurezza in Azure Active Directory (Azure AD).This topic discusses what you need to know about the public keys that are used in Azure Active Directory (Azure AD) to sign security tokens. È importante notare che il rollover di queste chiavi viene eseguito periodicamente e in caso di emergenza può essere eseguito immediatamente.It is important to note that these keys rollover on a periodic basis and, in an emergency, could be rolled over immediately. Tutte le applicazioni che usano Azure AD devono poter gestire a livello di codice il processo di rollover della chiave o stabilire un processo di rollover manuale periodico.All applications that use Azure AD should be able to programmatically handle the key rollover process or establish a periodic manual rollover process. Continuare la lettura per comprendere il funzionamento delle 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 della chiave, se necessario.Continue reading to understand how the keys work, how to assess the impact of the rollover to your application and how to update your application or establish a periodic manual rollover process to handle key rollover if necessary.

Informazioni generali sulle chiavi di firma in Azure ADOverview of signing keys in Azure AD

Azure AD usa la crittografia a chiave pubblica basata su standard di settore per stabilire una relazione di trust tra se stesso e le applicazioni che usano Azure AD.Azure AD uses public-key cryptography built on industry standards to establish trust between itself and the applications that use it. In termini pratici, Azure AD usa una chiave di firma costituita da una coppia di chiavi pubbliche e private.In practical terms, this works in the following way: Azure AD uses a signing key that consists of a public and private key pair. Quando un utente accede a un'applicazione che usa Azure AD per l'autenticazione, Azure AD crea un token di sicurezza contenente informazioni sull'utente.When a user signs in to an application that uses Azure AD for authentication, Azure AD creates a security token that contains information about the user. Questo token viene firmato da Azure AD con la chiave privata prima che venga inviato di nuovo all'applicazione.This token is signed by Azure AD using its private key before it is sent back to the application. Per verificare che il token sia valido e sia stato realmente originato da Azure AD, l'applicazione deve convalidare la firma del token usando la chiave pubblica esposta da Azure AD contenuta nel documento di individuazione di OpenID Connect del tenant o nel documento dei metadati della federazione SAML/WS-Fed.To verify that the token is valid and actually originated from Azure AD, the application must validate the token’s signature using the public key exposed by Azure AD that is contained in the tenant’s OpenID Connect discovery document or SAML/WS-Fed federation metadata document.

Per motivi di sicurezza, il rollover della chiave di firma di Azure AD viene eseguito periodicamente e può essere eseguito immediatamente in caso di emergenza.For security purposes, Azure AD’s signing key rolls on a periodic basis and, in the case of an emergency, could be rolled over immediately. Qualsiasi applicazione che si integra con Azure AD deve poter gestire un evento di rollover della chiave indipendentemente dalla frequenza con cui può verificarsi.Any application that integrates with Azure AD should be prepared to handle a key rollover event no matter how frequently it may occur. Se l'applicazione non ha la logica necessaria e prova a usare una chiave scaduta per verificare la firma su un token, la richiesta di accesso avrà esito negativo.If it doesn’t, and your application attempts to use an expired key to verify the signature on a token, the sign-in request will fail.

È sempre disponibile più di una chiave valida nel documento di individuazione di OpenID Connect e nel documento di metadati della federazione.There is always more than one valid key available in the OpenID Connect discovery document and the federation metadata document. L'applicazione deve poter usare qualsiasi chiave specificata nel documento perché di una chiave può essere eseguito il rollover a breve, un'altra può essere quella sostitutiva e così via.Your application should be prepared to use any of the keys specified in the document, since one key may be rolled soon, another may be its replacement, and so forth.

Come valutare se l'applicazione sarà interessata e come intervenireHow to assess if your application will be affected and what to do about it

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.How your application handles key rollover depends on variables such as the type of application or what identity protocol and library was used. 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.The sections below assess whether the most common types of applications are impacted by the key rollover and provide guidance on how to update the application to support automatic rollover or manually update the key.

Queste indicazioni non sono valide per:This guidance is not applicable for:

  • Applicazioni aggiunte dalla raccolta di applicazioni di Azure AD (incluse quelle personalizzate), che hanno indicazioni separate per la chiave di firma.Applications added from Azure AD Application Gallery (including Custom) have separate guidance with regards to signing keys. Altre informazioni.More information.
  • Applicazioni locali pubblicate tramite il proxy di applicazione, che non prevedono le chiavi di firma.On-premises applications published via application proxy don't have to worry about signing keys.

Applicazioni client native che accedono alle risorseNative client applications accessing resources

Le applicazioni che si limitano ad accedere alle risorse, comeApplications that are only accessing resources (i.e Microsoft Graph, l'insieme di credenziali, l'API Outlook e altre API Microsoft, in genere ottengono soltanto un token e lo passano al proprietario della risorsa.Microsoft Graph, KeyVault, Outlook API and other Microsoft APIs) generally only obtain a token and pass it along to the resource owner. Dato che tali applicazioni non proteggono risorse, il token non viene controllato e quindi non è necessario assicurarsi che sia firmato correttamente.Given that they are not protecting any resources, they do not inspect the token and therefore do not need to ensure it is properly signed.

Le applicazioni client native, sia per desktop che per dispositivi mobili, rientrano in questa categoria e quindi non sono interessate dal rollover.Native client applications, whether desktop or mobile, fall into this category and are thus not impacted by the rollover.

API / applicazioni Web che accedono alle risorseWeb applications / APIs accessing resources

Le applicazioni che si limitano ad accedere alle risorse, comeApplications that are only accessing resources (i.e Microsoft Graph, l'insieme di credenziali, l'API Outlook e altre API Microsoft, in genere ottengono soltanto un token e lo passano al proprietario della risorsa.Microsoft Graph, KeyVault, Outlook API and other Microsoft APIs) generally only obtain a token and pass it along to the resource owner. Dato che tali applicazioni non proteggono risorse, il token non viene controllato e quindi non è necessario assicurarsi che sia firmato correttamente.Given that they are not protecting any resources, they do not inspect the token and therefore do not need to ensure it is properly signed.

Le applicazioni Web e le API Web che usano il flusso solo app (credenziali client / certificato client) rientrano in questa categoria e quindi non sono interessate dal rollover.Web applications and web APIs that are using the app-only flow (client credentials / client certificate), fall into this category and are thus not impacted by the rollover.

API / applicazioni Web che proteggono le risorse e sono state compilate con i servizi app di AzureWeb applications / APIs protecting resources and built using Azure App Services

La funzionalità di autenticazione / autorizzazione (EasyAuth) dei servizi app di Azure ha già la logica necessaria per gestire automaticamente il rollover della chiave.Azure App Services' Authentication / Authorization (EasyAuth) functionality already has the necessary logic to handle key rollover automatically.

API / applicazioni Web che proteggono le risorse usando middleware .NET OWIN OpenID Connect, WS-Fed o WindowsAzureActiveDirectoryBearerAuthenticationWeb applications / APIs protecting resources using .NET OWIN OpenID Connect, WS-Fed or WindowsAzureActiveDirectoryBearerAuthentication middleware

Se l'applicazione usa middleware .NET OWIN OpenID Connect, WS-Fed o WindowsAzureActiveDirectoryBearerAuthentication, ha già la logica necessaria per gestire automaticamente il rollover della chiave.If your application is using the .NET OWIN OpenID Connect, WS-Fed or WindowsAzureActiveDirectoryBearerAuthentication middleware, it already has the necessary logic to handle key rollover automatically.

È possibile verificare che l'applicazione usi middleware di questo tipo cercando uno dei frammenti seguenti nei file Startup.cs o Startup.Auth.cs dell'applicazioneYou can confirm that your application is using any of these by looking for any of the following snippets in your application's Startup.cs or Startup.Auth.cs

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 JwtBearerAuthenticationWeb applications / APIs protecting resources using .NET Core OpenID Connect or JwtBearerAuthentication middleware

Se l'applicazione usa middleware .NET Core OWIN OpenID Connect o JwtBearerAuthentication, ha già la logica necessaria per gestire automaticamente il rollover della chiave.If your application is using the .NET Core OWIN OpenID Connect or JwtBearerAuthentication middleware, it already has the necessary logic to handle key rollover automatically.

È possibile verificare che l'applicazione usi middleware di questo tipo cercando uno dei frammenti seguenti nei file Startup.cs o Startup.Auth.cs dell'applicazioneYou can confirm that your application is using any of these by looking for any of the following snippets in your application's Startup.cs or Startup.Auth.cs

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

API / applicazioni Web che proteggono le risorse usando il modulo Node.js passport-azure-adWeb applications / APIs protecting resources using Node.js passport-azure-ad module

Se l'applicazione usa il modulo Node.js passport-ad, ha già la logica necessaria per gestire automaticamente il rollover della chiave.If your application is using the Node.js passport-ad module, it already has the necessary logic to handle key rollover automatically.

È possibile verificare che l'applicazione usi il modulo passport-ad cercando il frammento seguente nel file app.js dell'applicazioneYou can confirm that your application passport-ad by searching for the following snippet in your application's app.js

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

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

API/applicazioni Web che proteggono le risorse e sono state create con Visual Studio 2015 o Visual Studio 2017Web applications / APIs protecting resources and created with Visual Studio 2015 or Visual Studio 2017

Se l'applicazione è stata creata usando un modello di applicazione Web in Visual Studio 2015 o Visual Studio 2017 ed è stata selezionata l'opzione Account aziendali o dell'istituto di istruzione nel menu Modifica autenticazione, l'applicazione ha già la logica necessaria per gestire automaticamente il rollover della chiave.If your application was built using a web application template in Visual Studio 2015 or Visual Studio 2017 and you selected Work And School Accounts from the Change Authentication menu, it already has the necessary logic to handle key rollover automatically. 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.This logic, embedded in the OWIN OpenID Connect middleware, retrieves and caches the keys from the OpenID Connect discovery document and periodically refreshes them.

Se l'autenticazione è stata aggiunta alla soluzione manualmente, l'applicazione potrebbe non avare la logica di rollover della chiave necessaria.If you added authentication to your solution manually, your application might not have the necessary key rollover logic. Sarà necessario scriverla oppure seguire i passaggi illustrati in API/Applicazioni Web che proteggono le risorse usando qualsiasi altra libreria o con implementazione manuale di qualsiasi protocollo supportato.You will need to write it yourself, or follow the steps in Web applications / APIs using any other libraries or manually implementing any of the supported protocols..

Applicazioni Web che proteggono le risorse e sono state create con Visual Studio 2013Web applications protecting resources and created with 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.If your application was built using a web application template in Visual Studio 2013 and you selected Organizational Accounts from the Change Authentication menu, it already has the necessary logic to handle key rollover automatically. Questa logica archivia l'identificatore univoco dell'organizzazione e informazioni sulla chiave di firma in due tabelle di database associate al progetto.This logic stores your organization’s unique identifier and the signing key information in two database tables associated with the project. La stringa di connessione per il database si trova nel file Web.config del progetto.You can find the connection string for the database in the project’s Web.config file.

Se l'autenticazione è stata aggiunta alla soluzione manualmente, l'applicazione potrebbe non avare la logica di rollover della chiave necessaria.If you added authentication to your solution manually, your application might not have the necessary key rollover logic. Sarà necessario scriverla oppure seguire i passaggi illustrati in API/Applicazioni Web che proteggono le risorse usando qualsiasi altra libreria o con implementazione manuale di qualsiasi protocollo supportato.You will need to write it yourself, or follow the steps in Web applications / APIs using any other libraries or manually implementing any of the supported protocols..

I passaggi seguenti consentono di verificare il corretto funzionamento della logica dell'applicazione.The following steps will help you verify that the logic is working properly in your application.

  1. In Visual Studio 2013 aprire la soluzione e quindi fare clic sulla scheda Esplora Server nella finestra di destra.In Visual Studio 2013, open the solution, and then click on the Server Explorer tab on the right window.
  2. Espandere Connessioni dati, DefaultConnection e quindi Tabelle.Expand Data Connections, DefaultConnection, and then Tables. Trovare la tabella IssuingAuthorityKeys, fare clic con il pulsante destro del mouse e quindi scegliere Mostra dati tabella.Locate the IssuingAuthorityKeys table, right-click it, and then click Show Table Data.
  3. Nella tabella IssuingAuthorityKeys sarà presente almeno una riga che corrisponde al valore di identificazione personale per la chiave.In the IssuingAuthorityKeys table, there will be at least one row, which corresponds to the thumbprint value for the key. Eliminare tutte le righe nella tabella.Delete any rows in the table.
  4. Fare clic con il pulsante destro del mouse sulla tabella Tenant e quindi scegliere Mostra dati tabella.Right-click the Tenants table, and then click Show Table Data.
  5. Nella tabella Tenant sarà presente almeno una riga che corrisponde a un identificatore di tenant directory univoco.In the Tenants table, there will be at least one row, which corresponds to a unique directory tenant identifier. Eliminare tutte le righe nella tabella.Delete any rows in the table. Se non si eliminano le righe nella tabella Tenant e nella tabella IssuingAuthorityKeys, si verificherà un errore in fase di esecuzione.If you don't delete the rows in both the Tenants table and IssuingAuthorityKeys table, you will get an error at runtime.
  6. Compilare ed eseguire l'applicazione.Build and run the application. Dopo aver effettuato l'accesso al proprio account sarà possibile arrestare l'applicazione.After you have logged in to your account, you can stop the application.
  7. Tornare a Esplora Server ed esaminare i valori nelle tabelle IssuingAuthorityKeys e Tenant.Return to the Server Explorer and look at the values in the IssuingAuthorityKeys and Tenants table. Si noterà che sono stati popolati automaticamente con le informazioni appropriate dal documento di metadati della federazione.You’ll notice that they have been automatically repopulated with the appropriate information from the federation metadata document.

API Web che proteggono le risorse e sono state create con Visual Studio 2013Web APIs protecting resources and created with 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.If you created a web API application in Visual Studio 2013 using the Web API template, and then selected Organizational Accounts from the Change Authentication menu, you already have the necessary logic in your application.

Se l'autenticazione è stata configurata manualmente, seguire queste istruzioni per informazioni su come configurare l'API Web per aggiornare automaticamente le informazioni sulle chiavi.If you manually configured authentication, follow the instructions below to learn how to configure your Web API to automatically update its key information.

Il frammento di codice seguente illustra come ottenere le chiavi più recenti dal documento di metadati della federazione e quindi usare il gestore dei token JWT per convalidare il token.The following code snippet demonstrates how to get the latest keys from the federation metadata document, and then use the JWT Token Handler to validate the token. Il frammento di codice presuppone che si userà il proprio meccanismo di memorizzazione nella cache per mantenere la chiave per la convalida dei futuri token di Azure AD, che si trovino in un database, in un file di configurazione o altrove.The code snippet assumes that you will use your own caching mechanism for persisting the key to validate future tokens from Azure AD, whether it be in a database, configuration file, or elsewhere.

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, as registered in the Azure Classic Portal]",
                ValidIssuer = "[The issuer for the token goes here, such as https://sts.windows.net/68b98905-130e-4d7c-b6e1-a158a9ed8449/]",
                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 2012Web applications protecting resources and created with Visual Studio 2012

Se l'applicazione è stata creata in Visual Studio 2012 è stato probabilmente usato lo strumento Identità e accesso per configurare l'applicazione.If your application was built in Visual Studio 2012, you probably used the Identity and Access Tool to configure your application. È anche probabile che si usi Validating Issuer Name Registry (VINR).It’s also likely that you are using the Validating Issuer Name Registry (VINR). VINR gestisce le informazioni sui provider di identità attendibili (Azure AD) e le chiavi usate per convalidare i token rilasciati dai provider.The VINR is responsible for maintaining information about trusted identity providers (Azure AD) and the keys used to validate tokens issued by them. 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.The VINR also makes it easy to automatically update the key information stored in a Web.config file by downloading the latest federation metadata document associated with your directory, checking if the configuration is out of date with the latest document, and updating the application to use the new key as necessary.

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.If you created your application using any of the code samples or walkthrough documentation provided by Microsoft, the key rollover logic is already included in your project. Si noterà che il codice seguente esiste già nel progetto.You will notice that the code below already exists in your project. Se l'applicazione non ha questa logica, seguire questa procedura per aggiungerla e verificarne il corretto funzionamento.If your application does not already have this logic, follow the steps below to add it and to verify that it’s working correctly.

  1. In Esplora soluzioni aggiungere un riferimento all'assembly System.IdentityModel per il progetto appropriato.In Solution Explorer, add a reference to the System.IdentityModel assembly for the appropriate project.
  2. Aprire il file Global.asax.cs e aggiungere le direttive using seguenti:Open the Global.asax.cs file and add the following using directives: using System.Configuration; using System.IdentityModel.Tokens;
  3. Aggiungere il metodo seguente al file Global.asax.cs :Add the following method to the Global.asax.cs file: 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:Invoke the RefreshValidationSettings() method in the Application_Start() method in Global.asax.cs as shown: 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.Once you have followed these steps, your application’s Web.config will be updated with the latest information from the federation metadata document, including the latest keys. 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.This update will occur every time your application pool recycles in IIS; by default IIS is set to recycle applications every 29 hours.

Seguire questa procedura per verificare che la logica di rollover della chiave funzioni.Follow the steps below to verify that the key rollover logic is working.

  1. Dopo aver verificato che l'applicazione usi il codice indicato in precedenza, aprire il file Web.config e passare al blocco , verificando in particolare le righe seguenti:After you have verified that your application is using the code above, open the Web.config file and navigate to the block, specifically looking for the following few lines: <issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry"> <authority name="https://sts.windows.net/ec4187af-07da-4f01-b18f-64c2f5abecea/"> <keys> <add thumbprint="3A38FA984E8560F19AADC9F86FE9594BB6AD049B" /> </keys>
  2. Nella tabella <add thumbprint=””> modificare il valore di identificazione personale sostituendo un carattere con uno diverso.In the <add thumbprint=””> setting, change the thumbprint value by replacing any character with a different one. Salvare il file Web.config .Save the Web.config file.
  3. Compilare l'applicazione ed eseguirla.Build the application, and then run it. 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.If you can complete the sign-in process, your application is successfully updating the key by downloading the required information from your directory’s federation metadata document. In caso di problemi di accesso verificare che le modifiche nell'applicazione siano corrette leggendo l'argomento Adding Sign-On to Your Web Application Using Azure AD (Aggiunta del processo di accesso nell'applicazione Web tramite Azure AD) oppure scaricando ed esaminando l'esempio di codice seguente: Multi-Tenant Cloud Application for Azure Active Directory (Applicazione cloud multi-tenant per Azure Active Directory).If you are having issues signing in, ensure the changes in your application are correct by reading the Adding Sign-On to Your Web Application Using Azure AD topic, or downloading and inspecting the following code sample: Multi-Tenant Cloud Application for Azure Active Directory.

Applicazioni Web che proteggono le risorse e sono state create con Visual Studio 2008 o 2010 o con Windows Identity Foundation (WIF) v1.0 per .NET 3.5Web applications protecting resources and created with Visual Studio 2008 or 2010 and Windows Identity Foundation (WIF) v1.0 for .NET 3.5

Se è stata compilata un'applicazione in WIF v1.0 non esistono meccanismi per aggiornare automaticamente la configurazione dell'applicazione per l'uso di una nuova chiave.If you built an application on WIF v1.0, there is no provided mechanism to automatically refresh your application’s configuration to use a new key.

  • Modo più semplice : usare lo strumento FedUtil incluso in WIF SDK, che può recuperare il documento di metadati più recente e aggiornare la configurazione.Easiest way Use the FedUtil tooling included in the WIF SDK, which can retrieve the latest metadata document and update your configuration.
  • Aggiornare l'applicazione a .NET 4.5, che include la versione più recente di WIF nello spazio dei nomi System.Update your application to .NET 4.5, which includes the newest version of WIF located in the System namespace. Sarà quindi possibile usare Validating Issuer Name Registry (VINR) per eseguire gli aggiornamenti automatici della configurazione dell'applicazione.You can then use the Validating Issuer Name Registry (VINR) to perform automatic updates of the application’s configuration.
  • Eseguire un rollover manuale seguendo le istruzioni alla fine di questo documento.Perform a manual rollover as per the instructions at the end of this guidance document.

Istruzioni per usare FedUtil per aggiornare la configurazione:Instructions to use the FedUtil to update your configuration:

  1. Verificare di avere l'SDK WIF v1.0 installato nel computer di sviluppo per Visual Studio 2008 o 2010.Verify that you have the WIF v1.0 SDK installed on your development machine for Visual Studio 2008 or 2010. È possibile scaricarlo da qui se non è ancora installato.You can download it from here if you have not yet installed it.
  2. In Visual Studio aprire la soluzione, quindi fare clic con il pulsante destro del mouse sul progetto applicabile e scegliere Update federation metadata(Aggiorna metadati federazione).In Visual Studio, open the solution, and then right-click the applicable project and select Update federation metadata. Se questa opzione non è disponibile, FedUtil o l'SDK WIF v1.0 non è stato installato.If this option is not available, FedUtil and/or the WIF v1.0 SDK has not been installed.
  3. Al prompt selezionare Aggiorna per iniziare l'aggiornamento dei metadati della federazione.From the prompt, select Update to begin updating your federation metadata. Se si ha accesso all'ambiente server in cui è ospitata l'applicazione, è possibile usare facoltativamente l' utilità di pianificazione dell'aggiornamento automatico dei metadatidi FedUtil.If you have access to the server environment where the application is hosted, you can optionally use FedUtil’s automatic metadata update scheduler.
  4. Fare clic su Fine per completare il processo di aggiornamento.Click Finish to complete the update process.

API / applicazioni Web che proteggono le risorse usando qualsiasi altra libreria o con implementazione manuale di qualsiasi protocollo supportatoWeb applications / APIs protecting resources using any other libraries or manually implementing any of the supported protocols

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.If you are using some other library or manually implemented any of the supported protocols, you'll need to review the library or your implementation to ensure that the key is being retrieved from either the OpenID Connect discovery document or the federation metadata document. 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.One way to check for this is to do a search in your code or the library's code for any calls out to either the OpenID discovery document or the federation metadata document.

Se la chiave è archiviata in una posizione qualsiasi o è hardcoded nell'applicazione, è possibile recuperarla manualmente e aggiornarla di conseguenza eseguendo un rollover manuale in base alle istruzioni disponibili alla fine di questo documento.If they key is being stored somewhere or hardcoded in your application, you can manually retrieve the key and update it accordingly by perform a manual rollover as per the instructions at the end of this guidance document. È vivamente consigliato ottimizzare l'applicazione per il supporto del rollover automatico usando uno degli approcci descritti in questo articolo per evitare interruzioni future e sovraccarichi se Azure AD aumenta la cadenza di rollover o esegue un rollover di emergenza fuori programma.It is strongly encouraged that you enhance your application to support automatic rollover using any of the approaches outline in this article to avoid future disruptions and overhead if Azure AD increases it's rollover cadence or has an emergency out-of-band rollover.

Come testare l'applicazione per stabilire se sarà interessataHow to test your application to determine if it will be affected

È possibile verificare se l'applicazione supporta il rollover automatico della chiave scaricando gli script e seguendo le istruzioni contenute in questo repository GitHubYou can validate whether your application supports automatic key rollover by downloading the scripts and following the instructions in this GitHub repository.

Come eseguire un rollover manuale se l'applicazione non supporta il rollover automaticoHow to perform a manual rollover if you application does not support automatic rollover

Se l'applicazione non supporta il rollover automatico, sarà necessario stabilire un processo che monitori periodicamente le chiavi di firma di Azure AD ed esegua un rollover manuale di conseguenza.If your application does not support automatic rollover, you will need to establish a process that periodically monitors Azure AD's signing keys and performs a manual rollover accordingly. Questo repository GitHub contiene gli script e le istruzioni necessarie.This GitHub repository contains scripts and instructions on how to do this.