Rollover för signeringsnyckel i Microsofts identitetsplattform

  • Artikel

I den här artikeln beskrivs vad du behöver veta om de offentliga nycklar som används av Microsofts identitetsplattform för att signera säkerhetstoken. Det är viktigt att observera att dessa nycklar rullas över regelbundet och, i en nödsituation, kan rullas över omedelbart. Alla program som använder Microsofts identitetsplattform ska kunna hantera nyckelåterställningen programmatiskt. Du kommer att förstå hur nycklarna fungerar, hur du utvärderar effekten av återställningen till ditt program och hur du uppdaterar programmet eller upprättar en periodisk manuell rollover-process för att hantera nyckelåterställning om det behövs.

Översikt över signeringsnycklar i Microsofts identitetsplattform

Microsofts identitetsplattform använder kryptering med offentlig nyckel som bygger på branschstandarder för att upprätta förtroende mellan sig själv och de program som använder den. I praktiken fungerar detta på följande sätt: Microsofts identitetsplattform använder en signeringsnyckel som består av ett offentligt och privat nyckelpar. När en användare loggar in på ett program som använder Microsofts identitetsplattform för autentisering skapar Microsofts identitetsplattform en säkerhetstoken som innehåller information om användaren. Den här token signeras av Microsofts identitetsplattform med dess privata nyckel innan den skickas tillbaka till programmet. För att verifiera att token är giltig och kommer från Microsofts identitetsplattform måste programmet verifiera tokens signatur med hjälp av de offentliga nycklar som exponeras av Microsofts identitetsplattform som finns i klientorganisationens OpenID-Anslut identifieringsdokument eller SAML/WS-Fed federationsmetadatadokument.

I säkerhetssyfte rullar Microsofts identitetsplattform signeringsnyckeln regelbundet och, i händelse av en nödsituation, kan rullas över omedelbart. Det finns ingen uppsättning eller garanterad tid mellan dessa nyckelvalsar – alla program som integreras med Microsofts identitetsplattform bör vara beredda att hantera en nyckelåterställningshändelse oavsett hur ofta den kan inträffa. Om programmet inte hanterar plötsliga uppdateringar och försöker använda en nyckel som har upphört att gälla för att verifiera signaturen på en token avvisar programmet token felaktigt. Det är bästa praxis att kontrollera uppdateringar var 24:e timme med begränsade (högst en gång var femte minut) omedelbara uppdateringar av nyckeldokumentet om en token påträffas som inte verifieras med nycklarna i programmets cacheminne.

Det finns alltid fler än en giltig nyckel i OpenID-Anslut identifieringsdokumentet och federationsmetadatadokumentet. Ditt program bör vara redo att använda alla nycklar som anges i dokumentet, eftersom en nyckel kan rullas snart, en annan kan vara dess ersättning och så vidare. Antalet nycklar som finns kan ändras över tid baserat på den interna arkitekturen för Microsofts identitetsplattform eftersom vi stöder nya plattformar, nya moln eller nya autentiseringsprotokoll. Varken ordningen på nycklarna i JSON-svaret eller i vilken ordning de exponerades bör betraktas som meningsfulla för din app.

Program som endast stöder en enda signeringsnyckel, eller program som kräver manuella uppdateringar av signeringsnycklarna, är i sig mindre säkra och mindre tillförlitliga. De bör uppdateras för att använda standardbibliotek för att säkerställa att de alltid använder uppdaterade signeringsnycklar, bland andra metodtips.

Så här utvärderar du om ditt program kommer att påverkas och vad du ska göra åt det

Hur ditt program hanterar nyckelåterställning beror på variabler som typ av program eller vilket identitetsprotokoll och bibliotek som användes. I avsnitten nedan utvärderas om de vanligaste typerna av program påverkas av nyckelåterställning och ger vägledning om hur du uppdaterar programmet för att stödja automatisk återställning eller manuellt uppdatera nyckeln.

Den här vägledningen gäller inte för:

  • Program som lagts till från Microsoft Entra-programgalleriet (inklusive Anpassad) har separat vägledning om signeringsnycklar. Mer information.
  • Lokala program som publiceras via programproxy behöver inte bekymra sig om signeringsnycklar.

Interna klientprogram som har åtkomst till resurser

Program som bara har åtkomst till resurser (till exempel Microsoft Graph, KeyVault, Outlook API och andra Microsoft-API:er) hämtar bara en token och skickar den vidare till resursägaren. Eftersom de inte skyddar några resurser inspekterar de inte token och behöver därför inte se till att den är korrekt signerad.

Interna klientprogram, oavsett om de är stationära eller mobila, tillhör den här kategorin och påverkas därför inte av övergången.

Webbprogram/API:er som har åtkomst till resurser

Program som endast har åtkomst till resurser (till exempel Microsoft Graph, KeyVault, Outlook API och andra Microsoft-API:er) hämtar bara en token och skickar den vidare till resursägaren. Eftersom de inte skyddar några resurser inspekterar de inte token och behöver därför inte se till att den är korrekt signerad.

Webbprogram och webb-API:er som använder flödet endast för appar (klientautentiseringsuppgifter/klientcertifikat) för att begära token ingår i den här kategorin och påverkas därför inte av övergången.

Webbprogram/API:er som skyddar resurser och skapas med Hjälp av Azure App Services

Funktionerna för autentisering/auktorisering i Azure App Services (EasyAuth) har redan den logik som krävs för att hantera nyckelåterställning automatiskt.

Webbprogram/API:er som skyddar resurser med hjälp av ASP.NET OWIN OpenID Anslut, WS-Fed eller WindowsAzureActiveDirectoryBearerAuthentication mellanprogram

Om ditt program använder ASP.NET OWIN OpenID-Anslut, WS-Fed eller WindowsAzureActiveDirectoryBearerAuthentication mellanprogram, har det redan den logik som krävs för att hantera nyckelåterställning automatiskt.

Du kan bekräfta att ditt program använder något av dessa genom att leta efter något av följande kodfragment i programmets Startup.cs- eller Startup.Auth.cs-filer.

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

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

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

Webbprogram/API:er som skyddar resurser med hjälp av .NET Core OpenID Anslut eller JwtBearerAuthentication mellanprogram

Om ditt program använder ASP.NET OWIN OpenID-Anslut eller JwtBearerAuthentication-mellanprogram har det redan den logik som krävs för att hantera nyckelåterställning automatiskt.

Du kan bekräfta att programmet använder något av dessa genom att leta efter något av följande kodavsnitt i programmets Startup.cs eller Startup.Auth.cs

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

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

Webbprogram/API:er som skyddar resurser med hjälp av modulen Node.js passport-azure-ad

Om ditt program använder modulen Node.js passport-ad har det redan den logik som krävs för att hantera nyckelåterställning automatiskt.

Du kan bekräfta att ditt program passport-ad genom att söka efter följande kodfragment i programmets app.js

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

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

Webbprogram/API:er som skyddar resurser och skapas med Visual Studio 2015 eller senare

Om ditt program skapades med hjälp av en webbprogrammall i Visual Studio 2015 eller senare och du valde Arbets- eller skolkonton från menyn Ändra autentisering har det redan den logik som krävs för att hantera nyckelåterställning automatiskt. Den här logiken, inbäddad i OWIN OpenID Anslut mellanprogram, hämtar och cachelagrar nycklarna från OpenID-Anslut identifieringsdokumentet och uppdaterar dem regelbundet.

Om du har lagt till autentisering i lösningen manuellt kanske programmet inte har den nödvändiga logiken för nyckelåterställning. Du kan skriva det själv eller följa stegen i webbprogram/API:er med hjälp av andra bibliotek eller manuellt implementera något av de protokoll som stöds.

Webbprogram som skyddar resurser och skapas med Visual Studio 2013

Om ditt program skapades med hjälp av en webbprogrammall i Visual Studio 2013 och du valde Organisationskonton på menyn Ändra autentisering har det redan den logik som krävs för att hantera nyckelåterställning automatiskt. Den här logiken lagrar organisationens unika identifierare och signeringsnyckelinformationen i två databastabeller som är associerade med projektet. Du hittar anslutningssträng för databasen i projektets Web.config-fil.

Om du har lagt till autentisering i lösningen manuellt kanske programmet inte har den nödvändiga logiken för nyckelåterställning. Du måste skriva det själv eller följa stegen i webbprogram/API:er med hjälp av andra bibliotek eller manuellt implementera något av de protokoll som stöds..

Följande steg hjälper dig att kontrollera att logiken fungerar korrekt i ditt program.

  1. Öppna lösningen i Visual Studio 2013 och välj sedan på fliken Serverutforskaren i det högra fönstret.
  2. Expandera Data Anslut ions, Standard Anslut ion och sedan Tabeller. Leta upp tabellen IssuingAuthorityKeys, högerklicka på den och välj sedan Visa tabelldata.
  3. I tabellen IssuingAuthorityKeys finns det minst en rad, vilket motsvarar tumavtrycksvärdet för nyckeln. Ta bort alla rader i tabellen.
  4. Högerklicka på tabellen Klientorganisationer och välj sedan Visa tabelldata.
  5. I tabellen Klientorganisationer finns det minst en rad, vilket motsvarar en unik katalogklientidentifierare. Ta bort alla rader i tabellen. Om du inte tar bort raderna i både tabellen Klientorganisationer och tabellen IssuingAuthorityKeys får du ett fel vid körning.
  6. Skapa och kör programmet. När du har loggat in på ditt konto kan du stoppa programmet.
  7. Gå tillbaka till Server Explorer och titta på värdena i tabellen UtfärdandeAuthorityKeys och Klientorganisationer . Du kommer att märka att de har fyllts i automatiskt med lämplig information från federationsmetadatadokumentet.

Webb-API:er som skyddar resurser och skapas med Visual Studio 2013

Om du skapade ett webb-API-program i Visual Studio 2013 med hjälp av webb-API-mallen och sedan valde Organisationskonton på menyn Ändra autentisering har du redan den logik som krävs i ditt program.

Om du har konfigurerat autentisering manuellt följer du anvisningarna nedan för att lära dig hur du konfigurerar webb-API:et för att automatiskt uppdatera dess nyckelinformation.

Följande kodfragment visar hur du hämtar de senaste nycklarna från dokumentet med federationsmetadata och sedan använder JWT-tokenhanteraren för att verifiera token. Kodfragmentet förutsätter att du använder din egen cachelagringsmekanism för att bevara nyckeln för att verifiera framtida token från Microsofts identitetsplattform, oavsett om det finns i en databas, konfigurationsfil eller någon annanstans.

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

Webbprogram som skyddar resurser och skapas med Visual Studio 2012

Om ditt program skapades i Visual Studio 2012 använde du förmodligen identitets- och åtkomstverktyget för att konfigurera programmet. Det är också troligt att du använder VINR (Validating Issuer Name Registry). VINR ansvarar för att underhålla information om betrodda identitetsprovidrar (Microsofts identitetsplattform) och de nycklar som används för att verifiera token som utfärdats av dem. VINR gör det också enkelt att automatiskt uppdatera nyckelinformationen som lagras i en Web.config-fil genom att ladda ned det senaste federationsmetadatadokumentet som är associerat med din katalog, kontrollera om konfigurationen är inaktuell med det senaste dokumentet och uppdatera programmet för att använda den nya nyckeln efter behov.

Om du har skapat ditt program med hjälp av något av de kodexempel eller genomgångsdokumentation som tillhandahålls av Microsoft ingår redan logiken för nyckelåterställning i projektet. Du kommer att märka att koden nedan redan finns i projektet. Om ditt program inte redan har den här logiken följer du stegen nedan för att lägga till den och kontrollera att den fungerar korrekt.

  1. I Solution Explorer lägger du till en referens till sammansättningen System.IdentityModel för lämpligt projekt.
  2. Öppna filen Global.asax.cs och lägg till följande med hjälp av direktiv: 
    using System.Configuration;
using System.IdentityModel.Tokens;
  3. Lägg till följande metod i filen Global.asax.cs : 
    protected void RefreshValidationSettings()
{
 string configPath = AppDomain.CurrentDomain.BaseDirectory + "\\" + "Web.config";
 string metadataAddress =
               ConfigurationManager.AppSettings["ida:FederationMetadataLocation"];
 ValidatingIssuerNameRegistry.WriteToConfig(metadataAddress, configPath);
}
  4. Anropa metoden RefreshValidation Inställningar() i metoden Application_Start() i Global.asax.cs enligt följande:
    protected void Application_Start()
{
 AreaRegistration.RegisterAllAreas();
 ...
 RefreshValidationSettings();
}

När du har följt de här stegen uppdateras programmets Web.config med den senaste informationen från dokumentet med federationsmetadata, inklusive de senaste nycklarna. Den här uppdateringen sker varje gång programpoolen återanvänds i IIS. som standard är IIS inställt på att återanvända program var 29:e timme.

Följ stegen nedan för att kontrollera att nyckelåterställningslogik fungerar.

  1. När du har kontrollerat att programmet använder koden ovan öppnar du filen Web.config och navigerar till <blocket issuerNameRegistry> och letar specifikt efter följande rader: 
    <issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry">
     <authority name="https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/">
       <keys>
         <add thumbprint="3A38FA984E8560F19AADC9F86FE9594BB6AD049B" />
       </keys>
  2. I inställningen <lägg till tumavtryck=""> ändrar du tumavtrycksvärdet genom att ersätta alla tecken med ett annat. Spara filen Web.config.
  3. Skapa programmet och kör det sedan. Om du kan slutföra inloggningsprocessen uppdaterar programmet nyckeln genom att ladda ned nödvändig information från katalogens federationsmetadatadokument. Om du har problem med att logga in kontrollerar du att ändringarna i ditt program är korrekta genom att läsa artikeln Lägga till inloggning i ditt webbprogram med hjälp av Microsofts identitetsplattform eller ladda ned och inspektera följande kodexempel: Molnprogram för flera klientorganisationer för Microsoft Entra.

Webbprogram/API:er som skyddar resurser med andra bibliotek eller implementerar något av protokollen som stöds manuellt

Om du använder något annat bibliotek eller manuellt implementerar något av de protokoll som stöds måste du granska biblioteket eller implementeringen för att säkerställa att nyckeln hämtas från antingen OpenID-Anslut identifieringsdokument eller federationsmetadatadokumentet. Ett sätt att söka efter detta är att söka i koden eller bibliotekets kod efter eventuella anrop till antingen OpenID-identifieringsdokumentet eller federationsmetadatadokumentet.

Om nyckeln lagras någonstans eller hårdkodas i ditt program kan du manuellt hämta nyckeln och uppdatera den genom att utföra en manuell rollover enligt anvisningarna i slutet av det här vägledningsdokumentet. Det är starkt uppmuntrat att du förbättrar ditt program för att stödja automatisk rollover med någon av de metoder som beskrivs i den här artikeln för att undvika framtida störningar och omkostnader om Microsofts identitetsplattform ökar dess rollover-takt eller har en nödutrullning.

Så här testar du programmet för att avgöra om det kommer att påverkas

Du kan kontrollera om ditt program stöder automatisk nyckelåterställning med hjälp av följande PowerShell-skript.

Om du vill kontrollera och uppdatera signeringsnycklar med PowerShell behöver du POWERShell-modulen MSIdentityTools .

  1. Installera MSIdentityTools PowerShell-modulen:

    Install-Module -Name MSIdentityTools

  2. Logga in med kommandot Anslut-MgGraph med ett administratörskonto för att godkänna de nödvändiga omfången:

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

  3. Hämta listan över tillgängliga tumavtryck för signeringsnyckeln:

    Get-MsIdSigningKeyThumbprint

  4. Välj något av tumavtrycken och konfigurera Microsoft Entra-ID för att använda den nyckeln med ditt program (hämta app-ID:t från administrationscentret för Microsoft Entra):

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

  5. Testa webbprogrammet genom att logga in för att hämta en ny token. Den viktiga uppdateringsändringen är omedelbar, men se till att du använder en ny webbläsarsession (med till exempel Internet Explorers "InPrivate", Chromes "Incognito" eller Firefox"Private"-läge) för att säkerställa att du får en ny token.

  6. För var och en av tumavtrycken för den returnerade signeringsnyckeln kör du cmdleten Update-MsIdApplicationSigningKeyThumbprint och testar inloggningsprocessen för webbprogrammet.

  7. Om webbprogrammet signerar dig korrekt stöder det automatisk återställning. Om den inte gör det ändrar du programmet så att det stöder manuell återställning. Mer information finns i Upprätta en manuell rollover-process.

  8. Kör följande skript för att återgå till normalt beteende:

    Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default

Så här utför du en manuell rollover om programmet inte har stöd för automatisk rollover

Om ditt program inte stöder automatisk rollover måste du upprätta en process som regelbundet övervakar Microsofts identitetsplattform signeringsnycklar och utför en manuell rollover i enlighet med detta.

Om du vill kontrollera och uppdatera signeringsnycklar med PowerShell behöver MSIdentityTools du PowerShell-modulen.

  1. MSIdentityTools Installera PowerShell-modulen:

    Install-Module -Name MSIdentityTools

  2. Hämta den senaste signeringsnyckeln (hämta klient-ID:t från administrationscentret för Microsoft Entra):

    Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest

  3. Jämför den här nyckeln med nyckeln som programmet för närvarande är hårdkodat eller konfigurerat att använda.

  4. Om den senaste nyckeln skiljer sig från den nyckel som programmet använder laddar du ned den senaste signeringsnyckeln:

    Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>

  5. Uppdatera programmets kod eller konfiguration för att använda den nya nyckeln.

  6. Konfigurera Microsoft Entra-ID för att använda den senaste nyckeln med ditt program (hämta app-ID:t från administrationscentret för Microsoft Entra):

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

  7. Testa webbprogrammet genom att logga in för att hämta en ny token. Den viktiga uppdateringsändringen är omedelbar, men se till att du använder en ny webbläsarsession (med till exempel Internet Explorers "InPrivate", Chromes "Incognito" eller Firefox"Private"-läge) för att säkerställa att du får en ny token.

  8. Om du har problem kan du återgå till den tidigare nyckeln som du använde och kontakta Azure-supporten:

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

  9. När du har uppdaterat programmet för att stödja manuell återställning återgår du till normalt beteende:

    Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default