Sdílet prostřednictvím


Vrácení podpisového klíče na platformě Microsoft Identity Platform

Tento článek popisuje, co potřebujete vědět o veřejných klíčích používaných platformou Microsoft Identity Platform k podepisování tokenů zabezpečení. Je důležité si uvědomit, že tyto klíče se pravidelně převrácejí a v nouzovém stavu by se mohly okamžitě vrátit. Všechny aplikace, které používají platformu Microsoft Identity Platform, by měly být schopné programově zpracovávat proces přechodu klíčů. Porozumíte tomu, jak fungují klíče, jak vyhodnotit dopad přechodu do aplikace a jak aktualizovat aplikaci nebo vytvořit pravidelný ruční proces přechodu, který bude v případě potřeby zpracovávat vrácení klíče.

Přehled podpisových klíčů na platformě Microsoft Identity Platform

Platforma Microsoft Identity Platform používá kryptografii veřejného klíče postavenou na oborových standardech k navázání důvěryhodnosti mezi sebou a aplikacemi, které ji používají. V praxi to funguje následujícím způsobem: Platforma Microsoft Identity Platform používá podpisový klíč, který se skládá z páru veřejného a privátního klíče. Když se uživatel přihlásí k aplikaci, která k ověřování používá platformu Microsoft Identity Platform, vytvoří platforma Microsoft Identity Platform token zabezpečení, který obsahuje informace o uživateli. Tento token je podepsán platformou Microsoft Identity Platform pomocí svého privátního klíče před odesláním zpět do aplikace. Aby bylo možné ověřit, jestli je token platný a pochází z platformy Microsoft Identity Platform, musí aplikace ověřit podpis tokenu pomocí veřejných klíčů vystavených platformou Microsoft Identity Platform, která je obsažena v dokumentu openID tenanta Připojení dokumentu zjišťování nebo dokumentu federačních metadat SAML/WS-Fed.

Pro účely zabezpečení se podpisový klíč platformy Microsoft Identity Platform pravidelně zapisuje a v případě tísňového volání je možné okamžitě vrátit. Mezi těmito rolemi klíčů neexistuje žádná sada ani garantovaná doba – každá aplikace, která se integruje s platformou Microsoft Identity Platform, by měla být připravená na zpracování události přechodu klíče bez ohledu na to, jak často k ní může dojít. Pokud vaše aplikace nezpracuje náhlé aktualizace a pokusí se ověřit podpis v tokenu pomocí klíče s vypršenou platností, aplikace token nesprávně odmítne. Kontrola aktualizací každých 24 hodin je osvědčeným postupem, kdy se omezí (maximálně každých pět minut) okamžitá aktualizace dokumentu klíče, pokud se zjistí token, který neověřuje klíče v mezipaměti vaší aplikace.

V dokumentu zjišťování OpenID Připojení a dokumentu federačních metadat je vždy k dispozici více než jeden platný klíč. Vaše aplikace by měla být připravená použít všechny a všechny klíče zadané v dokumentu, protože jeden klíč může být brzy vrácen, další může být jeho nahrazení atd. Počet klíčů, které existují, se může v průběhu času měnit na základě interní architektury platformy Microsoft Identity Platform, protože podporujeme nové platformy, nové cloudy nebo nové ověřovací protokoly. Pořadí klíčů v odpovědi JSON ani pořadí, ve kterém byly zpřístupněny, by pro vaši aplikaci nemělo být považováno za smysluplné.

Aplikace, které podporují pouze jeden podpisový klíč nebo aplikace, které vyžadují ruční aktualizace podpisových klíčů, jsou ze své podstaty méně bezpečné a méně spolehlivé. Měly by se aktualizovat tak, aby používaly standardní knihovny , aby zajistily, že vždy používají aktuální podpisové klíče, mimo jiné osvědčené postupy.

Jak posoudit, jestli bude vaše aplikace ovlivněná a co s ní dělat

Způsob, jakým vaše aplikace zpracovává převod klíčů, závisí na proměnných, jako je typ aplikace nebo jaký protokol identity a knihovna se použily. V následujících částech se dozvíte, jestli jsou nejběžnější typy aplikací ovlivněné převodem klíče, a poskytují pokyny k aktualizaci aplikace tak, aby podporovala automatické převrácení nebo ruční aktualizaci klíče.

Tyto pokyny neplatí pro:

  • Aplikace přidané z Galerie aplikací Microsoft Entra (včetně vlastních) obsahují samostatné pokyny týkající se podpisových klíčů. Další informace.
  • Místní aplikace publikované prostřednictvím proxy aplikací se nemusí starat o podpisové klíče.

Nativní klientské aplikace přistupující k prostředkům

Aplikace, které přistupují jenom k prostředkům (například Microsoft Graph, KeyVault, Rozhraní API Outlooku a další rozhraní API Microsoftu), získají token a předají ho vlastníkovi prostředku. Vzhledem k tomu, že nechrání žádné prostředky, neprověřují token, a proto se nemusí ujistit, že je správně podepsaný.

Nativní klientské aplikace, ať už desktopové nebo mobilní, spadají do této kategorie, a proto nejsou ovlivněny převrácením.

Webové aplikace / rozhraní API přistupující k prostředkům

Aplikace, které přistupují jenom k prostředkům (jako je Microsoft Graph, KeyVault, Outlook API a další rozhraní API Microsoftu), získají token a předají ho vlastníkovi prostředku. Vzhledem k tomu, že nechrání žádné prostředky, neprověřují token, a proto se nemusí ujistit, že je správně podepsaný.

Webové aplikace a webová rozhraní API, které k vyžádání tokenů spadají do této kategorie a které používají tok jen pro aplikaci (přihlašovací údaje klienta nebo klientský certifikát), a proto to nemá vliv na vrácení.

Webové aplikace / rozhraní API chrání prostředky a vytvářejí se pomocí Aplikace Azure Services

Funkce ověřování / autorizace služby Aplikace Azure (EasyAuth) už má potřebnou logiku pro automatické zpracování přechodu klíčů.

Webové aplikace / rozhraní API chránící prostředky pomocí ASP.NET OWIN OpenID Připojení, WS-Fed nebo WindowsAzureActiveDirectoryBearerAuthentication middleware

Pokud vaše aplikace používá middleware ASP.NET OWIN OpenID Připojení, WS-Fed nebo WindowsAzureActiveDirectoryBearerAuthentication, už má potřebnou logiku pro automatické zpracování přechodu klíče.

Aplikaci můžete ověřit tak, že hledáte některý z následujících fragmentů kódu v souboru Startup.cs nebo Startup.Auth.cs vaší aplikace.

app.UseOpenIdConnectAuthentication(
    new OpenIdConnectAuthenticationOptions
    {
        // ...
    });
app.UseWsFederationAuthentication(
    new WsFederationAuthenticationOptions
    {
        // ...
    });
app.UseWindowsAzureActiveDirectoryBearerAuthentication(
    new WindowsAzureActiveDirectoryBearerAuthenticationOptions
    {
        // ...
    });

Webové aplikace / rozhraní API chránící prostředky pomocí rozhraní .NET Core OpenID Připojení nebo middleware JwtBearerAuthentication

Pokud vaše aplikace používá middleware ASP.NET OWIN OpenID Připojení nebo JwtBearerAuthentication, už má potřebnou logiku pro automatické zpracování přechodu klíče.

Pokud chcete ověřit, že vaše aplikace některou z těchto metod používá, vyhledejte v Startup.cs nebo Startup.Auth.cs vaší aplikace některý z následujících fragmentů kódu.

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

Webové aplikace / rozhraní API chránící prostředky pomocí modulu Node.js passport-azure-ad

Pokud vaše aplikace používá modul Node.js passport-ad, už má potřebnou logiku pro automatické zpracování přechodu klíče.

Potvrzení, že vaše aplikace passport-ad vyhledá následující fragment kódu v app.js vaší aplikace

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

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

Webové aplikace / rozhraní API chránící prostředky a vytvořené pomocí sady Visual Studio 2015 nebo novější

Pokud byla vaše aplikace vytvořena pomocí šablony webové aplikace v sadě Visual Studio 2015 nebo novější a v nabídce Změnit ověřování jste vybrali pracovní nebo školní účty, už má potřebnou logiku pro automatické zpracování přechodu klíče. Tato logika vložená do middlewaru OWIN OpenID Připojení, načte a ukládá klíče do mezipaměti z openID Připojení dokumentu zjišťování a pravidelně je aktualizuje.

Pokud jste do řešení přidali ověřování ručně, vaše aplikace nemusí mít potřebnou logiku přechodu klíče. Můžete ho napsat sami, nebo postupovat podle kroků ve webových aplikacích nebo rozhraních API pomocí jakékoli jiné knihovny nebo ručně implementovat některý z podporovaných protokolů.

Webové aplikace chrání prostředky a vytvářejí se pomocí sady Visual Studio 2013

Pokud byla vaše aplikace vytvořena pomocí šablony webové aplikace v sadě Visual Studio 2013 a v nabídce Změnit ověřování jste vybrali organizační účty, už má potřebnou logiku pro automatické zpracování přechodu klíče. Tato logika ukládá jedinečný identifikátor vaší organizace a informace o podpisovém klíči do dvou databázových tabulek přidružených k projektu. Připojovací řetězec pro databázi najdete v souboru Web.config projektu.

Pokud jste do řešení přidali ověřování ručně, vaše aplikace nemusí mít potřebnou logiku přechodu klíče. Budete ho muset napsat sami, nebo postupovat podle kroků ve webových aplikacích nebo rozhraních API pomocí jakékoli jiné knihovny nebo ručně implementovat některý z podporovaných protokolů.

Následující kroky vám pomůžou ověřit, že logika ve vaší aplikaci funguje správně.

  1. V sadě Visual Studio 2013 otevřete řešení a v pravém okně vyberte na kartě Průzkumník serveru.
  2. Rozbalte Připojení iony dat, výchozí Připojení ion a potom tabulky. Vyhledejte tabulku IssuingAuthorityKeys, klikněte na ni pravým tlačítkem myši a pak vyberte Zobrazit data tabulky.
  3. V tabulce IssuingAuthorityKeys bude alespoň jeden řádek, který odpovídá hodnotě kryptografického otisku klíče. Odstraňte všechny řádky v tabulce.
  4. Klikněte pravým tlačítkem myši na tabulku Tenants a pak vyberte Zobrazit data tabulky.
  5. V tabulce Tenants (Tenants) bude alespoň jeden řádek, který odpovídá jedinečnému identifikátoru tenanta adresáře. Odstraňte všechny řádky v tabulce. Pokud neodstraníte řádky v tabulce Tenants i v tabulce IssuingAuthorityKeys , zobrazí se za běhu chyba.
  6. Sestavte a spusťte aplikaci. Po přihlášení ke svému účtu můžete aplikaci zastavit.
  7. Vraťte se do Průzkumníka serveru a podívejte se na hodnoty v tabulce IssuingAuthorityKeys a Tenants. Všimnete si, že se automaticky znovu vyplní příslušnými informacemi z dokumentu federačních metadat.

Webová rozhraní API chrání prostředky a vytvářejí se pomocí sady Visual Studio 2013

Pokud jste vytvořili aplikaci webového rozhraní API v sadě Visual Studio 2013 pomocí šablony webového rozhraní API a poté jste v nabídce Změnit ověřování vybrali účty organizace, už máte ve své aplikaci potřebnou logiku.

Pokud jste ručně nakonfigurovali ověřování, postupujte podle následujících pokynů a zjistěte, jak nakonfigurovat webové rozhraní API tak, aby automaticky aktualizovalo informace o jeho klíči.

Následující fragment kódu ukazuje, jak získat nejnovější klíče z dokumentu federačních metadat a pak pomocí obslužné rutiny tokenu JWT ověřit token. Fragment kódu předpokládá, že použijete vlastní mechanismus ukládání do mezipaměti pro zachování klíče k ověření budoucích tokenů z platformy Microsoft Identity Platform, ať už v databázi, konfiguračním souboru nebo jinde.

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

Webové aplikace chrání prostředky a vytvořené pomocí sady Visual Studio 2012

Pokud byla vaše aplikace vytvořená v sadě Visual Studio 2012, pravděpodobně jste ke konfiguraci aplikace použili nástroj Identity and Access Tool. Je také pravděpodobné, že používáte registr vinR (Validating Issuer Name Registry). VinR zodpovídá za údržbu informací o důvěryhodných zprostředkovatelích identit (Microsoft Identity Platform) a klíčích používaných k ověření tokenů vydaných nimi. VinR také usnadňuje automatickou aktualizaci klíčových informací uložených v souboru Web.config stažením nejnovějšího dokumentu federačních metadat přidružených k vašemu adresáři, kontrolou, jestli konfigurace není aktuální s nejnovějším dokumentem, a podle potřeby aktualizuje aplikaci tak, aby používala nový klíč.

Pokud jste aplikaci vytvořili pomocí některé z ukázek kódu nebo dokumentace návodu od Microsoftu, logika přechodu klíčů je už součástí vašeho projektu. Všimněte si, že následující kód již ve vašem projektu existuje. Pokud vaše aplikace tuto logiku ještě nemá, přidejte ji podle následujících kroků a ověřte, že funguje správně.

  1. V Průzkumník řešení přidejte odkaz na sestavení System.IdentityModel pro příslušný projekt.
  2. Otevřete soubor Global.asax.cs a přidejte následující direktivy using:
    using System.Configuration;
    using System.IdentityModel.Tokens;
    
  3. Do souboru Global.asax.cs přidejte následující metodu:
    protected void RefreshValidationSettings()
    {
     string configPath = AppDomain.CurrentDomain.BaseDirectory + "\\" + "Web.config";
     string metadataAddress =
                   ConfigurationManager.AppSettings["ida:FederationMetadataLocation"];
     ValidatingIssuerNameRegistry.WriteToConfig(metadataAddress, configPath);
    }
    
  4. V metodě Application_Start() v Global.asax.cs vyvoláte metodu RefreshValidation Nastavení(), jak je znázorněno na obrázku:
    protected void Application_Start()
    {
     AreaRegistration.RegisterAllAreas();
     ...
     RefreshValidationSettings();
    }
    

Po provedení těchto kroků se soubor Web.config vaší aplikace aktualizuje nejnovějšími informacemi z dokumentu federačních metadat, včetně nejnovějších klíčů. K této aktualizaci dojde pokaždé, když váš fond aplikací recykluje ve službě IIS; Ve výchozím nastavení je služba IIS nastavená na recyklaci aplikací každých 29 hodin.

Pomocí následujícího postupu ověřte, že funguje logika přechodu klíče.

  1. Po ověření, že vaše aplikace používá výše uvedený kód, otevřete soubor Web.config a přejděte do< bloku issuerNameRegistry>, konkrétně hledáte následující řádky:
    <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. <V nastavení add thumbprint=""> změňte hodnotu kryptografického otisku nahrazením libovolného znaku jiným znakem. Uložte soubor Web.config.
  3. Sestavte aplikaci a spusťte ji. Pokud můžete dokončit proces přihlášení, vaše aplikace úspěšně aktualizuje klíč stažením požadovaných informací z dokumentu federačních metadat vašeho adresáře. Pokud máte problémy s přihlášením, ujistěte se, že jsou změny ve vaší aplikaci správné, a to tak, že si přečtete článek o přidání přihlášení k webové aplikaci pomocí platformy Microsoft Identity Platform nebo si stáhnete a zkontrolujete následující ukázku kódu: Cloudová aplikace s více tenanty pro Microsoft Entra ID.

Webové aplikace / rozhraní API chrání prostředky pomocí jakékoli jiné knihovny nebo ručně implementují některý z podporovaných protokolů.

Pokud používáte jinou knihovnu nebo ručně implementujete některý z podporovaných protokolů, budete muset zkontrolovat knihovnu nebo implementaci, abyste měli jistotu, že se klíč načítá z dokumentu OpenID Připojení zjišťování nebo z dokumentu metadat federace. Jedním ze způsobů, jak to zjistit, je provést vyhledávání v kódu nebo v kódu knihovny pro všechna volání dokumentu zjišťování OpenID nebo dokumentu federačních metadat.

Pokud je klíč uložený někde nebo pevně zakódovaný v aplikaci, můžete ho ručně načíst a odpovídajícím způsobem aktualizovat provedením ručního přechodu podle pokynů na konci tohoto dokumentu s pokyny. Důrazně doporučujeme, abyste svou aplikaci vylepšili tak, aby podporovala automatické převrácení pomocí některého z přístupů uvedených v tomto článku, abyste se vyhnuli budoucím přerušením a režijním nákladům, pokud platforma Microsoft Identity Platform zvýší četnost přechodu na jinou verzi nebo má nouzové zrušení mimo pásmo.

Jak otestovat aplikaci, abyste zjistili, jestli bude ovlivněná

Pomocí následujících skriptů PowerShellu můžete ověřit, jestli vaše aplikace podporuje automatické převrácení klíčů.

Pokud chcete zkontrolovat a aktualizovat podpisové klíče pomocí PowerShellu, budete potřebovat modul MSIdentityTools PowerShell.

  1. Nainstalujte modul POWERShellu MSIdentityTools:

    Install-Module -Name MSIdentityTools
    
  2. Přihlaste se pomocí příkazu Připojení-MgGraph s účtem správce, abyste udělili souhlas s požadovanými obory:

     Connect-MgGraph -Scope "Application.ReadWrite.All"
    
  3. Získejte seznam dostupných kryptografických otisků podpisového klíče:

    Get-MsIdSigningKeyThumbprint
    
  4. Vyberte některý z kryptografických otisků klíčů a nakonfigurujte ID Microsoft Entra tak, aby tento klíč používal s vaší aplikací (získejte ID aplikace z Centra pro správu Microsoft Entra):

    Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>
    
  5. Otestujte webovou aplikaci přihlášením, abyste získali nový token. Změna aktualizace klíče je okamžitá, ale ujistěte se, že používáte novou relaci prohlížeče (například "InPrivate", "InPrivate", Chrome "Anonymní" nebo "Soukromý" režim Firefoxu), abyste měli jistotu, že jste vystavil nový token.

  6. Pro každý z vrácených kryptografických otisků podpisového klíče spusťte rutinu Update-MsIdApplicationSigningKeyThumbprint a otestujte proces přihlášení k webové aplikaci.

  7. Pokud se webová aplikace správně přihlásí, podporuje automatické převrácení. Pokud tomu tak není, upravte aplikaci tak, aby podporovala ruční vrácení. Další informace najdete v části Vytvoření ručního procesu přechodu.

  8. Spuštěním následujícího skriptu se vraťte k normálnímu chování:

    Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
    

Postup ručního přechodu, pokud vaše aplikace nepodporuje automatické vrácení

Pokud vaše aplikace nepodporuje automatické převrácení, musíte vytvořit proces, který pravidelně monitoruje podpisové klíče platformy Microsoft Identity Platform a odpovídajícím způsobem provádí ruční převrácení.

Pokud chcete zkontrolovat a aktualizovat podpisové klíče pomocí PowerShellu MSIdentityTools , budete potřebovat modul PowerShellu.

  1. Nainstalujte modul PowerShellu MSIdentityTools :

    Install-Module -Name MSIdentityTools
    
  2. Získejte nejnovější podpisový klíč (získejte ID tenanta z Centra pro správu Microsoft Entra):

    Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
    
  3. Porovnejte tento klíč s klíčem, který je aktuálně pevně zakódovaný nebo nakonfigurovaný pro použití vaší aplikace.

  4. Pokud se nejnovější klíč liší od klíče, který vaše aplikace používá, stáhněte si nejnovější podpisový klíč:

    Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
    
  5. Aktualizujte kód nebo konfiguraci aplikace tak, aby používaly nový klíč.

  6. Nakonfigurujte ID Microsoft Entra tak, aby používalo tento nejnovější klíč s vaší aplikací (získejte ID aplikace z Centra pro správu Microsoft Entra):

    Get-MsIdSigningKeyThumbprint -Latest | Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId>
    
  7. Otestujte webovou aplikaci přihlášením, abyste získali nový token. Změna aktualizace klíče je okamžitá, ale ujistěte se, že používáte novou relaci prohlížeče (například "InPrivate", "InPrivate", Chrome "Anonymní" nebo "Soukromý" režim Firefoxu), abyste měli jistotu, že jste vystavil nový token.

  8. Pokud dojde k nějakým problémům, vraťte se k předchozímu klíči, který jste používali, a kontaktujte podpora Azure:

    Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <PreviousKeyThumbprint>
    
  9. Po aktualizaci aplikace na podporu ručního přechodu se vraťte k normálnímu chování:

    Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default