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 werden verstehen, wie die Schlüssel funktionieren und wie Sie die Auswirkungen des Rollovers auf Ihre Anwendung einschätzen können. Sie erfahren auch, wie Sie Ihre Anwendung aktualisieren oder einen regelmäßigen manuellen Rollover-Prozess einrichten, um bei Bedarf einen wichtigen Rollover zu bewältigen.

Ü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. Das Token wird von Microsoft Identity Platform mit dessen privatem Schlüssel signiert, bevor es zur 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 in die Microsoft Identity Platform integrierte Anwendung muss darauf vorbereitet sein, unabhängig von der Häufigkeit ein Schlüssel-Rollover-Ereignis zu verarbeiten. 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. Sie sollten Standardbibliotheken verwenden, um sicherzustellen, dass wichtige Metadaten korrekt aktualisiert und auf dem neuesten Stand gehalten werden. Wenn keine Standardbibliotheken verwendet werden, stellen Sie sicher, dass die Implementierung den bewährten Methoden entspricht.

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 in Ihrer Anwendung berücksichtigt werden. Weitere Informationen zur Datenstruktur von JSON Web Key finden Sie in RFC7517.

Anwendungen, die nur einen einzigen Unterzeichnerschlüssel unterstützen, oder Anwendungen, die manuelle Aktualisierungen der Unterzeichnerschlüssel erfordern, sind grundsätzlich weniger sicher und 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 Verfahren für die Zwischenspeicherung und Validierung von Schlüssel-Metadaten

• Ermitteln von Schlüsseln mithilfe des mandantenspezifischen Endpunkts wie in OpenID Connect (OIDC) und Verbundmetadaten beschrieben
• Selbst wenn Ihre Anwendung über mehrere Mandanten hinweg bereitgestellt wird, sollten Sie Schlüssel für jeden Mandanten, dem die Anwendung dient, immer separat ermitteln und zwischenspeichern (unter Verwendung des mandantenspezifischen Endpunkts). Ein Schlüssel, der heute für alle Mandanten gleich ist, kann in Zukunft für jeden Mandanten anders sein.
• Verwenden Sie den untenstehenden Zwischenspeicher-Algorithmus, um sicherzustellen, dass das Zwischenspeichern belastbar und sicher ist.

Algorithmus für das Zwischenspeichern von Schlüssel-Metadaten:

Unsere Standardbibliotheken implementieren eine robuste und sichere Zwischenspeicherung von Schlüsseln. Sie sollten sie verwenden, um subtile Mängel bei der Umsetzung zu vermeiden. Für benutzerdefinierte Implementierungen finden Sie hier den groben Algorithmus:

Allgemeine Überlegungen:

• Der Dienst, der die Token validiert, sollte über einen Zwischenspeicher verfügen, der viele verschiedene Schlüssel (10–1000) speichern kann.
• Die Schlüssel sollten einzeln zwischengespeichert werden, wobei die Schlüssel-ID („kid“ in der OIDC-Schlüssel-Metadatenspezifikation) als Zwischenspeicherschlüssel verwendet wird.
• Die Gültigkeitsdauer der Schlüssel im Cache sollte auf 24 Stunden konfiguriert werden, wobei stündlich Aktualisierungen erfolgen. Dadurch wird sichergestellt, dass das System schnell auf das Entfernen von Schlüsseln reagieren kann, aber über eine ausreichende Zwischenspeicherdauer verfügt, um nicht von Problemen beim Abrufen von Schlüsseln beeinträchtigt zu werden.
• Die Schlüssel sollten aktualisiert werden:
  • Sobald der Prozess gestartet wird oder wenn der Cache leer ist
  • In regelmäßigen Abständen (empfohlen jede Stunde) als Hintergrundprozess
  • Dynamisch, wenn ein empfangenes Token mit einem unbekannten Schlüssel (unbekannter kid oder tid im Header)

KeyRefresh-Verfahren (konzeptioneller Algorithmus von IdentityModel)

1. Initialisierung

   Der Konfigurationsmanager wird mit einer spezifischen Adresse zum Abrufen von Konfigurationsdaten und den erforderlichen Schnittstellen zum Abrufen und Validieren dieser Daten eingerichtet.

2. Überprüfung der Konfiguration

   Bevor neue Daten abgerufen werden, überprüft das System zunächst anhand eines vordefinierten Aktualisierungsintervalls, ob die vorhandenen Daten noch gültig sind.

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

4. Prüfung

   Sobald die neuen Daten abgerufen wurden, werden sie validiert, um sicherzustellen, dass sie den erforderlichen Standards entsprechen und nicht beschädigt sind. Die Metadaten werden nur akzeptiert, wenn eine eingehende Anfrage erfolgreich mit den neuen Schlüsseln validiert wurde.

5. Fehlerbehandlung

   Wenn beim Abrufen der Daten Fehler auftreten, werden diese protokolliert. Das System arbeitet mit der letzten als funktionierend bekannten Konfiguration weiter, wenn keine neuen Daten abgerufen werden können.

6. Automatische Updates Das System überprüft und aktualisiert die Konfigurationsdaten regelmäßig automatisch auf der Grundlage des Aktualisierungsintervalls (empfohlen werden 12 Stunden mit einer Abweichung von plus/minus 1 Stunde). Bei Bedarf kann auch manuell eine Aktualisierung angefordert werden, um sicherzustellen, dass die Daten immer aktuell sind.

7. Validierung eines Tokens mit einem neuen Schlüssel Wenn ein Token mit einem Signaturschlüssel empfangen wird, der in der Konfiguration noch nicht bekannt ist, versucht das System, die Konfiguration mit einem Synchronisierungsaufruf auf dem Hot Path abzurufen, um neue Schlüssel in Metadaten außerhalb der regulären erwarteten Aktualisierungen zu verarbeiten (jedoch nicht häufiger als alle 5 Minuten)

Dieser Ansatz stellt sicher, dass das System immer die aktuellsten und gültigen Konfigurationsdaten verwendet, während Fehler elegant behandelt und redundante Vorgänge vermieden werden.

Die .NET-Implementierung dieses Algorithmus ist über BaseConfigurationManagerverfügbar. Änderungen aufgrund von Bewertungen der Widerstandsfähigkeit und Sicherheit sind vorbehalten. Eine Erläuterung finden Sie auch hier.

KeyRefresh-Verfahren (Pseudocode):

Dieses Verfahren verwendet einen globalen (lastSuccessfulRefreshTime-Zeitstempel), um Bedingungen zu verhindern, die Schlüssel zu oft aktualisieren.

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

Autostartprozedur des Dienstes:

• KeyRefresh zum Aktualisieren der Schlüssel
• Starten Sie einen Hintergrundjob, der KeyRefresh stündlich aufruft.

TokenValidation-Verfahren zur Validierung 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 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.

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 in den Tabellen Mandanten und IssuingAuthorityKeys nicht löschen, erhalten Sie einen Laufzeitfehler.
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 Verbundmetadaten-Dokument 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. Möglicherweise verwenden Sie auch die Validierung der Ausstellernamenregistration (VINR). 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. Beachten Sie, dass der folgende Code in Ihrem Projekt bereits vorhanden ist. Wenn Ihre Anwendung diese Logik noch nicht enthält, führen Sie die folgenden Schritte aus, um sie hinzuzufügen und um sicherzustellen, dass sie korrekt 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. Falls bei der Anmeldung Probleme auftreten, vergewissern Sie sich, dass die Änderungen in Ihrer Anwendung korrekt sind. Lesen Sie hierzu den Artikel Hinzufügen einer Anmeldung zu einer Webanwendung mithilfe von Microsoft Identity Platform, oder laden Sie das folgende Codebeispiel herunter: Mehrinstanzenfähige Cloudanwendung für 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 bzw. die Implementierung überprüfen. Stellen Sie sicher, dass der Schlüssel entweder aus dem OpenID Connect Discovery-Dokument oder aus dem Verbundmetadaten-Dokument 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 Änderung des Schlüsselupdates erfolgt sofort, aber stellen Sie sicher, dass Sie eine neue Browsersitzung verwenden (z. B. mit Internet Explorer „InPrivate“, Chrome „Incognito“ oder dem Firefox „Private“-Modus), um sicherzustellen, dass Sie ein neues Token ausgestellt haben.

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
   

Gewusst wie: Durchführen eines manuellen Rollovers, falls die Anwendung keinen automatischen Rollover 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 PowerShell-Modul MSIdentityTools.

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 Änderung der Schlüsselaktualisierung erfolgt sofort. Vergewissern Sie sich jedoch, dass Sie eine neue Browsersitzung verwenden, um sicherzustellen, dass Sie ein neues Token erhalten. Verwenden Sie beispielsweise den „InPrivate“-Modus von Microsoft Edge, den „Incognito“-Modus von Chrome oder den „Private“-Modus von Firefox.

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