Przerzucanie klucza podpisywania w Platforma tożsamości Microsoft

Artykuł
10/30/2024

W tym artykule omówiono, co należy wiedzieć o kluczach publicznych używanych przez Platforma tożsamości Microsoft do podpisywania tokenów zabezpieczających. Należy pamiętać, że te klucze są przerzucane okresowo i w nagłych wypadkach mogą zostać natychmiast przerzucone. Wszystkie aplikacje korzystające z Platforma tożsamości Microsoft powinny być w stanie programowo obsługiwać proces przerzucania kluczy. Dowiesz się, jak działają klucze, jak ocenić wpływ przerzucania do aplikacji. Dowiesz się również, jak zaktualizować aplikację lub ustanowić okresowy proces ręcznego przerzucania w celu obsługi przerzucania klucza w razie potrzeby.

Omówienie kluczy podpisywania w Platforma tożsamości Microsoft

Platforma tożsamości Microsoft używa kryptografii klucza publicznego opartej na standardach branżowych w celu ustanowienia zaufania między samymi aplikacjami a aplikacjami, które go używają. W praktyce działa to w następujący sposób: Platforma tożsamości Microsoft używa klucza podpisywania, który składa się z pary kluczy publicznych i prywatnych. Gdy użytkownik loguje się do aplikacji korzystającej z Platforma tożsamości Microsoft do uwierzytelniania, Platforma tożsamości Microsoft tworzy token zabezpieczający zawierający informacje o użytkowniku. Ten token jest podpisany przez Platforma tożsamości Microsoft przy użyciu klucza prywatnego przed odesłaniem do aplikacji. Aby sprawdzić, czy token jest prawidłowy i pochodzi z Platforma tożsamości Microsoft, aplikacja musi zweryfikować podpis tokenu przy użyciu kluczy publicznych uwidocznionych przez Platforma tożsamości Microsoft zawartego w dokumencie odnajdywania OpenID Connect dzierżawy lub dokumencie metadanych federacji SAML/WS-Fed.

W celach bezpieczeństwa klucz podpisywania Platforma tożsamości Microsoft jest rzutowany okresowo i, w przypadku sytuacji awaryjnej, może zostać natychmiast przerzucony. Nie ma ustawionego ani gwarantowanego czasu między tymi rzutami kluczy. Każda aplikacja zintegrowana z Platforma tożsamości Microsoft powinna być przygotowana do obsługi zdarzenia przerzucania klucza niezależnie od tego, jak często może wystąpić. Jeśli aplikacja nie obsługuje nagłych odświeżeń i próbuje użyć wygasłego klucza w celu zweryfikowania podpisu tokenu, aplikacja niepoprawnie odrzuca token. Zaleca się używanie bibliotek standardowych, aby upewnić się, że metadane klucza są poprawnie odświeżane i aktualizowane. W przypadkach, gdy biblioteki standardowe nie są używane, upewnij się, że implementacja jest zgodna z sekcją najlepszych rozwiązań .

W dokumencie odnajdywania openID Connect i dokumencie metadanych federacji zawsze jest dostępnych więcej niż jeden prawidłowy klucz. Aplikacja powinna być przygotowana do użycia dowolnego i wszystkich kluczy określonych w dokumencie, ponieważ jeden klucz może zostać wkrótce wyrzucony, inny może być jego zastąpieniem itd. Liczba obecnych kluczy może ulec zmianie w miarę upływu czasu na podstawie wewnętrznej architektury Platforma tożsamości Microsoft, ponieważ obsługujemy nowe platformy, nowe chmury lub nowe protokoły uwierzytelniania. Ani kolejność kluczy w odpowiedzi JSON, ani kolejność, w jakiej zostały ujawnione, nie powinna być uznawana za zrozumiałą dla aplikacji.

Aplikacje, które obsługują tylko pojedynczy klucz podpisywania lub aplikacje wymagające ręcznej aktualizacji kluczy podpisywania, są z natury mniej bezpieczne i mniej niezawodne. Należy je zaktualizować w celu używania bibliotek standardowych w celu zapewnienia, że zawsze używają aktualnych kluczy podpisywania, między innymi najlepszych rozwiązań.

Najlepsze rozwiązania dotyczące buforowania i walidacji metadanych kluczy

Odnajdywanie kluczy przy użyciu punktu końcowego specyficznego dla dzierżawy zgodnie z opisem w temacie OpenID Connect (OIDC) i metadanych federacji
Nawet jeśli aplikacja jest wdrażana w wielu dzierżawach, zaleca się zawsze odnajdywanie i buforowanie kluczy niezależnie dla każdej dzierżawy, która jest obsługiwana przez aplikację (przy użyciu punktu końcowego specyficznego dla dzierżawy). Klucz, który jest obecnie wspólny dla dzierżaw, może stać się odrębny w różnych dzierżawach w przyszłości.
Użyj poniższego algorytmu buforowania, aby upewnić się, że buforowanie jest odporne i bezpieczne

Algorytm buforowania metadanych kluczy:

Nasze standardowe biblioteki implementują odporne i bezpieczne buforowanie kluczy. Zaleca się ich używanie, aby uniknąć drobnych wad w implementacji. W przypadku implementacji niestandardowych oto przybliżony algorytm:

Zagadnienia ogólne:

Usługa sprawdzania poprawności tokenów powinna mieć pamięć podręczną, która może przechowywać wiele odrębnych kluczy (10–1000).
Klucze powinny być buforowane indywidualnie, używając identyfikatora klucza ("kid" w specyfikacji metadanych kluczy OIDC) jako klucza pamięci podręcznej.
Czas wygaśnięcia kluczy w pamięci podręcznej powinien być skonfigurowany do 24 godzin, a odświeżanie odbywa się co godzinę. Dzięki temu system może szybko reagować na usuwane klucze, ale ma wystarczający czas trwania pamięci podręcznej, aby nie mieć wpływu na problemy z pobieraniem kluczy.
Klucze powinny być odświeżane:
- Po uruchomieniu procesu lub gdy pamięć podręczna jest pusta
- Okresowo (zalecane co 1 godzinę) jako zadanie w tle
- Dynamicznie, jeśli otrzymany token został podpisany przy użyciu nieznanego klucza (nieznane dziecko lub tid w nagłówku)

Procedura KeyRefresh (algorytm koncepcyjny z modelu IdentityModel)

Inicjowanie

Menedżer konfiguracji jest skonfigurowany przy użyciu określonego adresu w celu pobrania danych konfiguracji i niezbędnych interfejsów do pobrania i zweryfikowania tych danych.
Sprawdzanie konfiguracji

Przed pobraniem nowych danych system najpierw sprawdza, czy istniejące dane są nadal prawidłowe na podstawie wstępnie zdefiniowanego interwału odświeżania.
Pobieranie danych Jeśli dane są nieaktualne lub brakujące, system blokuje się w celu zapewnienia, że tylko jeden wątek pobiera nowe dane, aby uniknąć duplikowania (i wyczerpania wątków). Następnie system próbuje pobrać najnowsze dane konfiguracji z określonego punktu końcowego.
Weryfikacja

Po pobraniu nowych danych jest weryfikowana, aby upewnić się, że spełnia wymagane standardy i nie jest uszkodzona. Metadane są akceptowane tylko wtedy, gdy żądanie przychodzące zostało pomyślnie zweryfikowane przy użyciu nowych kluczy.
Obsługa błędów

Jeśli podczas pobierania danych wystąpią jakiekolwiek błędy, są rejestrowane. System nadal działa z ostatnią znaną dobrą konfiguracją, jeśli nie można pobrać nowych danych
Aktualizacje automatyczne System okresowo sprawdza i aktualizuje dane konfiguracji automatycznie na podstawie interwału odświeżania (zaleca się 12 godzin z zakłóceniami plus lub minus 1 h). Może również ręcznie zażądać aktualizacji w razie potrzeby, zapewniając, że dane są zawsze aktualne.
Walidacja tokenu przy użyciu nowego klucza Jeśli token zostanie dostarczony z kluczem podpisywania, który nie jest jeszcze znany z konfiguracji, system próbuje pobrać konfigurację z wywołaniem synchronizacji na gorącej ścieżce do obsługi nowych kluczy w metadanych poza regularnymi oczekiwanymi aktualizacjami (ale nie częściej niż 5 minut)

Takie podejście zapewnia, że system zawsze używa najbardziej aktualnych i prawidłowych danych konfiguracyjnych, jednocześnie bezpiecznie obsługując błędy i unikając nadmiarowych operacji.

Implementacja tego algorytmu platformy .NET jest dostępna w programie BaseConfigurationManager. Może ulec zmianie w oparciu o odporność i oceny zabezpieczeń. Zobacz również wyjaśnienie tutaj

Procedura KeyRefresh (pseudo code):

Ta procedura używa globalnego (lastSuccessfulRefreshTime sygnatury czasowej), aby zapobiec zbyt często warunkom odświeżania kluczy.

OpenID Connect (OIDC)

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

Procedura uruchamiania usługi:

KeyRefresh w celu zaktualizowania kluczy
Uruchamianie zadania w tle, które wywołuje funkcję KeyRefresh co godzinę

Procedura TokenValidation sprawdzania poprawności klucza (kod pseudo):

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

Jak ocenić, czy aplikacja będzie miała wpływ na aplikację i co z tym zrobić

Sposób obsługi przerzucania kluczy przez aplikację zależy od zmiennych, takich jak typ aplikacji lub używany protokół tożsamości i biblioteka. W poniższych sekcjach ocenisz, czy na najbardziej typowe typy aplikacji ma wpływ przerzucanie klucza, i podano wskazówki dotyczące sposobu aktualizowania aplikacji w celu obsługi automatycznego przerzucania lub ręcznego aktualizowania klucza.

Natywne aplikacje klienckie, które uzyskują dostęp do zasobów
Aplikacje internetowe/interfejsy API, które uzyskują dostęp do zasobów
Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone przy użyciu usług aplikacja systemu Azure
Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu ASP.NET OWIN OpenID Connect, WS-Fed lub WindowsAzureActiveDirectoryBearerAuthentication oprogramowania pośredniczącego
Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu ASP.NET Core OpenID Connect lub JwtBearerAuthentication oprogramowania pośredniczącego
Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu modułu Node.js passport-azure-ad
Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2015 lub nowszego
Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2013
Internetowe interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2013
Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2012
Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu innych bibliotek lub ręcznie implementowanie dowolnego z obsługiwanych protokołów

Te wskazówki nie mają zastosowania do:

Aplikacje dodane z galerii aplikacji Entra firmy Microsoft (w tym niestandardowej) mają oddzielne wskazówki dotyczące kluczy podpisywania. Więcej informacji.
Aplikacje lokalne opublikowane za pośrednictwem serwera proxy aplikacji nie muszą martwić się o klucze podpisywania.

Natywne aplikacje klienckie, które uzyskują dostęp do zasobów

Aplikacje uzyskujące dostęp tylko do zasobów (na przykład Microsoft Graph, KeyVault, Outlook API i inne interfejsy API firmy Microsoft) uzyskują token i przekazują go do właściciela zasobu. Ze względu na to, że nie chronią żadnych zasobów, nie sprawdzają tokenu i dlatego nie muszą upewnić się, że jest on prawidłowo podpisany.

Natywne aplikacje klienckie, zarówno klasyczne, jak i mobilne, należą do tej kategorii i w związku z tym nie mają wpływu na przerzucanie.

Aplikacje internetowe/interfejsy API, które uzyskują dostęp do zasobów

Aplikacje uzyskujące dostęp tylko do zasobów (takich jak Microsoft Graph, KeyVault, Outlook API i inne interfejsy API firmy Microsoft) uzyskują token i przekazują go do właściciela zasobu. Ze względu na to, że nie chronią żadnych zasobów, nie sprawdzają tokenu i dlatego nie muszą upewnić się, że jest on prawidłowo podpisany.

Aplikacje internetowe i internetowe interfejsy API korzystające z przepływu tylko do aplikacji (poświadczenia klienta/ certyfikat klienta) do żądania tokenów należą do tej kategorii i w związku z tym nie mają wpływu na przerzucanie.

Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone przy użyciu usług aplikacja systemu Azure

funkcja uwierzytelniania/autoryzacji usług aplikacja systemu Azure Services (EasyAuth) ma już niezbędną logikę do automatycznego obsługi przerzucania kluczy.

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu ASP.NET OWIN OpenID Connect, WS-Fed lub WindowsAzureActiveDirectoryBearerAuthentication oprogramowania pośredniczącego

Jeśli aplikacja korzysta z oprogramowania pośredniczącego ASP.NET OWIN OpenID Connect, WS-Fed lub WindowsAzureActiveDirectoryBearerAuthentication, ma już niezbędną logikę do automatycznego obsługi przerzucania kluczy.

Możesz potwierdzić, że aplikacja korzysta z dowolnego z tych elementów, wyszukując dowolne z poniższych fragmentów kodu w plikach Startup.cs lub Startup.Auth.cs aplikacji.

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

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

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

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu programu .NET Core OpenID Connect lub JwtBearerAuthentication oprogramowania pośredniczącego

Jeśli aplikacja korzysta z ASP.NET OWIN OpenID Connect lub JwtBearerAuthentication oprogramowania pośredniczącego, ma już niezbędną logikę do automatycznego obsługi przerzucania kluczy.

Możesz potwierdzić, że aplikacja korzysta z dowolnego z tych elementów, wyszukując dowolne z poniższych fragmentów kodu w Startup.cs aplikacji lub Startup.Auth.cs

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

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

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu modułu Node.js `passport-azure-ad`

Jeśli aplikacja korzysta z modułu Node.js passport-ad, ma już niezbędną logikę do automatycznego przerzucania kluczy.

Możesz potwierdzić, że twoja aplikacja passport-ad jest wyszukiwana w poniższym fragmencie kodu w app.js aplikacji

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

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

Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2015 lub nowszego

Jeśli aplikacja została utworzona przy użyciu szablonu aplikacji internetowej w programie Visual Studio 2015 lub nowszym, a z menu Zmień uwierzytelnianie wybrano opcję Konta służbowe, ma już niezbędną logikę do automatycznego obsługi przerzucania kluczy. Ta logika osadzona w narzędziu pośredniczącym OWIN OpenID Connect pobiera i buforuje klucze z dokumentu odnajdywania OpenID Connect i okresowo je odświeża.

W przypadku ręcznego dodania uwierzytelniania do rozwiązania aplikacja może nie mieć niezbędnej logiki przerzucania kluczy. Możesz napisać go samodzielnie lub wykonać kroki opisane w temacie Aplikacje internetowe/interfejsy API przy użyciu innych bibliotek lub ręcznie zaimplementować dowolny z obsługiwanych protokołów.

Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2013

Jeśli aplikacja została utworzona przy użyciu szablonu aplikacji internetowej w programie Visual Studio 2013 i wybrano pozycję Konta organizacyjne z menu Zmiana uwierzytelniania , ma już niezbędną logikę do automatycznego obsługi przerzucania kluczy. Ta logika przechowuje unikatowy identyfikator organizacji i informacje o kluczu podpisywania w dwóch tabelach bazy danych skojarzonych z projektem. Parametry połączenia bazy danych można znaleźć w pliku Web.config projektu.

W przypadku ręcznego dodania uwierzytelniania do rozwiązania aplikacja może nie mieć niezbędnej logiki przerzucania kluczy. Musisz napisać go samodzielnie lub wykonać kroki opisane w temacie Aplikacje internetowe/interfejsy API przy użyciu innych bibliotek lub ręcznie implementowanie dowolnego z obsługiwanych protokołów.

Poniższe kroki ułatwiają sprawdzenie, czy logika działa prawidłowo w aplikacji.

W programie Visual Studio 2013 otwórz rozwiązanie, a następnie wybierz na karcie Eksplorator serwera w prawym oknie.
Rozwiń węzeł Połączenia danych, DefaultConnection, a następnie tabele. Znajdź tabelę IssuingAuthorityKeys , kliknij ją prawym przyciskiem myszy, a następnie wybierz polecenie Pokaż dane tabeli.
W tabeli IssuingAuthorityKeys będzie co najmniej jeden wiersz odpowiadający wartości odcisku palca klucza. Usuń wszystkie wiersze w tabeli.
Kliknij prawym przyciskiem myszy tabelę Dzierżawy , a następnie wybierz polecenie Pokaż dane tabeli.
W tabeli Tenants (Dzierżawy) będzie istnieć co najmniej jeden wiersz, który odpowiada unikatowego identyfikatora dzierżawy katalogu. Usuń wszystkie wiersze w tabeli. Jeśli nie usuniesz wierszy zarówno w tabeli Tenants, jak i w tabeli IssuingAuthorityKeys, wystąpi błąd w czasie wykonywania.
Skompiluj i uruchom aplikację. Po zalogowaniu się na koncie możesz zatrzymać aplikację.
Wróć do Eksploratora serwera i przyjrzyj się wartościom w tabeli IssuingAuthorityKeys i Tenants. Zauważysz, że zostały one automatycznie ponownie wypełnione odpowiednimi informacjami z dokumentu metadanych federacji.

Internetowe interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2013

Jeśli aplikacja internetowego interfejsu API została utworzona w programie Visual Studio 2013 przy użyciu szablonu internetowego interfejsu API, a następnie wybrano pozycję Konta organizacyjne z menu Zmień uwierzytelnianie, masz już niezbędną logikę w aplikacji.

Jeśli uwierzytelnianie zostało skonfigurowane ręcznie, postępuj zgodnie z poniższymi instrukcjami, aby dowiedzieć się, jak skonfigurować internetowy interfejs API w celu automatycznego aktualizowania jego kluczowych informacji.

Poniższy fragment kodu pokazuje, jak pobrać najnowsze klucze z dokumentu metadanych federacji, a następnie używa programu obsługi tokenów JWT do sprawdzania poprawności tokenu. W fragmencie kodu założono, że użyjesz własnego mechanizmu buforowania do utrwalania klucza w celu zweryfikowania przyszłych tokenów z Platforma tożsamości Microsoft, niezależnie od tego, czy znajduje się w bazie danych, pliku konfiguracji, czy w innym miejscu.

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

Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2012

Jeśli aplikacja została skompilowana w programie Visual Studio 2012, prawdopodobnie użyto narzędzia Identity and Access w celu skonfigurowania aplikacji. Prawdopodobnie używasz również rejestru weryfikowania nazw wystawcy (VINR). VinR jest odpowiedzialny za utrzymywanie informacji o zaufanych dostawcach tożsamości (Platforma tożsamości Microsoft) i kluczach używanych do weryfikowania tokenów wystawionych przez nich. VinR ułatwia również automatyczne aktualizowanie informacji o kluczu przechowywanych w pliku Web.config przez pobranie najnowszego dokumentu metadanych federacji skojarzonego z katalogiem, sprawdzenie, czy konfiguracja jest nieaktualna z najnowszym dokumentem, i zaktualizowanie aplikacji w celu użycia nowego klucza w razie potrzeby.

Jeśli aplikacja została utworzona przy użyciu dowolnego z przykładów kodu lub dokumentacji przewodnika dostarczonej przez firmę Microsoft, logika przerzucania kluczy jest już zawarta w projekcie. Zauważysz, że poniższy kod już istnieje w projekcie. Jeśli aplikacja nie ma jeszcze tej logiki, wykonaj poniższe kroki, aby dodać ją i sprawdzić, czy działa poprawnie.

W Eksplorator rozwiązań dodaj odwołanie do zestawu System.IdentityModel dla odpowiedniego projektu.
Otwórz plik Global.asax.cs i dodaj następujące dyrektywy using:
```
using System.Configuration;
using System.IdentityModel.Tokens;
```

Dodaj następującą metodę do pliku Global.asax.cs :

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

Wywołaj metodę RefreshValidationSettings() w metodzie Application_Start() w Global.asax.cs , jak pokazano poniżej:

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

Po zakończeniu tych kroków konfiguracja aplikacji Web.config zostanie zaktualizowana o najnowsze informacje z dokumentu metadanych federacji, w tym najnowsze klucze. Ta aktualizacja będzie występować za każdym razem, gdy pula aplikacji będzie odzyskiwana w usługach IIS; domyślnie usługi IIS są ustawiane na odtwarzanie aplikacji co 29 godzin.

Wykonaj poniższe kroki, aby sprawdzić, czy logika przerzucania klucza działa.

Po sprawdzeniu, że aplikacja używa powyższego kodu, otwórz plik Web.config i przejdź do< bloku issuerNameRegistry>, w szczególności szukając następujących kilku wierszy:

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

W ustawieniu <add thumbprint=""> zmień wartość odcisku palca, zastępując dowolny znak innym znakiem. Zapisz plik Web.config.
Skompiluj aplikację, a następnie uruchom ją. Jeśli możesz ukończyć proces logowania, aplikacja pomyślnie aktualizuje klucz, pobierając wymagane informacje z dokumentu metadanych federacji katalogu. Jeśli masz problemy z logowaniem, upewnij się, że zmiany w aplikacji są poprawne, czytając artykuł Dodawanie logowania do aplikacji internetowej przy użyciu Platforma tożsamości Microsoft lub pobieranie i sprawdzanie następującego przykładu kodu: Wielodostępna aplikacja w chmurze dla firmy Microsoft Entra ID.

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu innych bibliotek lub ręcznie implementowanie dowolnego z obsługiwanych protokołów

Jeśli używasz innej biblioteki lub ręcznie zaimplementowano dowolny z obsługiwanych protokołów, należy przejrzeć bibliotekę lub implementację, aby upewnić się, że klucz jest pobierany z dokumentu odnajdywania OpenID Connect lub dokumentu metadanych federacji. Jednym ze sposobów sprawdzenia tego jest przeprowadzenie wyszukiwania w kodzie lub w kodzie biblioteki pod kątem wywołań dokumentu odnajdywania OpenID lub dokumentu metadanych federacji.

Jeśli klucz jest przechowywany gdzieś lub zakodowany w aplikacji, możesz ręcznie pobrać klucz i odpowiednio go zaktualizować, wykonując ręczne przerzucanie zgodnie z instrukcjami na końcu tego dokumentu ze wskazówkami. Zdecydowanie zachęcamy do ulepszenia aplikacji w celu obsługi automatycznego przerzucania przy użyciu dowolnego z metod opisanych w tym artykule, aby uniknąć przyszłych zakłóceń i narzutów, jeśli Platforma tożsamości Microsoft zwiększy jego cykl przerzucania lub ma awaryjne przerzucanie poza pasmem.

Jak przetestować aplikację, aby określić, czy będzie to miało wpływ

Możesz sprawdzić, czy aplikacja obsługuje automatyczne przerzucanie kluczy, korzystając z poniższych skryptów programu PowerShell.

Aby sprawdzić i zaktualizować klucze podpisywania przy użyciu programu PowerShell, potrzebny jest moduł MSIdentityTools programu PowerShell.

Zainstaluj moduł MSIdentityTools programu PowerShell:
```
Install-Module -Name MSIdentityTools
```
Zaloguj się przy użyciu polecenia Connect-MgGraph z kontem administratora, aby wyrazić zgodę na wymagane zakresy:
```
 Connect-MgGraph -Scope "Application.ReadWrite.All"
```
Pobierz listę dostępnych odcisków palca klucza podpisywania:
```
Get-MsIdSigningKeyThumbprint
```
Wybierz dowolne odciski palca klucza i skonfiguruj identyfikator entra firmy Microsoft do używania tego klucza z aplikacją (pobierz identyfikator aplikacji z centrum administracyjnego firmy Microsoft Entra):
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <Thumbprint>
```
Przetestuj aplikację internetową, logując się, aby uzyskać nowy token. Zmiana aktualizacji klucza jest natychmiastowa, ale upewnij się, że używasz nowej sesji przeglądarki (na przykład w przeglądarce Internet Explorer "InPrivate", "Incognito" przeglądarki Chrome lub "Prywatnego" przeglądarki Firefox), aby upewnić się, że masz nowy token.
Dla każdego z zwróconych odcisków palca klucza podpisywania uruchom polecenie cmdlet i przetestuj Update-MsIdApplicationSigningKeyThumbprint proces logowania aplikacji internetowej.
Jeśli aplikacja internetowa prawidłowo się zaloguje, obsługuje automatyczne przerzucanie. Jeśli tak nie jest, zmodyfikuj aplikację, aby obsługiwała ręczne przerzucanie. Aby uzyskać więcej informacji, zobacz Ustanawianie ręcznego procesu przerzucania.

Uruchom następujący skrypt, aby przywrócić normalne zachowanie:

Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default

Jak wykonać ręczne przerzucanie, jeśli aplikacja nie obsługuje automatycznego przerzucania

Jeśli aplikacja nie obsługuje automatycznego przerzucania, należy ustanowić proces, który okresowo monitoruje klucze podpisywania Platforma tożsamości Microsoft i odpowiednio wykonuje ręczne przerzucanie.

Aby sprawdzić i zaktualizować klucze podpisywania przy użyciu programu PowerShell, potrzebny jest MSIdentityTools moduł programu PowerShell.

MSIdentityTools Zainstaluj moduł programu PowerShell:
```
Install-Module -Name MSIdentityTools
```
Pobierz najnowszy klucz podpisywania (pobierz identyfikator dzierżawy z centrum administracyjnego firmy Microsoft Entra):
```
Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
```
Porównaj ten klucz z kluczem, który aplikacja jest obecnie zakodowana lub skonfigurowana do użycia.
Jeśli najnowszy klucz różni się od klucza używanego przez aplikację, pobierz najnowszy klucz podpisywania:
```
Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
```
Zaktualizuj kod lub konfigurację aplikacji, aby użyć nowego klucza.
Skonfiguruj identyfikator entra firmy Microsoft, aby używać tego najnowszego klucza w aplikacji (pobierz identyfikator aplikacji z centrum administracyjnego firmy Microsoft Entra):
```
Get-MsIdSigningKeyThumbprint -Latest | Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId>
```
Przetestuj aplikację internetową, logując się, aby uzyskać nowy token. Zmiana aktualizacji klucza jest natychmiastowa, ale upewnij się, że używasz nowej sesji przeglądarki, aby upewnić się, że wystawiono nowy token. Na przykład użyj trybu "InPrivate" przeglądarki Microsoft Edge, przeglądarki Chrome "Incognito" lub "Prywatnego" przeglądarki Firefox.
Jeśli wystąpią jakiekolwiek problemy, wróć do poprzedniego klucza, którego używasz, i skontaktuj się z pomoc techniczna platformy Azure:
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -KeyThumbprint <PreviousKeyThumbprint>
```
Po zaktualizowaniu aplikacji w celu obsługi ręcznego przerzucania przywróć normalne zachowanie:
```
Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
```

Udostępnij za pośrednictwem

Przerzucanie klucza podpisywania w Platforma tożsamości Microsoft

Omówienie kluczy podpisywania w Platforma tożsamości Microsoft

Najlepsze rozwiązania dotyczące buforowania i walidacji metadanych kluczy

Algorytm buforowania metadanych kluczy:

Zagadnienia ogólne:

Procedura KeyRefresh (algorytm koncepcyjny z modelu IdentityModel)

Procedura KeyRefresh (pseudo code):

Procedura uruchamiania usługi:

Procedura TokenValidation sprawdzania poprawności klucza (kod pseudo):

Jak ocenić, czy aplikacja będzie miała wpływ na aplikację i co z tym zrobić

Natywne aplikacje klienckie, które uzyskują dostęp do zasobów

Aplikacje internetowe/interfejsy API, które uzyskują dostęp do zasobów

Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone przy użyciu usług aplikacja systemu Azure

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu ASP.NET OWIN OpenID Connect, WS-Fed lub WindowsAzureActiveDirectoryBearerAuthentication oprogramowania pośredniczącego

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu programu .NET Core OpenID Connect lub JwtBearerAuthentication oprogramowania pośredniczącego

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu modułu Node.js `passport-azure-ad`

Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2015 lub nowszego

Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2013

Internetowe interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2013

Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2012

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu innych bibliotek lub ręcznie implementowanie dowolnego z obsługiwanych protokołów

Jak przetestować aplikację, aby określić, czy będzie to miało wpływ

Jak wykonać ręczne przerzucanie, jeśli aplikacja nie obsługuje automatycznego przerzucania

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Przerzucanie klucza podpisywania w Platforma tożsamości Microsoft

Omówienie kluczy podpisywania w Platforma tożsamości Microsoft

Najlepsze rozwiązania dotyczące buforowania i walidacji metadanych kluczy

Algorytm buforowania metadanych kluczy:

Zagadnienia ogólne:

Procedura KeyRefresh (algorytm koncepcyjny z modelu IdentityModel)

Procedura KeyRefresh (pseudo code):

Procedura uruchamiania usługi:

Procedura TokenValidation sprawdzania poprawności klucza (kod pseudo):

Jak ocenić, czy aplikacja będzie miała wpływ na aplikację i co z tym zrobić

Natywne aplikacje klienckie, które uzyskują dostęp do zasobów

Aplikacje internetowe/interfejsy API, które uzyskują dostęp do zasobów

Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone przy użyciu usług aplikacja systemu Azure

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu ASP.NET OWIN OpenID Connect, WS-Fed lub WindowsAzureActiveDirectoryBearerAuthentication oprogramowania pośredniczącego

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu programu .NET Core OpenID Connect lub JwtBearerAuthentication oprogramowania pośredniczącego

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu modułu Node.js passport-azure-ad

Aplikacje internetowe/interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2015 lub nowszego

Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2013

Internetowe interfejsy API chroniące zasoby i tworzone za pomocą programu Visual Studio 2013

Aplikacje internetowe chroniące zasoby i tworzone za pomocą programu Visual Studio 2012

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu innych bibliotek lub ręcznie implementowanie dowolnego z obsługiwanych protokołów

Jak przetestować aplikację, aby określić, czy będzie to miało wpływ

Jak wykonać ręczne przerzucanie, jeśli aplikacja nie obsługuje automatycznego przerzucania

Opinia

Dodatkowe zasoby

Aplikacje internetowe/interfejsy API chroniące zasoby przy użyciu modułu Node.js `passport-azure-ad`