Aktivieren von SSO für die Registerkarten-App

  • Artikel

Mit dem einmaligen Anmelden (Single Sign-On, SSO) in Teams haben App-Benutzer den Vorteil, dass Teams für den Zugriff auf Registerkarten-Apps verwendet wird. Nach der Anmeldung bei Teams mit einem Microsoft- oder Microsoft 365-Konto können App-Benutzer Ihre App verwenden, ohne sich erneut anmelden zu müssen. Ihre App ist für App-Benutzer auf jedem Gerät verfügbar, auf dem der Zugriff über Microsoft Entra ID gewährt wird.

Hier erfahren Sie, was Sie in diesem Abschnitt lernen:

  1. SSO-Benutzererfahrung: Teams bietet Ihren App-Benutzern eine echte SSO-Erfahrung. Die App-Benutzer können Ihre App verwenden, ohne sich erneut anzumelden.
  2. SSO in Teams zur Laufzeit: Ihre Registerkarten-App interagiert mit Microsoft Entra ID zur Laufzeit für einmalige Authentifizierung und Autorisierung für Ihre App-Benutzer.
  3. Aktivieren des einmaligen Anmeldens für Ihre Registerkarten-App: Implementieren Sie die aufgaben zum Aktivieren des einmaligen Anmeldens in Ihrer Registerkarten-App.

SSO-Benutzererfahrung in Teams

Die App-Benutzer melden sich bei Teams entweder mit einem persönlichen Microsoft-Konto oder einem Microsoft 365-Konto an. Sie können dieses Konto nutzen und SSO verwenden, um die App-Benutzer zu authentifizieren und zu autorisieren.

Screenshot: SSO-Benutzeroberfläche in einer Teams-Registerkarten-App

  • Teams authentifiziert und speichert die Identität des App-Benutzers.
  • Ihre Registerkarten-App verwendet die gespeicherte Identität des App-Benutzers, der bereits von Teams überprüft wurde.
  • Der App-Benutzer muss Teams seine Zustimmung für die Verwendung der Identität für den Zugriff auf Ihre Registerkarten-App erteilen.
  • Der App-Benutzer kann auf die App im Web, Desktop oder mobilen Client zugreifen.

Sie können hier ein Beispiel für die Benutzererfahrung mit SSO in einer Registerkarten-App anzeigen:

Die grafische Darstellung zeigt die Benutzererfahrung von SSO in der Registerkarten-App.

Verbessern der Benutzerfreundlichkeit mit SSO

Hier erfahren Sie, was Ihre App-Benutzer mit SSO-Erfahrung erhalten:

  • Teams ruft das Zugriffstoken für den aktuellen App-Benutzer von Microsoft Entra ID ab. Diese Interaktion mit Microsoft Entra ID ist für den App-Benutzer unsichtbar. Dies bedeutet, dass sie Zugriff auf die App erhält, ohne die Teams-Umgebung verlassen zu müssen.
  • Ein App-Benutzer muss nur in einer mehrinstanzenfähigen Umgebung zustimmen. Wenn sich der App-Benutzer und die App im selben Mandanten befinden, muss der App-Benutzer der Verwendung der App nicht zustimmen.
  • Nachdem der App-Benutzer Teams das erste Mal zugestimmt hat, kann er Ihre App ohne weitere Zustimmung verwenden, auch auf jedem anderen Gerät. Aus diesem Grund bietet es eine bessere Benutzererfahrung.
    • Alternativ kann der Mandantenadministrator die Zustimmung im Namen der App-Benutzer erteilen. Wenn in diesem Szenario der Mandantenadministrator den App-Benutzern im Mandanten zustimmt, müssen die App-Benutzer überhaupt nicht zur Zustimmung aufgefordert werden. Dies bedeutet, dass die App-Benutzer die Zustimmungsdialoge nicht sehen und nahtlos auf die App zugreifen können.
  • Das Zugriffstoken wird von Teams vorab abgerufen, um die Leistung und Ladezeit der App in der Teams-Umgebung zu verbessern.
  • Die App-Benutzer müssen sich nicht mehrere Kennwörter merken oder aufzeichnen, um auf Apps in der Teams-Umgebung zuzugreifen und diese zu verwenden.

Sehen wir uns nun an, was während der Laufzeit im Back-End geschieht, um die SSO-Erfahrung in Teams zu erreichen.

SSO in Teams zur Laufzeit

Erzielen Sie SSO in einer Registerkarten-App, indem Sie ein Zugriffstoken für den Benutzer der Teams-App abrufen, der aktuell angemeldet ist. Dieser Prozess umfasst den Tab-App-Client und -Server, den Teams-Client und Microsoft Entra ID. Während dieser Interaktion muss der App-Benutzer die Zustimmung zur Verwendung der Teams-Identität erteilen, um das Zugriffstoken in einer mehrinstanzenfähigen Umgebung abzurufen.

Die folgende Abbildung zeigt, wie SSO funktioniert, wenn ein Benutzer einer Teams-App versucht, auf die Registerkarten-App zuzugreifen:

Screenshot: Ablauf des SSO-Prozesses auf der Registerkarte und dessen Funktionsweise

# Interaktion Was gerade geschieht
1 Registerkarten-App → Teams-Client Die Registerkarten-App führt einen JavaScript-Aufruf durch getAuthToken(), der Teams angibt, ein Zugriffstoken abzurufen.
2 Teams-Client-→ Microsoft Entra ID Teams fordert Microsoft Entra Endpunkt für das Zugriffstoken für den aktuellen App-Benutzer basierend auf der Teams-Identität an.
3 Microsoft Entra ID → Zustimmungsformular Wenn der aktuelle App-Benutzer Ihre Registerkarten-App zum ersten Mal verwendet, zeigt Teams die Aufforderung zur Zustimmung an, wenn die App auf einige geschützte Daten zugreifen muss. Der App-Benutzer (oder der Administrator) muss Teams die Zustimmung für die Verwendung der Teams-Identität des App-Benutzers erteilen, um Zugriffstoken von Microsoft Entra ID abzurufen.
Alternativ gibt es eine Aufforderung, eine erhöhte Authentifizierung durchführen, z. B. die zweistufige Authentifizierung.
4 Microsoft Entra ID → Teams-Client Microsoft Entra ID sendet das Zugriffstoken an den Teams-Client. Das Token ist ein JSON Web Token (JWT), und seine Überprüfung funktioniert genau wie die Tokenvalidierung in den meisten standardmäßigen OAuth-Flows. Office speichert das Token in Ihrem Namen zwischen, sodass zukünftige Aufrufe von getAuthToken() einfach das zwischengespeicherte Token zurückgeben.
5 Teams-Client → Registerkarten-App-Client Teams sendet das Registerkartenzugriffstoken als Teil des Ergebnisobjekts, das vom getAuthToken()-Aufruf zurückgegeben wird, an die Registerkarte.
6 Tab-App (zwischen Client und Server) Das Token wird in der Registerkartenanwendung mithilfe von JavaScript analysiert, um die erforderlichen Informationen wie z. B. die E-Mail-Adresse des Benutzers zu extrahieren. Das an die Registerkarten-App zurückgegebene Token ist sowohl ein Zugriffstoken als auch ein ID-Token.

Weitere Informationen finden Sie unter Hinzufügen von Code zum Aktivieren von SSO in einer Registerkarten-App und Hinzufügen von Code zum Aktivieren des einmaligen Anmeldens in Ihrer Bot-App.

Wichtig

  • Dies getAuthToken() gilt nur für die Zustimmung zu einer begrenzten Gruppe von APIs auf Benutzerebene, d. h. E-Mail, Profil, offline_access und OpenId. Es wird nicht für weitere Graph-Bereiche wie User.Read oder Mail.Read verwendet. Vorgeschlagene Problemumgehungen finden Sie unter Erweitern Ihrer App mit Microsoft Graph-Berechtigungen.
  • Bei getAuthToken anonymen Benutzern tritt ein Fehler auf, da sie keine Microsoft Entra Konten sind.

Registerkarten sind Microsoft Teams-fähige Webseiten. Um einmaliges Anmelden auf einer Webseite zu aktivieren, die in einer Registerkarten-App gehostet wird, fügen Sie die Teams JavaScript-Clientbibliothek hinzu, und rufen Sie auf microsoftTeams.initialize(). Rufen Sie microsoftTeams.getAuthToken() nach der Initialisierung das Zugriffstoken für Ihre App ab.

Anwendungsfälle zum Aktivieren von SSO

Sie können SSO in Teams für alle Apps aktivieren, die Microsoft Entra ID als Identitätsanbieter unterstützen. Zusätzlich zur Verwendung von SSO für die Authentifizierung von App-Benutzern in einer Registerkarten-App können Sie es auch verwenden, um den nahtlosen Zugriff über Teams hinweg zu ermöglichen.

Einige Szenarien, in denen Sie die SSO-API verwenden können, um Ihre App-Benutzer zu authentifizieren, sind:

  • Wenn Sie Ihre App-Benutzer in einer Teams-Registerkarten-App authentifizieren möchten, ermöglicht die SSO-API App-Benutzern die Verwendung Ihrer App in Teams ohne zusätzliche Authentifizierung. Basierend auf der Teams-Identität des App-Benutzers können Sie das Zugriffstoken für den Benutzer aus Microsoft Entra ID abrufen.
  • Wenn Ihre App Dialoge (in TeamsJS v1.x als Aufgabenmodule bezeichnet) aus einem Bot, einer Registerkarte, einer Nachrichtenerweiterung oder adaptiven Karten verwendet, können Sie die SSO-API verwenden, um Ihre App-Benutzer zu authentifizieren.
  • Sie können auch die SSO-API verwenden, um Ihre App-Benutzer zu authentifizieren, die auf Stageview zugreifen möchten, ohne erneut überprüft werden zu müssen.

Tipp

Sie können die SSO-API auch verwenden, um App-Benutzer in Dialogfeldern zu authentifizieren , die Webinhalte einbetten.

Um SSO zur Laufzeit zu erreichen, konfigurieren Sie Ihre App so, dass SSO für die Authentifizierung und Autorisierung von App-Benutzern aktiviert wird.

Aktivieren des einmaligen Anmeldens für eine Teams-Registerkarten-App

In diesem Abschnitt werden die Aufgaben beschrieben, die bei der Implementierung von SSO für eine Teams-App erforderlich sind. Diese Aufgaben sind sprach- und frameworkunabhängig.

So aktivieren Sie einmaliges Anmelden für eine Teams-Registerkarten-App:

       Screenshot: Schritte zum Aktivieren des einmaligen Anmeldens für die Registerkarte

  1. App mit Microsoft Entra ID konfigurieren: Erstellen Sie eine Microsoft Entra App, um eine App-ID und einen Anwendungs-ID-URI zu generieren. Konfigurieren Sie Zum Generieren von Zugriffstoken Bereiche und autorisieren Sie vertrauenswürdige Clientanwendungen.
  2. Code hinzufügen: Fügen Sie den Code zum Verarbeiten des Zugriffstokens hinzu, senden Sie dieses Token im Autorisierungsheader an den Servercode Ihrer App, und überprüfen Sie das Zugriffstoken, wenn es empfangen wird.
  3. Aktualisieren des Teams-App-Manifests: Aktualisieren Sie Ihr Teams-Client-App-Manifest mit der App-ID und dem Anwendungs-ID-URI, die auf Microsoft Entra ID generiert wurden, damit Teams Zugriffstoken im Namen Ihrer App anfordern kann.

Cookies von Drittanbietern unter iOS

Nach dem iOS 14-Update hat Apple standardmäßig den Zugriff auf Cookies von Drittanbietern für alle Apps blockiert. Daher können die Apps, die Cookies von Drittanbietern für die Authentifizierung auf ihren Registerkarten "Kanal" oder "Chat" und "Persönliche Apps" verwenden, ihre Authentifizierungsworkflows auf Teams iOS-Clients nicht abschließen. Um den Datenschutz- und Sicherheitsanforderungen zu entsprechen, müssen Sie zu einem tokenbasierten System wechseln oder Cookies von Erstanbietern für die Benutzerauthentifizierungsworkflows verwenden.

Support für mobile Teams-Clients

Für mobile Teams sind Clientversionen, die SSO unterstützen, folgende:

  • Teams für Android (1416/1.0.0.2020073101 und höher)
  • Teams für iOS (Version: 2.0.18 und höher)
  • Teams JavaScript-Bibliothek (Version: 1.11 und höher), damit SSO im Besprechungsseitenbereich funktioniert

Für eine optimale Benutzererfahrung verwenden Sie die jeweils neueste Version von iOS und Android.

Schritt-für-Schritt-Anleitungen

Verwenden Sie die folgenden schrittweisen Anleitungen zum Aktivieren von SSO für die Teams-App:

Bewährte Methoden

Hier ist eine Liste der bewährten Methoden:

  • Rufen Sie das Zugriffstoken nur auf, wenn Sie es benötigen: Rufen Sie getAuthToken() nur auf, wenn Sie ein Zugriffstoken benötigen. Sie können sie aufrufen, wenn ein App-Benutzer auf Ihre Registerkarten-App zugreift, oder um eine bestimmte Funktion zu verwenden, für die eine App-Benutzerüberprüfung erforderlich ist.
  • Speichern Sie das Zugriffstoken nicht im clientseitigen Code: Speichern Sie das Zugriffstoken nicht im clientseitigen Code Ihrer App. Der Teams-Client speichert das Zugriffstoken zwischen (oder fordert ein neues an, wenn es abläuft). Dadurch wird sichergestellt, dass ihr Token nicht versehentlich aus Ihrer Web-App ausläuft.
  • Verwenden Sie serverseitigen Code für Microsoft Graph-Aufrufe: Verwenden Sie immer den serverseitigen Code, um Microsoft Graph-Aufrufe oder andere Aufrufe auszuführen, die das Übergeben eines Zugriffstokens erfordern. Geben Sie niemals das OBO-Token an den Client zurück, damit der Client direkte Aufrufe an Microsoft Graph durchführen kann. Dadurch wird verhindert, dass der Token abgefangen oder weitergegeben werden kann. Weitere Informationen finden Sie unter Erweitern der Registerkarten-App mit Microsoft Graph-Berechtigungen und -Bereich.

Bekannte Einschränkungen

  • Derzeit unterstützt SSO in Teams nur OAuth 2.0-Token. Es unterstützt kein SAML-Token.
  • Mehrere Domänen pro App werden nicht unterstützt. Weitere Informationen finden Sie unter Benutzerdefinierte Apps, die für Ihre Organisation (BRANCHEN-Apps) erstellt wurden.
  • Umleitungen werden für iframed- oder Broker-Apps nicht unterstützt. Stellen Sie sicher, dass Sie MSAL.js im oberen Rahmen des Fensters verwenden, wenn Sie die Umleitungs-APIs oder die Popup-API (window.parent!==window) => trueverwenden.

Nächster Schritt

Registrieren Ihrer Registerkartenanwendung in Microsoft Entra ID

Siehe auch