Rollover von Signaturschlüsseln in Microsoft Identity Platform

In diesem Artikel wird erläutert, was Sie über die öffentlichen Schlüssel wissen müssen, die in Microsoft Identity Platform zum Signieren von Sicherheitstoken verwendet werden. Es sollte beachtet werden, dass für diese Schlüssel regelmäßig ein Rollover durchgeführt wird und dass in einem Notfall sofort ein Rollover erfolgen kann. Alle Anwendungen, die Microsoft Identity Platform verwenden, müssen den Schlüsselrollovervorgang programmgesteuert verarbeiten können. Sie verstehen, wie die Schlüssel funktionieren, wie Sie die Auswirkungen des Rollovers auf Ihre Anwendung bewerten. Außerdem erfahren Sie, wie Sie Ihre Anwendung aktualisieren oder bei Bedarf einen regelmäßigen manuellen Rolloverprozess einrichten, um den Schlüsselrollover zu verarbeiten.

Übersicht über Signaturschlüssel in Microsoft Identity Platform

Microsoft Identity Platform verwendet die auf Branchenstandards basierende Verschlüsselung mit öffentlichem Schlüssel zum Einrichten einer Vertrauensstellung zwischen sich selbst und den Anwendungen, die Microsoft Identity Platform verwenden. In der Praxis funktioniert dies wie folgt: Microsoft Identity Platform verwendet einen Signaturschlüssel, der aus einem Paar mit einem öffentlichen und einem privaten Schlüssel besteht. Wenn sich ein Benutzer bei einer Anwendung anmeldet, die Microsoft Identity Platform für die Authentifizierung verwendet, erstellt Microsoft Identity Platform ein Sicherheitstoken, das Informationen zum Benutzer enthält. Dieses Token wird von der Microsoft Identity Platform mit seinem privaten Schlüssel signiert, bevor es an die Anwendung zurückgesendet wird. Um zu überprüfen, ob das Token gültig ist und von Microsoft Identity Platform stammt, muss die Anwendung die Signatur des Tokens überprüfen. Hierzu wird der öffentliche, von Microsoft Identity Platform verfügbar gemachte Schlüssel verwendet, der im OpenID Connect-Ermittlungsdokument oder im SAML/WS-Fed-Verbundmetadaten-Dokument des Mandanten enthalten ist.

Aus Sicherheitsgründen führt Microsoft Identity Platform regelmäßig ein Rollover für den Signaturschlüssel durch, das im Notfall auch sofort erfolgen kann. Es gibt keine festgelegte oder garantierte Zeit zwischen diesen Schlüsselrollen. Jede Anwendung, die in die Microsoft Identity Platform integriert wird, sollte darauf vorbereitet sein, ein Schlüsselrolloverereignis zu behandeln, unabhängig davon, wie häufig es vorkommen kann. Wenn von Ihrer Anwendung plötzliche Aktualisierungen nicht verarbeitet werden und ein abgelaufener Schlüssel zum Überprüfen der Signatur in einem Token verwendet wird, wird das Token von Ihrer Anwendung fälschlicherweise abgelehnt. Es wird empfohlen, Standardbibliotheken zu verwenden, um sicherzustellen, dass wichtige Metadaten korrekt aktualisiert und auf dem neuesten Stand gehalten werden. In Fällen, in denen Standardbibliotheken nicht verwendet werden, stellen Sie sicher, dass die Implementierung dem Abschnitt "Bewährte Methoden " folgt.

Im OpenID Connect Discovery-Dokument und Verbundmetadaten-Dokument ist immer mehr als ein gültiger Schlüssel verfügbar. Ihre Anwendung sollte einen oder alle der im Dokument angegebenen Schlüssel verwenden können, da ein Schlüssel z. B. geändert oder durch einen anderen ersetzt werden kann usw. Die Anzahl der vorhandenen Schlüssel kann sich im Lauf der Zeit je nach der interne Architektur von Microsoft Identity Platform ändern, wenn neue Plattformen, neue Clouds oder neue Authentifizierungsprotokolle unterstützt werden. Weder die Reihenfolge der Schlüssel in der JSON-Antwort noch die Reihenfolge, in der sie verfügbar gemacht wurden, sollten für Ihre Anwendung als sinnvoll angesehen werden.

Anwendungen, die nur einen einzelnen Signaturschlüssel unterstützen, oder Anwendungen, die manuelle Updates für die Signaturschlüssel erfordern, sind inhärent weniger sicher und weniger zuverlässig. Sie sollten auf die Verwendung der Standardbibliotheken umgestellt werden, um sicherzustellen, dass sie immer die aktuellen Unterzeichnerschlüssel verwenden (neben anderen bewährten Methoden).

Bewährte Methoden für die Zwischenspeicherung und Validierung von Schlüsselmetadaten

• Ermitteln von Schlüsseln mithilfe des mandantenspezifischen Endpunkts, wie in OpenID Connect (OIDC) und Verbundmetadaten beschrieben
• Auch wenn Ihre Anwendung über mehrere Mandanten hinweg bereitgestellt wird, empfiehlt es sich, schlüssel unabhängig für jeden Mandanten zu ermitteln und zwischenzuspeichern, der von der Anwendung bereitgestellt wird (mithilfe des mandantenspezifischen Endpunkts). Ein Schlüssel, der heute über Mandanten hinweg gemeinsam ist, kann in Zukunft in verschiedenen Mandanten unterschieden werden.
• Verwenden Sie den folgenden Cachealgorithmus, um sicherzustellen, dass die Zwischenspeicherung stabil und sicher ist.

Schlüsselmetadatenzwischenspeicherungsalgorithmus:

Unsere Standardbibliotheken implementieren robustes und sicheres Zwischenspeichern von Schlüsseln. Es wird empfohlen, sie zu verwenden, um subtile Mängel bei der Implementierung zu vermeiden. Für benutzerdefinierte Implementierungen finden Sie hier den groben Algorithmus:

Allgemeine Überlegungen:

• Der Dienst, der Token überprüft, sollte über einen Cache verfügen, in dem viele unterschiedliche Schlüssel gespeichert werden können (10-1000).
• Die Schlüssel sollten einzeln zwischengespeichert werden, wobei die Schlüssel-ID ("kid" in der OIDC-Schlüsselmetadatenspezifikation) als Cacheschlüssel verwendet wird.
• Der Zeit-zu-Live-Ablauf von Schlüsseln im Cache sollte 24 Stunden konfiguriert werden, wobei jede Stunde Aktualisierungen stattfinden. Dadurch wird sichergestellt, dass das System schnell auf entfernte Schlüssel reagieren kann, aber über genügend Cachedauer verfügt, um nicht von Problemen beim Abrufen von Schlüsseln betroffen zu sein.
• Die Schlüssel sollten aktualisiert werden:
  • Einmal beim Starten des Prozesses oder beim Leeren des Caches
  • Regelmäßig (alle 1 Stunde empfohlen) als Hintergrundauftrag
  • Dynamisch, wenn ein empfangenes Token mit einem unbekannten Schlüssel signiert wurde (unbekanntes Kind oder Tid im Header)

KeyRefresh-Prozedur (Konzeptioneller Algorithmus von IdentityModel)

1. Initialisierung

   Der Konfigurations-Manager ist mit einer bestimmten Adresse zum Abrufen von Konfigurationsdaten und erforderlichen Schnittstellen zum Abrufen und Überprüfen dieser Daten eingerichtet.

2. Konfigurationsüberprüfung

   Vor dem Abrufen neuer Daten überprüft das System zunächst, ob die vorhandenen Daten weiterhin gültig sind, basierend auf einem vordefinierten Aktualisierungsintervall.

3. Datenabruf Wenn die Daten veraltet oder fehlen, sperrt das System, um sicherzustellen, dass nur ein Thread die neuen Daten abruft, um Duplizierung (und Threadausschöpfung) zu vermeiden. Das System versucht dann, die neuesten Konfigurationsdaten von einem angegebenen Endpunkt abzurufen.

4. Prüfung

   Nachdem die neuen Daten abgerufen wurden, wird sie überprüft, um sicherzustellen, dass sie die erforderlichen Standards erfüllt und nicht beschädigt ist. Die Metadaten werden nur akzeptiert, wenn eine eingehende Anforderung mit den neuen Schlüsseln erfolgreich überprüft wurde.

5. Fehlerbehandlung

   Wenn während des Datenabrufs Fehler auftreten, werden sie protokolliert. Das System funktioniert weiterhin mit der letzten bekannten guten Konfiguration, wenn neue Daten nicht abgerufen werden können.

6. Automatische Updates Das System überprüft und aktualisiert die Konfigurationsdaten automatisch basierend auf dem Aktualisierungsintervall (empfehlen 12 h mit einem Jitter von plus oder minus 1 h). Sie kann bei Bedarf auch manuell eine Aktualisierung anfordern, um sicherzustellen, dass die Daten immer aktuell sind.

7. Überprüfung eines Tokens mit einem neuen Schlüssel Wenn ein Token mit einem Signaturschlüssel eingeht, der noch nicht aus der Konfiguration bekannt ist, versucht das System, die Konfiguration mit einem Synchronisierungsaufruf auf dem heißen Pfad abzurufen, um neue Schlüssel in Metadaten außerhalb der regulären erwarteten Updates zu verarbeiten(aber nicht häufiger als 5 Minuten)

Mit diesem Ansatz wird sichergestellt, dass das System immer die aktuellsten und gültigsten Konfigurationsdaten verwendet, während Fehler ordnungsgemäß behandelt und redundante Vorgänge vermieden werden.

Die .NET-Implementierung dieses Algorithmus ist über BaseConfigurationManager verfügbar. Es unterliegt Änderungen basierend auf Resilienz- und Sicherheitsbewertungen. Siehe auch hier eine Erläuterung

KeyRefresh-Prozedur (Pseudocode):

Bei diesem Verfahren wird ein globaler Zeitstempel (lastSuccessfulRefreshTime timestamp) verwendet, um zu häufig zu aktualisierende Bedingungen zu verhindern.

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

Dienststartprozedur:

• KeyRefresh zum Aktualisieren der Schlüssel
• Starten eines Hintergrundauftrags, der KeyRefresh jede Stunde aufruft

TokenValidation-Prozedur zum Überprüfen des Schlüssels (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
    }
  }
}

Bewerten, ob Ihre Anwendung betroffen ist und welche Schritte erforderlich sind

Die Art und Weise, wie Ihre Anwendung den Schlüsselrollover behandelt, hängt von Variablen ab, z.B. dem Typ der Anwendung oder dem Identitätsprotokoll und der Bibliothek. In den folgenden Abschnitten wird bewertet, ob die häufigsten Arten von Anwendungen vom Schlüsselrollover betroffen sind. Außerdem enthalten sie eine Anleitung, wie Sie die Anwendung aktualisieren, damit der automatische Rollover oder die manuelle Aktualisierung des Schlüssels unterstützt werden.

• Native Clientanwendungen mit Ressourcenzugriff
• Webanwendungen/-APIs mit Ressourcenzugriff
• Mit Azure App Services erstellte Webanwendungen/-APIs zum Schutz von Ressourcen
• Webanwendungen/-APIs zum Schutz von Ressourcen unter Verwendung von ASP.NET OWIN OpenID Connect-, WS-Fed- oder WindowsAzureActiveDirectoryBearerAuthentication-Middleware
• Webanwendungen/-APIs zum Schutz von Ressourcen unter Verwendung von ASP.NET Core OpenID Connect- oder JwtBearerAuthentication-Middleware
• Webanwendungen/-APIs zum Schutz von Ressourcen mithilfe des Node.js-Moduls passport-azure-ad
• Mit Visual Studio 2015 oder höher erstellte Webanwendungen/-APIs zum Schutz von Ressourcen
• Mit Visual Studio 2013 erstellte Webanwendungen zum Schutz von Ressourcen
• Mit Visual Studio 2013 erstellte Web-APIs zum Schutz von Ressourcen
• Mit Visual Studio 2012 erstellte Webanwendungen zum Schutz von Ressourcen
• Webanwendungen/-APIs zum Schutz von Ressourcen unter Verwendung anderer Bibliotheken oder durch manuelle Implementierung unterstützter Protokolle

Ausnahmen:

• Bei Anwendungen, die über den Microsoft Entra-Anwendungskatalog hinzugefügt werden, steht jeweils ein separater Leitfaden für die Signatur mit Schlüsseln zur Verfügung. Weitere Informationen.
• Für lokale, mittels Anwendungsproxy veröffentlichte Anwendungen sind Signaturschlüssel nicht relevant.

Native Clientanwendungen mit Ressourcenzugriff

Anwendungen, die nur auf Ressourcen zugreifen (z. B. Microsoft Graph, KeyVault, Outlook-API und andere Microsoft-APIs), erhalten nur ein Token und geben es an den Besitzer der Ressource weiter. Da sie keine Ressourcen schützen, untersuchen sie das Token nicht und müssen somit auch nicht sicherstellen, dass es ordnungsgemäß signiert ist.

Native Clientanwendungen (sowohl für Desktop- als auch für Mobilgeräte) fallen in diese Kategorie und werden durch den Rollover nicht beeinträchtigt.

Webanwendungen/-APIs mit Ressourcenzugriff

Anwendungen, die nur auf Ressourcen zugreifen (z. B. Microsoft Graph, KeyVault, Outlook-API und andere Microsoft-APIs), erhalten nur ein Token und geben es an den Besitzer der Ressource weiter. Da sie keine Ressourcen schützen, untersuchen sie das Token nicht und müssen somit auch nicht sicherstellen, dass es ordnungsgemäß signiert ist.

Webanwendungen und Web-APIs, die den App-exklusiven Flow (Clientanmeldeinformationen/Clientzertifikat) nutzen, um Token anzufordern, fallen in diese Kategorie und werden durch den Rollover nicht beeinträchtigt.

Mit Azure App Services erstellte Webanwendungen/-APIs zum Schutz von Ressourcen

Die Authentifizierungs-/Autorisierungsfunktion von Azure App Services (EasyAuth) verfügt bereits über die erforderliche Logik zur automatischen Behandlung des Schlüsselrollovers.

Webanwendungen/-APIs zum Schutz von Ressourcen unter Verwendung von ASP.NET OWIN OpenID Connect-, WS-Fed- oder WindowsAzureActiveDirectoryBearerAuthentication-Middleware

Wenn Ihre Anwendung ASP.NET OWIN OpenID Connect-, WS-Fed- oder WindowsAzureActiveDirectoryBearerAuthentication-Middleware verwendet, verfügt sie bereits über die erforderliche Logik zur automatischen Behandlung des Schlüsselrollovers.

Sie können überprüfen, ob Ihre Anwendung diese Komponenten nutzt, indem Sie in der Datei „Startup.cs“ oder „Startup.Auth.cs“ der Anwendung nach den folgenden Codeausschnitten suchen.

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

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

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

Webanwendungen/-APIs zum Schutz von Ressourcen unter Verwendung von .NET Core OpenID Connect- oder JwtBearerAuthentication-Middleware

Wenn Ihre Anwendung ASP.NET OWIN OpenID Connect- oder JwtBearerAuthentication-Middleware verwendet, verfügt sie bereits über die erforderliche Logik zur automatischen Behandlung des Schlüsselrollovers.

Sie können überprüfen, ob Ihre Anwendung diese Komponenten nutzt, indem Sie in der Datei „Startup.cs“ oder „Startup.Auth.cs“ der Anwendung nach den folgenden Codeausschnitten suchen:

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

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

Webanwendungen/-APIs zum Schutz von Ressourcen mithilfe des Node.js-Moduls passport-azure-ad

Wenn Ihre Anwendung das Node.js-passport-ad-Modul verwendet, verfügt sie bereits über die erforderliche Logik zur automatischen Behandlung des Schlüsselrollovers.

Sie können überprüfen, ob Ihre Anwendung passport-ad verwendet, indem Sie in der Datei „app.js“ der Anwendung nach dem folgenden Codeausschnitt suchen:

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

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

Mit Visual Studio 2015 oder höher erstellte Webanwendungen/-APIs zum Schutz von Ressourcen

Wenn Ihre Anwendung mithilfe einer Webanwendungsvorlage in Visual Studio 2015 oder höher erstellt wurde und Sie im Menü Authentifizierung ändern die Option Geschäfts-, Schul- oder Unikonten ausgewählt haben, verfügt sie bereits über die erforderliche Logik zur automatischen Ausführung des Schlüsselrollovers. Mit dieser Logik, die in die OWIN OpenID Connect-Middleware eingebettet ist, werden die Schlüssel aus dem OpenID Connect Discovery-Dokument abgerufen und zwischengespeichert, sowie regelmäßig aktualisiert.

Wenn Sie die Authentifizierung Ihrer Lösung manuell hinzugefügt haben, verfügt die Anwendung unter Umständen nicht über die erforderliche Logik für einen Schlüsselrollover. Sie k0nnen diese Logik selbst erstellen oder die Schritte unter Webanwendungen/-APIs zum Schutz von Ressourcen unter Verwendung anderer Bibliotheken oder durch manuelle Implementierung unterstützter Protokolle ausführen.

Mit Visual Studio 2013 erstellte Webanwendungen zum Schutz von Ressourcen

Wenn Ihre Anwendung mithilfe einer Webanwendungsvorlage in Visual Studio 2013 erstellt wurde und Sie im Menü Authentifizierung ändern die Option Organisationskonten ausgewählt haben, verfügt sie bereits über die erforderliche Logik zur automatischen Behandlung des Schlüsselrollovers. Diese Logik speichert den eindeutigen Bezeichner Ihrer Organisation und die Signaturschlüsselinformationen in zwei Datenbanktabellen, die dem Projekt zugeordnet sind. Sie finden die Verbindungszeichenfolge für die Datenbank in der „Web.config“-Datei des Projekts.

Wenn Sie die Authentifizierung Ihrer Lösung manuell hinzugefügt haben, verfügt die Anwendung unter Umständen nicht über die erforderliche Logik für einen Schlüsselrollover. Sie müssen sie selbst schreiben oder die Schritte in Webanwendungen/APIs mithilfe anderer Bibliotheken oder manueller Implementierung eines der unterstützten Protokolle ausführen.

Die folgenden Schritte helfen Ihnen dabei, sicherzustellen, dass die Logik in Ihrer Anwendung korrekt funktioniert.

1. Öffnen Sie die Lösung in Visual Studio 2013, und wählen Sie im rechten Fenster die Registerkarte Server-Explorer aus.
2. Erweitern Sie Datenverbindungen, DefaultConnection und dann Tabellen. Suchen Sie die Tabelle IssuingAuthorityKeys, klicken Sie mit der rechten Maustaste darauf, und wählen Sie dann Tabellendaten anzeigen aus.
3. In der Tabelle IssuingAuthorityKeys befindet sich mindestens eine Zeile, die dem Fingerabdruckwert des Schlüssels entspricht. Löschen Sie alle Zeilen in der Tabelle.
4. Klicken Sie mit der rechten Maustaste auf die Tabelle Mandanten, und wählen Sie Tabellendaten anzeigen aus.
5. Die Tabelle Mandanten enthält mindestens eine Zeile, die einer eindeutigen Verzeichnismandanten-ID entspricht. Löschen Sie alle Zeilen in der Tabelle. Wenn Sie die Zeilen nicht in der Tabelle "Mandanten " und "IssuingAuthorityKeys " löschen, wird zur Laufzeit ein Fehler angezeigt.
6. Erstellen Sie die Anwendung, und führen Sie sie aus. Wenn Sie sich bei Ihrem Konto angemeldet haben, können Sie die Anwendung anhalten.
7. Kehren Sie zum Server-Explorer zurück, und sehen Sie sich die Werte in den Tabellen IssuingAuthorityKeys und Mandanten an. Sie werden feststellen, dass sie automatisch mit den entsprechenden Informationen aus dem Verbundmetadatendokument aufgefüllt wurden.

Mit Visual Studio 2013 erstellte Web-APIs zum Schutz von Ressourcen

Wenn Sie eine Web-API-Anwendung mithilfe der Web-API-Vorlage in Visual Studio 2013 erstellt und im Menü Authentifizierung ändern die Option Organisationskonten ausgewählt haben, verfügt sie bereits über die erforderliche Logik für einen Schlüsselrollover.

Wenn Sie die Authentifizierung manuell konfiguriert haben, gehen Sie folgendermaßen vor, um zu erfahren, wie Sie Ihre Web-API konfigurieren, damit die Schlüsselinformationen automatisch aktualisiert werden.

Der folgende Codeausschnitt veranschaulicht, wie die neuesten Schlüssel aus dem Verbundmetadaten-Dokument abgerufen werden und verwenden Sie anschließend den JWT-Tokenhandler, um das Token zu überprüfen. Bei diesem Codeausschnitt wird davon ausgegangen, dass Sie Ihre eigenen Verfahren zum Zwischenspeichern verwenden werden, um den Schlüssel zum Überprüfen zukünftiger Token von Microsoft Identity Platform in einer Datenbank, Konfigurationsdatei usw. dauerhaft zu aufzubewahren.

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

Mit Visual Studio 2012 erstellte Webanwendungen zum Schutz von Ressourcen

Wenn Ihre Anwendung in Visual Studio 2012 erstellt wurde, haben Sie wahrscheinlich das Identitäts- und Zugriffstool zum Konfigurieren Ihrer Anwendung verwendet. Es ist auch wahrscheinlich, dass Sie die Validating Issuer Name Registry (VINR) verwenden. Die VINR ist für die Verwaltung von Informationen zu vertrauenswürdigen Identitätsanbietern (Microsoft Identity Platform) und den Schlüsseln, die zum Überprüfen der von ihnen ausgestellten Token verwendet werden, zuständig. Die VINR erleichtert es zudem, die in einer „Web.config“-Datei gespeicherten Schlüsselinformationen automatisch zu aktualisieren, indem das aktuelle Ihrem Verzeichnis zugeordnete Verbundmetadaten-Dokument heruntergeladen wird. Mit dem aktuellen Dokument wird geprüft, ob die Konfiguration veraltet ist, und bei Bedarf wird die Anwendung aktualisiert, sodass der neue Schlüssel verwendet wird.

Wenn Sie die Anwendung mithilfe eines der Codebeispiele oder der von Microsoft bereitgestellten Dokumentation zur exemplarischen Vorgehensweise erstellt haben, ist die Logik für das Schlüsselrollover in Ihrem Projekt bereits enthalten. Sie werden feststellen, dass der folgende Code bereits in Ihrem Projekt vorhanden ist. Wenn Ihre Anwendung noch nicht über diese Logik verfügt, führen Sie die folgenden Schritte aus, um sie hinzuzufügen und zu überprüfen, ob sie ordnungsgemäß funktioniert.

1. Fügen Sie im Projektmappen-Explorer einen Verweis auf die System.IdentityModel-Assembly für das entsprechende Projekt hinzu.
2. Öffnen Sie die Datei Global.asax.cs , und fügen Sie die folgenden using-Direktiven hinzu:

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

3. Fügen Sie der Datei Global.asax.cs die folgende Methode hinzu:

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

4. Rufen Sie wie folgt die RefreshValidationSettings()-Methode in der Application_Start()-Methode in Global.asax.cs auf:

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

Nachdem Sie diese Schritte ausgeführt haben, wird die „Web.config“-Datei Ihrer Anwendung mit den neuesten Informationen aus den Verbundmetadaten-Dokument, einschließlich der neuesten Schlüssel, aktualisiert. Diese Aktualisierung erfolgt jedes Mal, wenn Ihr Anwendungspool in IIS wiederverwendet wird. Standardmäßig ist IIS so eingestellt, dass Anwendungen alle 29 Stunden wiederverwendet werden.

Gehen Sie folgendermaßen vor, um sicherzustellen, dass die Logik für das Schlüsselrollover funktioniert.

1. Nachdem Sie sich vergewissert haben, dass Ihre Anwendung den obigen Code verwendet, öffnen Sie die Datei Web.config und navigieren Sie zum Block <issuerNameRegistry>, wobei Sie insbesondere nach den folgenden Zeilen suchen:

   <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. In der Einstellung <add thumbprint=""> ändern Sie den Wert des Fingerabdrucks, indem Sie ein beliebiges Zeichen durch ein anderes ersetzen Speichern Sie die Datei Web.config .
3. Erstellen Sie die Anwendung, und führen Sie sie anschließend aus. Wenn Sie den Anmeldevorgang abschließen, aktualisiert die Anwendung den Schlüssel, indem die erforderlichen Informationen vom Verbundmetadaten-Dokument Ihres Verzeichnisses heruntergeladen werden. Wenn Sie Probleme beim Anmelden haben, stellen Sie sicher, dass die Änderungen in Ihrer Anwendung korrekt sind, indem Sie den Artikel zum Hinzufügen der Anmeldung zu Ihrer Webanwendung mithilfe von Microsoft Identity Platform lesen oder das folgende Codebeispiel herunterladen und prüfen: Multitenant Cloud Application for Microsoft Entra ID.

Webanwendungen/-APIs zum Schutz von Ressourcen unter Verwendung anderer Bibliotheken oder durch manuelle Implementierung unterstützter Protokolle

Wenn Sie eine andere Bibliothek verwenden oder eines der unterstützten Protokolle manuell implementiert haben, müssen Sie die Bibliothek oder Ihre Implementierung überprüfen, um sicherzustellen, dass der Schlüssel entweder aus dem OpenID Connect-Ermittlungsdokument oder dem Verbundmetadatendokument abgerufen wird. Eine Möglichkeit der Überprüfung ist das Durchsuchen Ihres Codes oder des Codes der Bibliothek nach Aufrufen des OpenID Discovery-Dokuments oder Verbundmetadaten-Dokuments.

Wenn der Schlüssel an einem Speicherort gespeichert wird oder in der Anwendung hartcodiert ist, können Sie ihn manuell abrufen und entsprechend aktualisieren, indem Sie gemäß den Anweisungen am Ende dieses Anleitungsdokuments einen manuellen Rollover durchführen. Es wird dringend empfohlen, Ihre Anwendung um Unterstützung des automatischen Rollovers zu erweitern, , wie in den Vorgehensweisen dieses Artikels beschrieben. So verhindern Sie zukünftige Störungen und Mehraufwand, wenn die Rolloverkadenz von Microsoft Identity Platform erhöht oder im Notfall ein außerplanmäßiges Rollover durchgeführt wird.

So ermitteln Sie, ob Ihre Anwendung betroffen ist

Mit den folgenden PowerShell-Skripten können Sie überprüfen, ob Ihre Anwendung ein automatisches Key Rollover unterstützt.

Zum Überprüfen und Aktualisieren von Signaturschlüsseln mit PowerShell benötigen Sie das MSIdentityTools-PowerShell-Modul.

1. Installieren Sie das MSIdentityTools-PowerShell-Modul:

   Install-Module -Name MSIdentityTools
   

2. Melden Sie sich mit dem Befehl Connect-MgGraph mit einem Administratorkonto an, um die erforderlichen Bereiche zu genehmigen:

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

3. Abrufen der Liste der verfügbaren Signaturschlüsselfingerabdrücke:

   Get-MsIdSigningKeyThumbprint
   

4. Wählen Sie einen der Schlüsselfingerabdrücke aus, und konfigurieren Sie Microsoft Entra ID für die Verwendung dieses Schlüssels mit Ihrer Anwendung (rufen Sie die App-ID aus dem Microsoft Entra Admin Center ab):

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

5. Testen Sie die Webanwendung, indem Sie sich anmelden, um ein neues Token abzurufen. Die Schlüsselaktualisierungsänderung erfolgt sofort, aber stellen Sie sicher, dass Sie eine neue Browsersitzung verwenden (z. B. internet Explorers "InPrivate", Chromes "Inkognito" oder Firefoxs "Privater" Modus), um sicherzustellen, dass Sie ein neues Token ausgegeben werden.

6. Führen Sie für jeden zurückgegebenen Signaturschlüsselfingerabdruck das Update-MsIdApplicationSigningKeyThumbprint Cmdlet aus und testen Sie den Anmeldevorgang Ihrer Webanwendung.

7. Wenn die Webanwendung Sie ordnungsgemäß anmeldet, unterstützt sie das automatische Rollover. Andernfalls ändern Sie Ihre Anwendung so, dass ein manueller Rollover unterstützt wird. Weitere Informationen finden Sie unter Einrichten eines manuellen Rolloverprozesses.

8. Führe das folgende Skript aus, um zum normalen Verhalten zurückzukehren:

   Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default
   

So führen Sie einen manuellen Rollover aus, wenn Ihre Anwendung den automatischen Rollover nicht unterstützt

Falls Ihre Anwendung keinen automatischen Rollover unterstützt, müssen Sie einen Prozess einrichten, der in regelmäßigen Abständen die Signaturschlüssel von Microsoft Identity Platform überprüft und entsprechend einen manuellen Rollover durchführt.

Zum Überprüfen und Aktualisieren von Signaturschlüsseln mit PowerShell benötigen Sie das MSIdentityTools PowerShell-Modul.

1. Installieren des MSIdentityToolsPowerShell-Moduls:

   Install-Module -Name MSIdentityTools
   

2. Rufen Sie den neuesten Signaturschlüssel ab (rufen Sie die Mandanten-ID aus dem Microsoft Entra Admin Center ab):

   Get-MsIdSigningKeyThumbprint -Tenant <tenandId> -Latest
   

3. Vergleichen Sie diesen Schlüssel mit dem Schlüssel, den Ihre Anwendung derzeit hartcodiert oder für die Verwendung konfiguriert hat.

4. Wenn sich der neueste Schlüssel von dem Schlüssel unterscheidet, den Ihre Anwendung verwendet, laden Sie den neuesten Signaturschlüssel herunter:

   Get-MsIdSigningKeyThumbprint -Latest -DownloadPath <DownloadFolderPath>
   

5. Aktualisieren Sie den Code oder die Konfiguration Ihrer Anwendung, um den neuen Schlüssel zu verwenden.

6. Konfigurieren Sie Microsoft Entra ID für die Verwendung dieses aktuellen Schlüssels mit Ihrer Anwendung (rufen Sie die App-ID aus dem Microsoft Entra Admin Center ab):

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

7. Testen Sie die Webanwendung, indem Sie sich anmelden, um ein neues Token abzurufen. Die Schlüsselaktualisierungsänderung erfolgt sofort, aber stellen Sie sicher, dass Sie eine neue Browsersitzung verwenden, um sicherzustellen, dass Sie ein neues Token ausgestellt haben. Verwenden Sie z. B. den "InPrivate"-Modus von Microsoft Edge, chromes "Inkognito", oder den Firefox-Modus "Privat".

8. Wenn Probleme auftreten, kehren Sie zum vorherigen Schlüssel zurück, den Sie verwendet haben, und wenden Sie sich an den Azure-Support:

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

9. Nachdem Sie Ihre Anwendung aktualisiert haben, um einen manuellen Rollover zu unterstützen, kehren Sie zum normalen Verhalten zurück:

   Update-MsIdApplicationSigningKeyThumbprint -ApplicationId <ApplicationId> -Default