Rollover van ondertekeningssleutel in het Microsoft Identity Platform

In dit artikel wordt beschreven wat u moet weten over de openbare sleutels die door het Microsoft Identity Platform worden gebruikt om beveiligingstokens te ondertekenen. Het is belangrijk om te weten dat deze sleutels periodiek worden overgezet en, in noodgevallen, onmiddellijk kunnen worden overgezet. Alle toepassingen die gebruikmaken van het Microsoft Identity Platform, moeten het rollover-proces van de sleutel programmatisch kunnen verwerken. U begrijpt hoe de sleutels werken, hoe u de impact van de rollover naar uw toepassing kunt beoordelen. U leert ook hoe u uw toepassing bijwerkt of een periodiek handmatig rolloverproces tot stand brengt om sleutelrollover indien nodig af te handelen.

Overzicht van ondertekeningssleutels in het Microsoft Identity Platform

Het Microsoft Identity Platform maakt gebruik van openbare-sleutelcryptografie die is gebouwd op industriestandaarden om vertrouwen tussen zichzelf en de toepassingen die het gebruiken te vestigen. In de praktijk werkt dit op de volgende manier: Het Microsoft Identity Platform maakt gebruik van een ondertekeningssleutel die bestaat uit een openbaar en persoonlijk sleutelpaar. Wanneer een gebruiker zich aanmeldt bij een toepassing die gebruikmaakt van het Microsoft Identity Platform voor verificatie, maakt het Microsoft Identity Platform een beveiligingstoken dat informatie over de gebruiker bevat. Dit token wordt ondertekend door het Microsoft Identity Platform met behulp van de persoonlijke sleutel voordat deze naar de toepassing wordt verzonden. Om te controleren of het token geldig is en afkomstig is van het Microsoft Identity Platform, moet de toepassing de handtekening van het token valideren met behulp van de openbare sleutels die beschikbaar zijn gemaakt door het Microsoft Identity Platform dat is opgenomen in het OpenID Connect-detectiedocument van de tenant of saml/WS-Fed-federatiemetagegevensdocument.

Voor veiligheidsdoeleinden wordt de ondertekeningssleutel van het Microsoft Identity Platform periodiek geïmplementeerd en kan in geval van nood onmiddellijk worden overgezet. Er is geen vaste of gegarandeerde tijd tussen deze sleutelrollen. Elke toepassing die kan worden geïntegreerd met het Microsoft Identity Platform, moet worden voorbereid om een belangrijke rollover-gebeurtenis af te handelen, ongeacht hoe vaak het kan gebeuren. Als uw toepassing geen plotselinge vernieuwingen afhandelt en een verlopen sleutel probeert te gebruiken om de handtekening op een token te verifiëren, weigert uw toepassing het token onjuist. Het is raadzaam om standaardbibliotheken te gebruiken om ervoor te zorgen dat belangrijke metagegevens correct worden vernieuwd en up-to-date blijven. In gevallen waarin standaardbibliotheken niet worden gebruikt, moet u ervoor zorgen dat de implementatie de sectie met aanbevolen procedures volgt.

Er is altijd meer dan één geldige sleutel beschikbaar in het OpenID Connect-detectiedocument en het document met federatieve metagegevens. Uw toepassing moet voorbereid zijn op het gebruik van alle sleutels die zijn opgegeven in het document, omdat de ene sleutel binnenkort kan worden geïmplementeerd, een andere sleutel kan worden vervangen, enzovoort. Het aantal sleutels dat aanwezig is, kan in de loop van de tijd veranderen op basis van de interne architectuur van het Microsoft Identity Platform, omdat we nieuwe platforms, nieuwe clouds of nieuwe verificatieprotocollen ondersteunen. De volgorde van de sleutels in het JSON-antwoord en de volgorde waarin ze werden weergegeven, moet niet als zinvol worden beschouwd voor uw toepassing. Raadpleeg RFC7517 voor meer informatie over de gegevensstructuur van de JSON-websleutel.

Toepassingen die slechts één ondertekeningssleutel ondersteunen of toepassingen waarvoor handmatige updates van de ondertekeningssleutels nodig zijn, zijn inherent minder veilig en minder betrouwbaar. Ze moeten worden bijgewerkt om standaardbibliotheken te gebruiken om ervoor te zorgen dat ze altijd up-to-date ondertekeningssleutels gebruiken, en andere aanbevolen procedures.

Aanbevolen procedures voor het opslaan van metagegevens in cache en validatie van sleutels

• Sleutels detecteren met behulp van het tenantspecifieke eindpunt, zoals beschreven in OpenID Connect (OIDC) en federatiemetagegevens
• Zelfs als uw toepassing wordt geïmplementeerd in meerdere tenants, is het raadzaam om sleutels altijd onafhankelijk te detecteren en op te slaan voor elke tenant die door de toepassing wordt gebruikt (met behulp van het tenantspecifieke eindpunt). Een sleutel die tegenwoordig gebruikelijk is voor tenants, kan in de toekomst verschillen tussen tenants.
• Gebruik het onderstaande caching-algoritme om ervoor te zorgen dat de caching tolerant en veilig is

Algoritme voor het opslaan van metagegevens van sleutels:

Onze standaardbibliotheken implementeren robuuste en veilige caching van sleutels. Het is raadzaam om ze te gebruiken om subtiele defecten in de implementatie te voorkomen. Voor aangepaste implementaties is dit het ruwe algoritme:

Algemene overwegingen:

• De service die tokens valideert, moet een cache hebben waarmee veel afzonderlijke sleutels kunnen worden opgeslagen (10-1000).
• De sleutels moeten afzonderlijk in de cache worden opgeslagen met behulp van de sleutel-id ('kid' in de metagegevensspecificatie van OIDC-sleutels) als cachesleutel.
• De time-to-live van sleutels in de cache moet worden geconfigureerd tot 24 uur, waarbij elke uur vernieuwingen plaatsvinden. Dit zorgt ervoor dat het systeem snel kan reageren op sleutels die worden verwijderd, maar heeft voldoende cacheduur om niet te worden beïnvloed door problemen bij het ophalen van sleutels.
• De sleutels moeten worden vernieuwd:
  • Eenmaal bij het opstarten van het proces of wanneer de cache leeg is
  • Periodiek (aanbevolen om de 1 uur) als achtergrondtaak
  • Dynamisch als een ontvangen token is ondertekend met een onbekende sleutel (onbekend kind of netjes in de header)

KeyRefresh-procedure (conceptueel algoritme van IdentityModel)

1. Initialisatie

   Configuration Manager is ingesteld met een specifiek adres voor het ophalen van configuratiegegevens en de benodigde interfaces om deze gegevens op te halen en te valideren.

2. Configuratiecontrole

   Voordat nieuwe gegevens worden opgehaald, controleert het systeem eerst of de bestaande gegevens nog geldig zijn op basis van een vooraf gedefinieerd vernieuwingsinterval.

3. Ophalen van gegevens Als de gegevens verouderd of ontbreken, wordt het systeem vergrendeld om ervoor te zorgen dat slechts één thread de nieuwe gegevens ophaalt om duplicatie (en threaduitputting) te voorkomen. Het systeem probeert vervolgens de meest recente configuratiegegevens op te halen van een opgegeven eindpunt.

4. Validatie

   Zodra de nieuwe gegevens zijn opgehaald, wordt deze gevalideerd om ervoor te zorgen dat deze voldoet aan de vereiste standaarden en niet beschadigd is. De metagegevens worden alleen geaccepteerd wanneer een binnenkomende aanvraag is gevalideerd met de nieuwe sleutels.

5. Foutafhandeling

   Als er fouten optreden tijdens het ophalen van gegevens, worden ze geregistreerd. Het systeem blijft werken met de laatst bekende goede configuratie als er geen nieuwe gegevens kunnen worden opgehaald

6. Automatische updates Het systeem controleert en werkt de configuratiegegevens automatisch bij op basis van het vernieuwingsinterval (raad 12 uur aan met een jitter van plus of min 1 h). Het kan ook handmatig een update aanvragen indien nodig, zodat de gegevens altijd actueel zijn.

7. Validatie van een token met een nieuwe sleutel Als een token binnenkomt met een ondertekeningssleutel die nog niet bekend is uit de configuratie, probeert het systeem de configuratie op te halen met een synchronisatieaanroep op het dynamische pad voor het afhandelen van nieuwe sleutels in metagegevens buiten de normale verwachte updates (maar niet vaker dan 5 minuten)

Deze aanpak zorgt ervoor dat het systeem altijd gebruikmaakt van de meest recente en geldige configuratiegegevens, terwijl fouten correct worden verwerkt en redundante bewerkingen worden vermeden.

De .NET-implementatie van dit algoritme is beschikbaar via BaseConfigurationManager. Het is onderhevig aan wijzigingen op basis van tolerantie en beveiligingsevaluaties. Zie hier ook een uitleg

KeyRefresh-procedure (pseudocode):

In deze procedure wordt een globale tijdstempel (lastSuccessfulRefreshTime) gebruikt om te voorkomen dat sleutels te vaak worden vernieuwd.

• 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
}

Procedure voor het opstarten van de service:

• KeyRefresh om de sleutels bij te werken
• Een achtergrondtaak starten die KeyRefresh elk uur aanroept

TokenValidation-procedure voor het valideren van de sleutel (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
    }
  }
}

Beoordelen of uw toepassing wordt beïnvloed en wat u ermee kunt doen

Hoe uw toepassing sleutelrollover afhandelt, is afhankelijk van variabelen zoals het type toepassing of welk identiteitsprotocol en welke bibliotheek is gebruikt. In de onderstaande secties wordt beoordeeld of de meest voorkomende typen toepassingen worden beïnvloed door de sleutelrollover en richtlijnen bieden voor het bijwerken van de toepassing ter ondersteuning van automatische rollover of het handmatig bijwerken van de sleutel.

• Systeemeigen clienttoepassingen die toegang hebben tot resources
• Webtoepassingen/API's die toegang hebben tot resources
• Webtoepassingen/API's die resources beveiligen en gebouwd met behulp van Azure-app Services
• Webtoepassingen/API's die resources beveiligen met behulp van ASP.NET OWIN OpenID Connect, WS-Fed of WindowsAzureActiveDirectoryBearerAuthentication middleware
• Webtoepassingen/API's die resources beveiligen met behulp van ASP.NET Core OpenID Connect of JwtBearerAuthentication middleware
• Webtoepassingen/API's die resources beveiligen met behulp van Node.js-module passport-azure-ad
• Webtoepassingen/API's voor het beveiligen van resources en gemaakt met Visual Studio 2015 of hoger
• Webtoepassingen die resources beveiligen en maken met Visual Studio 2013
• Web-API's voor het beveiligen van resources en gemaakt met Visual Studio 2013
• Webtoepassingen die resources beveiligen en maken met Visual Studio 2012
• Webtoepassingen/API's die resources beveiligen met behulp van andere bibliotheken of handmatig een van de ondersteunde protocollen implementeren

Deze richtlijnen zijn niet van toepassing op:

• Toepassingen die zijn toegevoegd vanuit de Microsoft Entra Application Gallery (inclusief Aangepast) hebben afzonderlijke richtlijnen met betrekking tot ondertekeningssleutels. Meer informatie.
• On-premises toepassingen die zijn gepubliceerd via de toepassingsproxy hoeven zich geen zorgen te maken over ondertekeningssleutels.

Systeemeigen clienttoepassingen die toegang hebben tot resources

Toepassingen die alleen toegang hebben tot resources (bijvoorbeeld Microsoft Graph, KeyVault, Outlook API en andere Microsoft-API's), verkrijgen alleen een token en geven dit door aan de eigenaar van de resource. Aangezien ze geen resources beveiligen, controleren ze het token niet en hoeven ze er daarom niet voor te zorgen dat het goed is ondertekend.

Systeemeigen clienttoepassingen, zowel desktop als mobiel, vallen in deze categorie en worden dus niet beïnvloed door de rollover.

Webtoepassingen/API's die toegang hebben tot resources

Toepassingen die alleen toegang hebben tot resources (zoals Microsoft Graph, KeyVault, Outlook-API en andere Microsoft-API's), verkrijgen alleen een token en geven dit door aan de resource-eigenaar. Aangezien ze geen resources beveiligen, controleren ze het token niet en hoeven ze er daarom niet voor te zorgen dat het goed is ondertekend.

Webtoepassingen en web-API's die gebruikmaken van de stroom alleen-apps (clientreferenties/clientcertificaat) om tokens aan te vragen, vallen in deze categorie en worden dus niet beïnvloed door de rollover.

Webtoepassingen/API's die resources beveiligen en gebouwd met behulp van Azure-app Services

Azure-app De functionaliteit verificatie/autorisatie (EasyAuth) van services beschikt al over de benodigde logica voor het automatisch afhandelen van sleutelrollover.

Webtoepassingen/API's die resources beveiligen met behulp van ASP.NET OWIN OpenID Connect, WS-Fed of WindowsAzureActiveDirectoryBearerAuthentication middleware

Als uw toepassing gebruikmaakt van de ASP.NET OWIN OpenID Connect, WS-Fed of WindowsAzureActiveDirectoryBearerAuthentication middleware, beschikt deze al over de benodigde logica voor het automatisch verwerken van sleutelrollover.

U kunt bevestigen dat uw toepassing een van deze gebruikt door te zoeken naar een van de volgende codefragmenten in de Startup.cs- of Startup.Auth.cs-bestanden van uw toepassing.

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

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

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

Webtoepassingen/API's die resources beveiligen met behulp van .NET Core OpenID Connect of JwtBearerAuthentication middleware

Als uw toepassing gebruikmaakt van de ASP.NET OWIN OpenID Connect- of JwtBearerAuthentication-middleware, beschikt deze al over de benodigde logica voor het automatisch afhandelen van sleutelrollover.

U kunt controleren of uw toepassing een van deze gebruikt door te zoeken naar een van de volgende fragmenten in de Startup.cs of Startup.Auth.cs van uw toepassing

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

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

Webtoepassingen/API's die resources beveiligen met behulp van Node.js passport-azure-ad module

Als uw toepassing gebruikmaakt van de Node.js passport-ad-module, beschikt deze al over de benodigde logica voor het automatisch afhandelen van sleutelrollover.

U kunt bevestigen dat uw toepassing passport-ad door te zoeken naar het volgende codefragment in de app.js van uw toepassing

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

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

Webtoepassingen/API's voor het beveiligen van resources en gemaakt met Visual Studio 2015 of hoger

Als uw toepassing is gebouwd met behulp van een webtoepassingssjabloon in Visual Studio 2015 of hoger en u werk- of schoolaccounts hebt geselecteerd in het menu Verificatie wijzigen, beschikt deze al over de benodigde logica om de sleutelrollover automatisch af te handelen. Deze logica, ingesloten in de OWIN OpenID Connect-middleware, haalt de sleutels op uit het OpenID Connect-detectiedocument en vernieuwt deze regelmatig.

Als u handmatig verificatie aan uw oplossing hebt toegevoegd, beschikt uw toepassing mogelijk niet over de benodigde logica voor sleutelrollover. U kunt het zelf schrijven of de stappen in webtoepassingen/API's volgen met behulp van andere bibliotheken of handmatig een van de ondersteunde protocollen implementeren.

Webtoepassingen die resources beveiligen en maken met Visual Studio 2013

Als uw toepassing is gebouwd met behulp van een webtoepassingssjabloon in Visual Studio 2013 en u organisatieaccounts hebt geselecteerd in het menu Verificatie wijzigen, beschikt deze al over de benodigde logica voor het automatisch afhandelen van sleutelrollover. Met deze logica worden de unieke id van uw organisatie en de informatie over de ondertekeningssleutel opgeslagen in twee databasetabellen die aan het project zijn gekoppeld. U vindt de verbindingsreeks voor de database in het web.config-bestand van het project.

Als u handmatig verificatie aan uw oplossing hebt toegevoegd, beschikt uw toepassing mogelijk niet over de benodigde logica voor sleutelrollover. U moet deze zelf schrijven of de stappen in webtoepassingen/API's volgen met behulp van andere bibliotheken of handmatig een van de ondersteunde protocollen implementeren.

Met de volgende stappen kunt u controleren of de logica goed werkt in uw toepassing.

1. Open de oplossing in Visual Studio 2013 en selecteer vervolgens op het tabblad Server Explorer in het rechtervenster.
2. Vouw gegevensverbindingen, DefaultConnection en vervolgens Tabellen uit. Zoek de tabel IssuingAuthorityKeys, klik er met de rechtermuisknop op en selecteer Tabelgegevens weergeven.
3. In de tabel IssuingAuthorityKeys is er ten minste één rij, die overeenkomt met de vingerafdrukwaarde voor de sleutel. Verwijder alle rijen in de tabel.
4. Klik met de rechtermuisknop op de tabel Tenants en selecteer Tabelgegevens weergeven.
5. In de tabel Tenants is er ten minste één rij die overeenkomt met een unieke maptenant-id. Verwijder alle rijen in de tabel. Als u de rijen in zowel de tabel Tenants als de tabel IssuingAuthorityKeys niet verwijdert, krijgt u tijdens runtime een fout.
6. Maak de toepassing en voer deze uit. Nadat u zich hebt aangemeld bij uw account, kunt u de toepassing stoppen.
7. Ga terug naar Server Explorer en bekijk de waarden in de tabel IssuingAuthorityKeys en Tenants . U ziet dat ze automatisch opnieuw zijn ingevuld met de juiste informatie uit het document met federatieve metagegevens.

Web-API's voor het beveiligen van resources en gemaakt met Visual Studio 2013

Als u een web-API-toepassing hebt gemaakt in Visual Studio 2013 met behulp van de web-API-sjabloon en vervolgens organisatieaccounts hebt geselecteerd in het menu Verificatie wijzigen, hebt u al de benodigde logica in uw toepassing.

Als u handmatig verificatie hebt geconfigureerd, volgt u de onderstaande instructies om te leren hoe u uw web-API configureert om de sleutelgegevens automatisch bij te werken.

In het volgende codefragment ziet u hoe u de meest recente sleutels kunt ophalen uit het document met federatieve metagegevens en vervolgens de JWT-tokenhandler gebruikt om het token te valideren. In het codefragment wordt ervan uitgegaan dat u uw eigen cachemechanisme gebruikt voor het behouden van de sleutel om toekomstige tokens van het Microsoft Identity Platform te valideren, ongeacht of dit zich in een database, configuratiebestand of elders bevindt.

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;
        }
    }
}

Webtoepassingen die resources beveiligen en maken met Visual Studio 2012

Als uw toepassing is gebouwd in Visual Studio 2012, hebt u waarschijnlijk het hulpprogramma Voor identiteit en toegang gebruikt om uw toepassing te configureren. Het is ook waarschijnlijk dat u het VINR (Validating Issuer Name Registry) gebruikt. De VINR is verantwoordelijk voor het onderhouden van informatie over vertrouwde id-providers (Microsoft Identity Platform) en de sleutels die worden gebruikt om tokens te valideren die door hen zijn uitgegeven. Met vinr kunt u de sleutelgegevens die zijn opgeslagen in een Web.config-bestand ook automatisch bijwerken door het meest recente document met federatieve metagegevens te downloaden dat aan uw directory is gekoppeld, te controleren of de configuratie verouderd is met het meest recente document en de toepassing zo nodig bij te werken om de nieuwe sleutel te gebruiken.

Als u uw toepassing hebt gemaakt met behulp van een van de codevoorbeelden of walkthrough-documentatie van Microsoft, is de logica voor de belangrijkste rollover al opgenomen in uw project. U ziet dat de onderstaande code al bestaat in uw project. Als uw toepassing deze logica nog niet heeft, volgt u de onderstaande stappen om deze toe te voegen en te controleren of deze correct werkt.

1. Voeg in Solution Explorer een verwijzing toe naar de System.IdentityModel-assembly voor het juiste project.
2. Open het bestand Global.asax.cs en voeg het volgende toe met behulp van instructies:

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

3. Voeg de volgende methode toe aan het bestand Global.asax.cs :

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

4. Roep de methode RefreshValidationSettings() aan in de methode Application_Start() in Global.asax.cs zoals wordt weergegeven:

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

Zodra u deze stappen hebt uitgevoerd, wordt de web.config van uw toepassing bijgewerkt met de meest recente informatie uit het document met federatieve metagegevens, inclusief de meest recente sleutels. Deze update vindt plaats telkens wanneer uw groep van toepassingen wordt gerecycled in IIS; IIS is standaard elke 29 uur ingesteld op recyclen van toepassingen.

Volg de onderstaande stappen om te controleren of de logica voor sleutelrollover werkt.

1. Nadat u hebt gecontroleerd of uw toepassing de bovenstaande code gebruikt, opent u het bestand Web.config en navigeert u naar het <blok issuerNameRegistry>, met name op zoek naar de volgende regels:

   <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. Wijzig in de <instelling add thumbprint=""> de vingerafdrukwaarde door een teken te vervangen door een ander teken. Sla het web.config-bestand op.
3. Bouw de toepassing en voer deze uit. Als u het aanmeldingsproces kunt voltooien, wordt de sleutel door uw toepassing bijgewerkt door de vereiste informatie te downloaden uit het document met federatieve metagegevens van uw directory. Als u problemen ondervindt met aanmelden, controleert u of de wijzigingen in uw toepassing juist zijn door het artikel Aanmelding toevoegen aan uw webtoepassing te lezen met behulp van het Microsoft Identity Platform-artikel of door het volgende codevoorbeeld te downloaden en te controleren: Multitenant Cloud Application for Microsoft Entra ID.

Webtoepassingen/API's die resources beveiligen met behulp van andere bibliotheken of handmatig een van de ondersteunde protocollen implementeren

Als u een andere bibliotheek gebruikt of een van de ondersteunde protocollen handmatig hebt geïmplementeerd, moet u de bibliotheek of uw implementatie controleren om ervoor te zorgen dat de sleutel wordt opgehaald uit het OpenID Connect-detectiedocument of het document met federatiemetagegevens. Een manier om dit te controleren, is door een zoekopdracht uit te voeren in uw code of de code van de bibliotheek voor aanroepen naar het OpenID-detectiedocument of het document met federatieve metagegevens.

Als de sleutel ergens of in code in uw toepassing wordt opgeslagen, kunt u de sleutel handmatig ophalen en dienovereenkomstig bijwerken door een handmatige rollover uit te voeren volgens de instructies aan het einde van dit richtlijnendocument. Het wordt ten zeerste aangeraden uw toepassing te verbeteren ter ondersteuning van automatische rollover met behulp van een van de benaderingen die in dit artikel worden beschreven om toekomstige onderbrekingen en overhead te voorkomen als het Microsoft Identity Platform de rolloverfrequentie verhoogt of een out-of-band rollover heeft.

Uw toepassing testen om te bepalen of deze wordt beïnvloed

U kunt controleren of uw toepassing automatische rollover van sleutels ondersteunt met behulp van de volgende PowerShell-scripts.

Als u ondertekeningssleutels wilt controleren en bijwerken met PowerShell, hebt u de POWERShell-module MSIdentityTools nodig.

1. Installeer de MSIdentityTools PowerShell-module:

   Install-Module -Name MSIdentityTools
   

2. Meld u aan met de opdracht Connect-MgGraph met een beheerdersaccount om toestemming te geven voor de vereiste bereiken:

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

3. Haal de lijst met beschikbare vingerafdruk van de ondertekeningssleutel op:

   Get-MsIdSigningKeyThumbprint
   

4. Kies een van de sleutelvingerafdrukken en configureer Microsoft Entra-id om die sleutel te gebruiken met uw toepassing (haal de app-id op uit het Microsoft Entra-beheercentrum):

   Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>
   

5. Test de webtoepassing door u aan te melden om een nieuw token op te halen. De wijziging van de sleutelupdate is onmiddellijk, maar zorg ervoor dat u een nieuwe browsersessie gebruikt (met bijvoorbeeld 'InPrivate' van Internet Explorer, chrome's 'Incognito' of de modus Privé van Firefox) om ervoor te zorgen dat u een nieuw token krijgt.

6. Voer voor elk van de geretourneerde vingerafdruk van de ondertekeningssleutel de Update-MsIdApplicationSigningKeyThumbprint cmdlet uit en test het aanmeldingsproces van uw webtoepassing.

7. Als de webtoepassing u correct aanmeldt, ondersteunt deze automatische rollover. Als dit niet het probleem is, wijzigt u uw toepassing ter ondersteuning van handmatige rollover. Bekijk het opzetten van een handmatig rollover-proces voor meer informatie.

8. Voer het volgende script uit om terug te keren naar normaal gedrag:

   Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
   

Een handmatige rollover uitvoeren als uw toepassing geen ondersteuning biedt voor automatische rollover

Als uw toepassing automatische rollover niet ondersteunt, moet u een proces opzetten waarmee de ondertekeningssleutels van het Microsoft Identity Platform periodiek worden bewaakt en dienovereenkomstig een handmatige rollover wordt uitgevoerd.

Als u ondertekeningssleutels wilt controleren en bijwerken met PowerShell, hebt u de MSIdentityTools PowerShell-module nodig.

1. Installeer de MSIdentityTools PowerShell-module:

   Install-Module -Name MSIdentityTools
   

2. Haal de meest recente ondertekeningssleutel op (haal de tenant-id op uit het Microsoft Entra-beheercentrum):

   Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
   

3. Vergelijk deze sleutel met de sleutel die uw toepassing momenteel in code heeft vastgelegd of geconfigureerd voor gebruik.

4. Als de meest recente sleutel verschilt van de sleutel die uw toepassing gebruikt, downloadt u de meest recente ondertekeningssleutel:

   Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
   

5. Werk de code of configuratie van uw toepassing bij om de nieuwe sleutel te gebruiken.

6. Configureer De Microsoft Entra-id om die meest recente sleutel met uw toepassing te gebruiken (haal de app-id op uit het Microsoft Entra-beheercentrum):

   Get-MsIdSigningKeyThumbprint -Latest | Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId>
   

7. Test de webtoepassing door u aan te melden om een nieuw token op te halen. De wijziging van de sleutelupdate is onmiddellijk, maar zorg ervoor dat u een nieuwe browsersessie gebruikt om ervoor te zorgen dat u een nieuw token krijgt uitgegeven. Gebruik bijvoorbeeld 'InPrivate' van Microsoft Edge, de 'Incognito' van Chrome of de modus Privé van Firefox.

8. Als u problemen ondervindt, gaat u terug naar de vorige sleutel die u gebruikte en neemt u contact op met ondersteuning voor Azure:

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

9. Nadat u uw toepassing hebt bijgewerkt ter ondersteuning van handmatige rollover, gaat u terug naar normaal gedrag:

   Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default