Konvertieren einer Einzelmandanten-App in eine mehrinstanzenfähige App in Microsoft Entra ID

  • Artikel

Wenn Sie vielen Organisationen eine SaaS-Anwendung (Software-as-a-Service) anbieten, können Sie Ihre Anwendung so konfigurieren, dass Anmeldungen von beliebigen Microsoft Entra-Mandanten akzeptiert werden, indem Sie sie in eine mehrinstanzenfähige App umwandeln. Benutzer eines Microsoft Entra-Mandanten können sich bei Ihrer Anwendung anmelden, nachdem sie zugestimmt haben, ihr Konto mit Ihrer Anwendung zu verwenden.

Für vorhandene Apps mit einem eigenen Kontosystem (oder Anmeldedaten anderer Cloudanbieter) sollten Sie Anmeldecode über OAuth2, OpenID Connect oder SAML hinzufügen und eine Schaltfläche Bei Microsoft anmelden in Ihre Anwendung einfügen.

In dieser Schrittanleitung führen Sie die vier Schritte aus, mit denen Sie eine Einzelmandanten-App in eine mehrinstanzenfähige Microsoft Entra-App umwandeln:

  1. Aktualisieren der Anwendungsregistrierung, sodass sie mehrinstanzenfähig ist
  2. Aktualisieren des Code, um Anforderungen an den /common-Endpunkt zu senden
  3. Aktualisieren des Codes zum Verarbeiten mehrerer Ausstellerwerte
  4. Interpretieren der Benutzer- und Administratorzustimmung und Vornehmen der entsprechenden Codeänderungen

Wenn Sie versuchen möchten, eines unserer Beispiele zu verwenden, siehe Erstellen einer Mehrinstanzen-SaaS-Webanwendung, die Microsoft Graph mithilfe von Microsoft Entra ID und OpenID Connect aufruft

Voraussetzungen

Aktualisieren der Registrierung, sodass sie mehrinstanzenfähig ist

Standardmäßig gelten Web-App-/API-Registrierungen bei ihrer Erstellung in Microsoft Entra ID für einen einzelnen Mandanten. Um die Registrierung mehrinstanzenfähig zu machen, melden Sie sich beim Microsoft Entra Admin Center an, und wählen Sie die App-Registrierung aus, die Sie aktualisieren möchten. Wählen Sie bei geöffneter App-Registrierung den Authentifizierungsbereich aus, und navigieren Sie zum Abschnitt Unterstützte Kontotypen. Ändern Sie die Einstellung in Konten in einem beliebigen Organisationsverzeichnis.

Wenn eine Einzelmandantenanwendung im Microsoft Entra Admin Center erstellt wird, ist eines der Elemente, die auf der Seite Übersicht aufgeführt sind, der Anwendungs-ID-URI. Sie stellt eine Möglichkeit dar, mit der eine Anwendung in Protokollnachrichten identifiziert wird, und sie kann jederzeit hinzugefügt werden. Der App-ID-URI für Einzelmandanten-Apps kann innerhalb dieses Mandanten global eindeutig sein. Im Gegensatz dazu muss sie für mehrinstanzenfähige Apps global eindeutig sein, damit sichergestellt wird, dass Microsoft Entra ID die App über alle Mandanten hinweg finden kann.

Wenn der Name Ihres Mandanten beispielsweise contoso.onmicrosoft.com lautet, wäre ein gültiger App-ID-URI https://contoso.onmicrosoft.com/myapp. Wenn der App-ID-URI nicht diesem Muster folgt, schlägt das Festlegen einer Anwendung als mehrinstanzenfähig fehl.

Aktualisieren des Codes zum Senden von Anforderungen an /common

Bei einer mehrinstanzenfähigen Anwendung kann die Anwendung nicht sofort erkennen, von welchem Mandanten Benutzer*innen stammen, sodass Anforderungen nicht an den Endpunkt eines Mandanten gesendet werden können. Stattdessen werden Anforderungen an einen gemeinsamen Endpunkt (https://login.microsoftonline.com/common) gesendet, der alle Microsoft Entra-Mandanten bedient und als zentraler Hub fungiert, der Anforderungen verarbeitet.

Öffnen Sie Ihre App in Ihrer IDE, bearbeiten Sie Ihren Code und ändern Sie den Wert für Ihre Mandanten-ID in /common. Dieser Endpunkt ist selbst kein Mandant oder Aussteller. Wenn Microsoft Identity Platform Anforderungen am /common-Endpunkt empfängt, werden die Benutzer*innen angemeldet. Dabei wird auch der Mandant der Benutzer*innen ermittelt. Dieser Endpunkt funktioniert mit allen von Microsoft Entra ID unterstützten Authentifizierungsprotokollen: OpenID Connect, OAuth 2.0, SAML 2.0 und WS-Verbund.

Die Anmeldeantwort an die Anwendung enthält dann ein Token, das den Benutzer darstellt. Anhand des Ausstellerwerts im Token erfährt eine Anwendung, von welchem Mandanten der Benutzer stammt. Wenn vom /common-Endpunkt eine Antwort zurückgegeben wird, entspricht der Ausstellerwert im Token dem Mandanten der Benutzer*innen.

Hinweis

Es gibt in Wirklichkeit zwei autoritative Stellen für mehrinstanzenfähige Anwendungen:

  • https://login.microsoftonline.com/common für Anwendungen, die Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra-Verzeichnis) und persönliche Microsoft-Konten (z. B. Skype, Xbox) verarbeiten.
  • https://login.microsoftonline.com/organizations für Anwendungen, die Konten in einem beliebigen Organisationsverzeichnis (beliebiges Microsoft Entra-Verzeichnis) verarbeiten:

In den Erläuterungen in diesem Dokument wird common verwendet. Sie können jedoch auch organizations einsetzen, wenn Ihre Anwendung keine persönlichen Microsoft-Konten unterstützt.

Aktualisieren des Codes zum Verarbeiten mehrerer Ausstellerwerte

Webanwendungen und Web-APIs empfangen und überprüfen Token von Microsoft Identity Platform. Native Anwendungen überprüfen Zugriffstoken nicht und müssen sie als nicht transparent behandeln. Sie fordern stattdessen Token von Microsoft Identity Platform an und senden die empfangenen Token zur Überprüfung an APIs.

Mehrinstanzenfähige Anwendungen müssen beim Überprüfen eines Tokens weitere Überprüfungen durchführen. Eine mehrinstanzenfähige Anwendung ist so konfiguriert, dass sie Schlüsselmetadaten der Schlüssel-URLs /organizations oder /common nutzt. Die Anwendung muss überprüfen, ob die Eigenschaft issuer in den veröffentlichten Metadaten mit dem Anspruch iss im Token übereinstimmt, zusätzlich zur üblichen Überprüfung, ob der Anspruch iss im Token den Anspruch der Mandanten-ID (tid) enthält. Weitere Informationen finden Sie unter Überprüfen von Token.

Damit sich ein Benutzer bei einer Anwendung in Microsoft Entra ID anmelden kann, muss die Anwendung im Mandanten des Benutzers dargestellt werden. Dies ermöglicht es der Organisation beispielsweise, eindeutige Richtlinien anzuwenden, wenn sich Benutzer ihres Mandanten bei der Anwendung anmelden. Für eine Einzelmandantenanwendung kann man die Registrierung über das Microsoft Entra Admin Center verwenden.

Bei einer mehrinstanzenfähigen Anwendung erfolgt die erste Registrierung für die Anwendung in dem Microsoft Entra-Mandanten, der vom Entwickler verwendet wurde. Wenn sich ein Benutzer von einem anderen Mandanten zum ersten Mal bei der Anwendung anmeldet, fordert Microsoft Entra ID ihn auf, den von der Anwendung angeforderten Berechtigungen zuzustimmen. Wenn er zustimmt, wird eine Darstellung der Anwendung, die als Dienstprinzipal bezeichnet wird, im Mandanten des Benutzers erstellt, und die Anmeldung kann fortgesetzt werden. Im Verzeichnis, das die Zustimmung des Benutzers zur Anwendung erfasst, wird auch eine Delegierung erstellt. Ausführliche Informationen zu Anwendungsobjekten und Dienstprinzipalobjekten der Anwendung und deren Beziehungen zueinander finden Sie unter Anwendungsobjekte und Dienstprinzipalobjekte.

Diagramm der Benutzereinwilligung zu einer App mit einer Ebene

Dieser Zustimmungsprozess wird durch die von der Anwendung angeforderten Berechtigungen beeinflusst. Die Microsoft Identity Platform unterstützt zwei Arten von Berechtigungen:

  • Delegiert: Diese Berechtigung gewährt einer Anwendung die Möglichkeit, für einen Teil der Funktionen, die der Benutzer ausführen kann, als angemeldeter Benutzer zu agieren. Sie können einer Anwendung z.B. die delegierte Berechtigung zum Lesen des Kalenders des angemeldeten Benutzers erteilen.
  • Nur App: Diese Berechtigung wird der Identität der Anwendung direkt gewährt. Beispielsweise können Sie einer Anwendung die nur für die App geltende Berechtigung zum Lesen der Liste der Benutzer in einem Mandanten erteilen, unabhängig davon, wer sich bei der Anwendung angemeldet hat.

Einigen Berechtigungen kann ein regulärer Benutzer zustimmen, während andere die Zustimmung eines Mandantenadministrators erfordern.

Weitere Informationen zur Benutzer- und Administratoreinwilligung finden Sie unter Konfigurieren des Workflows für die Administratoreinwilligung.

Nur für die App geltende Berechtigungen erfordern immer die Zustimmung eines Mandantenadministrators. Wenn die Anwendung eine nur für die App geltende Berechtigung anfordert und ein Benutzer versucht, sich bei der Anwendung anzumelden, wird eine Fehlermeldung angezeigt, die besagt, dass der Benutzer nicht zustimmen kann.

Bestimmte delegierte Berechtigungen erfordern ebenfalls die Zustimmung eines Mandantenadministrators. Beispielsweise erfordert die Funktion zum Zurückschreiben in Microsoft Entra ID als der angemeldete Benutzer die Zustimmung eines Mandantenadministrators. Wenn normale Benutzer*innen versuchen, sich bei einer Anwendung anzumelden, die eine delegierte Berechtigung anfordert, für die die Zustimmung durch Administrator*innen erforderlich ist, wird in Ihrer App ein Fehler angezeigt, wie es auch bei nur für die App geltenden Berechtigungen der Fall ist. Ob für eine Berechtigung die Zustimmung des Administrators erforderlich ist, wird durch den Entwickler bestimmt, der die Ressource veröffentlicht hat. Sie können dies in der Dokumentation für die Ressource nachlesen. In der Berechtigungsdokumentation für die Microsoft Graph-API ist angegeben, für welche Berechtigungen die Zustimmung des Administrators erforderlich ist.

Wenn Ihre Anwendung Berechtigungen nutzt, die eine Administratoreinwilligung erfordern, sollten Sie eine Schaltfläche oder einen Link hinzufügen, damit die Administrator*innen die Aktion initiieren können. Die Anforderung, die die Anwendung für diese Aktion sendet, ist die reguläre OAuth2/OpenID Connect-Autorisierungsanforderung, die zusätzlich den Abfragezeichenfolgen-Parameter prompt=consent enthält. Nachdem die Administrator*innen eingewilligt haben und der Dienstprinzipal im Mandanten der Kundschaft erstellt wurde, ist für nachfolgende Anmeldeanforderungen der prompt=consent-Parameter nicht mehr erforderlich. Da der Administrator entschieden hat, dass die angeforderten Berechtigungen zulässig sind, werden von diesem Zeitpunkt an keine anderen Benutzer im Mandanten zur Zustimmung aufgefordert.

Ein Mandantenadministrator kann die Funktion deaktivieren, dass reguläre Benutzer Anwendungen zustimmen. Wenn diese Funktion deaktiviert ist, ist die Zustimmung des Administrators immer erforderlich, damit die Anwendung im Mandanten verwendet werden kann. Sie können Ihre Anwendung mit deaktivierter Endbenutzerzustimmung im Microsoft Entra Admin Center testen. Aktivieren Sie in Enterprise-Anwendungen>Zustimmung und Berechtigungen die Option Benutzereinwilligung nicht zulassen.

Der Parameter prompt=consent kann auch von Anwendungen verwendet werden, die Berechtigungen anfordern, die keine Administratoreinwilligung erfordern. Ein Beispiel für einen Anwendungsfall lautet wie folgt: Für die Anwendung ist ein Vorgang erforderlich, bei dem sich der Administrator des Mandanten einmal registriert, und danach werden keine anderen Benutzer mehr zur Zustimmung aufgefordert.

Wenn für eine Anwendung die Zustimmung des Administrators erforderlich ist und sich ein Administrator anmeldet, ohne dass der Parameter prompt=consent gesendet wird, gilt die erfolgreiche Zustimmung des Administrators nur für sein Benutzerkonto. Reguläre Benutzer können sich weiterhin nicht anmelden und der Anwendung nicht zustimmen. Diese Funktion ist sinnvoll, wenn Sie dem Mandantenadministrator die Möglichkeit geben möchten, Ihre Anwendung zu untersuchen, bevor Sie anderen Benutzern Zugriff gewähren.

Ihre Anwendung weist möglicherweise mehrere Ebenen auf, die in Microsoft Entra ID jeweils durch eine eigene Registrierung dargestellt werden. Beispielsweise eine native Anwendung, die eine Web-API aufruft, oder eine Webanwendung, die eine Web-API aufruft. In beiden Fällen fordert der Client (native App oder Web-App) Berechtigungen an, um die Ressource (Web-API) aufzurufen. Damit dem Client erfolgreich die Zustimmung im Mandanten eines Kunden erteilt werden kann, müssen alle Ressourcen, für die Berechtigungen angefordert werden, bereits im Mandanten des Kunden vorhanden sein. Wenn diese Bedingung nicht erfüllt ist, gibt Microsoft Entra ID einen Fehler zurück, der besagt, dass die Ressource zuerst hinzugefügt werden muss.

Mehrere Ebenen in einem einzelnen Mandanten

Dies kann ein Problem sein, wenn die logische Anwendung aus zwei oder mehr Anwendungsregistrierungen besteht, z.B. separate Clients und Ressourcen. Wie sorgen Sie zuerst dafür, dass die Ressource im externen Mandanten vorhanden ist? Microsoft Entra ID behandelt diesen Fall, indem der Client und die Ressource, der zugestimmt werden soll, in einem einzigen Schritt aktiviert werden. Der Benutzer sieht die Gesamtsumme der Berechtigungen, die sowohl vom Client als auch von der Ressource auf der Seite „Zustimmung“ angefordert werden. Um dieses Verhalten zu ermöglichen, muss die Anwendungsregistrierung der Ressource die App-ID des Clients als knownClientApplications im Anwendungsmanifest enthalten. Beispiel:

"knownClientApplications": ["12ab34cd-56ef-78gh-90ij11kl12mn"]

Dies wird in einem Mehrinstanzenanwendungsbeispiel veranschaulicht. Die folgende Abbildung zeigt eine Übersicht über die Zustimmung für eine Mehrparteien-App, die in einem einzigen Mandanten registriert wurde.

Darstellung der Einwilligung zur bekannten Client-App mit mehreren Ebenen

Mehrere Ebenen in mehreren Mandanten

Ein ähnlicher Fall tritt ein, wenn die verschiedenen Ebenen einer Anwendung in verschiedenen Mandanten registriert sind. Betrachten Sie z.B. die Erstellung einer nativen Clientanwendung, die die Exchange Online-API aufruft. Um die native Anwendung zu entwickeln und sie später im Mandanten eines Kunden auszuführen, muss der Exchange Online-Dienstprinzipal vorhanden sein. In diesem Fall müssen der Entwickler und der Kunde Exchange Online erwerben, damit der Dienstprinzipal in seinen Mandanten erstellt wird.

Falls die API von einer anderen Organisation als Microsoft erstellt wurde, muss der Entwickler der API für Kunden eine Möglichkeit bieten, der Anwendung in den Mandanten der Kunden die Zustimmung zu erteilen. Der empfohlene Entwurf gilt für externe Entwickler, um die API so zu erstellen, dass sie auch als Webclient zur Implementierung der Registrierung fungieren kann. Gehen Sie hierzu folgendermaßen vor:

  1. Führen Sie die Schritte in den vorherigen Abschnitten durch, um sicherzustellen, dass die API die Registrierungs-/Codeanforderungen für mehrinstanzenfähige Anwendungen erfüllt.
  2. Stellen Sie neben der Bereitstellung der API-Bereiche/-Rollen sicher, dass die Registrierung die (standardmäßig bereitgestellte) Berechtigung „Anmelden und Benutzerprofil lesen“ beinhaltet.
  3. Implementieren Sie eine Anmelde-/Registrierungsseite im Webclient gemäß den Schritten unter Administratorzustimmung.
  4. Nach der Zustimmung des Benutzers bei der Anwendung werden die Dienstprinzipal- und Zustimmungsdelegierungsverknüpfungen in dessen Mandanten erstellt, und die systemeigene Anwendung kann Tokens für die API abrufen.

Die folgende Abbildung zeigt eine Übersicht über die Zustimmung für eine App mit mehreren Ebenen, die in verschiedenen Mandanten registriert wurde.

Darstellung der Einwilligung zu einer App mit mehreren Ebenen und Parteien

Benutzer und Administratoren können die Zustimmung zu Ihrer Anwendung jederzeit widerrufen:

  • Benutzer widerrufen den Zugriff auf einzelne Anwendungen, indem sie die jeweiligen Anwendungen aus der Liste Zugriffspanel – Anwendungen entfernen.
  • Administratoren widerrufen den Zugriff auf Anwendungen, indem sie diese über den Abschnitt Unternehmensanwendungen des Microsoft Entra Admin Centers entfernen. Wählen Sie die Anwendung aus, und navigieren Sie zur Registerkarte Berechtigungen , um den Zugriff zu widerrufen.

Wenn Administrator*innen einer Anwendung für alle Benutzer*innen in einem Mandanten ihre Einwilligung geben, können Benutzer*innen den Zugriff nicht einzeln widerrufen. Nur der Administrator kann den Zugriff widerrufen, und dies nur für die gesamte Anwendung.

Mehrinstanzenfähige Anwendungen und Zwischenspeichern von Zugriffstoken

Mehrinstanzenfähige Anwendungen können auch Zugriffstoken abrufen, um APIs aufzurufen, die von Microsoft Entra ID geschützt sind. Ein häufiger Fehler bei der Verwendung der Microsoft-Authentifizierungsbibliothek (Microsoft Authentication Library, MSAL) mit einer mehrinstanzenfähigen Anwendung ist, zuerst ein Token für Benutzer*innen mithilfe von /common anzufordern, eine Antwort zu erhalten und dann ein weiteres Token für dieselben Benutzer*innen ebenfalls mit /common anzufordern. Da die Antwort von Microsoft Entra ID von einem Mandanten stammt (und nicht von /common), speichert MSAL das Token als Token vom Mandanten zwischen. Beim nachfolgenden Aufruf von /common zum Abrufen eines Zugriffstokens für die Benutzer*innen wird der Cacheeintrag übersehen, und die Benutzer*innen werden aufgefordert, sich erneut anzumelden. Um zu vermeiden, dass Cacheeinträge übersehen werden, stellen Sie sicher, dass nachfolgende Aufrufe für einen bereits angemeldeten Benutzer dem Endpunkt des Mandanten gelten.

Siehe auch