SSO-Unterstützung (Single Sign-On) für Registerkarten

Benutzer melden sich bei Microsoft Teams über ihr Geschäfts-, Schul- oder Microsoft-Konto an, Outlook Office 365 ist, können Sie die Vorteile nutzen, indem Sie eine einmalige Anmeldung ermöglichen, um Ihre Teams Registerkarte oder Ihr Aufgabenmodul auf Desktop- oder mobilen Clients zu autorisieren. Wenn sich ein Benutzer einmal anmeldet, muss er sich nicht erneut auf einem anderen Gerät anmelden, da er automatisch angemeldet ist. Ihr Zugriffstoken wird ebenfalls vorab abgerufen, um die Leistung und die Ladezeiten zu verbessern.

Hinweis

Teams Versionen mobiler Clients, die SSO unterstützen

✔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 SDK (Version: 1.10 und höher) für SSO, um im Besprechungsseitigen Bereich zu arbeiten.

Um eine optimale Erfahrung mit Teams zu erzielen, verwenden Sie die neueste Version von iOS und Android.

Hinweis

Schnellstart

Der einfachste Weg für die ersten Schritte mit Tab-SSO ist das Teams-Toolkit für Visual Studio Code. Weitere Informationen finden Sie unter SSO mit Teams Toolkit und Visual Studio Code für Registerkarten

Funktionsweise von SSO zur Laufzeit

Die folgende Abbildung zeigt, wie der SSO-Prozess funktioniert:

Tab single sign-on SSO diagram
  1. In der Registerkarte wird ein JavaScript-Aufruf an getAuthToken() durchgeführt. getAuthToken()weist Teams an, ein Zugriffstoken für die Registerkartenanwendung abzurufen.
  2. Wenn der aktuelle Benutzer Ihre Registerkartenanwendung zum ersten Mal verwendet, wird eine Aufforderung zur Zustimmung angefordert, wenn eine Zustimmung erforderlich ist. Alternativ gibt es eine Anforderungsaufforderung für die Verarbeitung der Schrittauthentifizierung, z. B. die zweistufige Authentifizierung.
  3. Teams fordert das Registerkartenzugriffstoken vom Azure Active Directory(AAD)-Endpunkt für den aktuellen Benutzer an.
  4. AAD sendet das Registerkartenzugriffstoken an die Teams Anwendung.
  5. Teams sendet das Registerkartenzugriffstoken als Teil des ergebnisobjekts, das vom Aufruf zurückgegeben wird, an die getAuthToken() Registerkarte.
  6. Das Token wird in der Registerkartenanwendung mithilfe von JavaScript analysiert, um die erforderlichen Informationen wie die E-Mail-Adresse des Benutzers zu extrahieren.

Hinweis

Dies getAuthToken() gilt nur für die Zustimmung zu einer begrenzten Gruppe von APIs auf Benutzerebene, bei denen es sich um E-Mails, Profile, offline_access und OpenId handelt. Es wird nicht für weitere Graph Bereichen wie User.Read oder Mail.Read verwendet. Mögliche Problemumgehungen finden Sie unter Abrufen eines Zugriffstokens mit Graph Berechtigungen.

Die SSO-API funktioniert auch in Aufgabenmodulen, die Webinhalte einbetten.

Entwickeln einer SSO-Microsoft Teams-Registerkarte

In diesem Abschnitt werden die Aufgaben zum Erstellen einer Teams Registerkarte beschrieben, die SSO verwendet. Diese Aufgaben sind sprach- und frameworkunabhängig.

1. Erstellen Der AAD-Anwendung

So registrieren Sie Ihre Anwendung in der Übersicht über das AAD Portal

  1. Rufen Sie Ihre AAD Anwendungs-IDab.
  2. Geben Sie die Berechtigungen an, die Ihre Anwendung für den AAD Endpunkt benötigt, und optional Graph.
  3. Erteilen von Berechtigungen für Teams Desktop-, Web- und mobile Anwendungen.
  4. Autorisieren Sie Teams vorab, indem Sie auf die Schaltfläche "Bereich hinzufügen" klicken, und geben Sie im daraufhin geöffneten Bereich access_as_user als Bereichsnamen ein.

Hinweis

Es gibt einige wichtige Einschränkungen, die Sie kennen müssen:

  • Es werden nur Graph API-Berechtigungen auf Benutzerebene unterstützt, d. h. E-Mail, Profil, offline_access, OpenId. Wenn Sie Zugriff auf andere Graph Bereiche haben müssen, z. B. User.Read oder , finden Sie weitere Informationen unter Abrufen eines Mail.Read Zugriffstokens mit Graph Berechtigungen.
  • Es ist wichtig, dass der Domänenname Ihrer Anwendung mit dem Domänennamen übereinstimmt, den Sie für Ihre AAD Anwendung registriert haben.
  • Derzeit werden mehrere Domänen pro App nicht unterstützt.
  • Der Benutzer muss accessTokenAcceptedVersion 2 dies für eine neue Anwendung festlegen.

So registrieren Sie Ihre App über das AAD Portal

  1. Registrieren Sie eine neue Anwendung im Portal für AAD App-Registrierungen.

  2. Wählen Sie "Neue Registrierung" aus. Die Seite "Anwendung registrieren" wird angezeigt.

  3. Geben Sie auf der Seite "Anwendung registrieren" die folgenden Werte ein:

    1. Geben Sie einen Namen für Ihre App ein.
    2. Wählen Sie die unterstützten Kontotypen aus, wählen Sie den Kontotyp "Einzelner Mandant" oder "Mehrinstanzenkonto" aus. ¹
    • Lassen Sie URI umleiten leer.
    1. Wählen Sie Registrieren aus.
  4. Kopieren und speichern Sie auf der Übersichtsseite die Anwendungs-ID (Client-ID). Sie müssen ihn später haben, wenn Sie Ihr Teams Anwendungsmanifest aktualisieren.

  5. Wählen Sie unter Verwalten die Option Eine API verfügbar machen aus.

    Hinweis

    Wenn Sie eine App mit einem Bot und einer Registerkarte erstellen, geben Sie den Anwendungs-ID-URI als api://fully-qualified-domain-name.com/botid-{YourBotId} .

  6. Wählen Sie den Link "Festlegen" aus, um den Anwendungs-ID-URI in Form von zu api://{AppID} generieren. Fügen Sie Ihren vollqualifizierten Domänennamen mit einem schrägen Schrägstrich "/" an das Ende zwischen den doppelten Schrägstrichen und der GUID ein. Die gesamte ID muss die Form von api://fully-qualified-domain-name.com/{AppID} aufweisen. ² Beispiel: api://subdomain.example.com/00000000-0000-0000-0000-000000000000 . Der vollqualifizierte Domänenname ist der lesbare Domänenname, aus dem Ihre App bereitgestellt wird. Wenn Sie einen Tunneldienst wie ngrok verwenden, müssen Sie diesen Wert aktualisieren, wenn sich Ihre ngrok-Unterdomäne ändert.

  7. Wählen Sie Bereich hinzufügen. Geben Sie im daraufhin geöffneten Bereich access_as_user als Bereichsnamen ein.

  8. Geben Sie im Feld Wer zustimmen können? Administratoren und Benutzer ein.

  9. Geben Sie die Details in die Felder für die Konfiguration der Aufforderungen zur Administrator- und Benutzerzustimmung mit werten ein, die für den Bereich geeignet access_as_user sind:

    • Titel der Administratoreinwilligung: Teams kann auf das Benutzerprofil zugreifen.
    • Beschreibung der Administratorzustimmung: Teams können die Web-APIs der App als aktueller Benutzer aufrufen.
    • Benutzer-Zustimmungstitel: Teams können auf Ihr Profil zugreifen und Anforderungen in Ihrem Namen stellen.
    • Beschreibung der Benutzergenehmigung: Teams können die APIs dieser App mit den gleichen Rechten aufrufen wie Sie.
  10. Stellen Sie sicher, Zustand auf Aktiviert festgelegt ist.

  11. Wählen Sie "Bereich hinzufügen" aus, um die Details zu speichern. Der Domänenteil des Bereichsnamens, der unterhalb des Textfelds angezeigt wird, muss automatisch mit dem im vorherigen Schritt festgelegten Anwendungs-ID-URI übereinstimmen, /access_as_user wobei er am Ende angefügt api://subdomain.example.com/00000000-0000-0000-0000-000000000000/access_as_user wird.

  12. Identifizieren Sie im Abschnitt "Autorisierte Clientanwendungen" die Anwendungen, die Sie für die Webanwendung Ihrer App autorisieren möchten. Wählen Sie "Clientanwendung hinzufügen" aus. Geben Sie jede der folgenden Client-IDs ein, und wählen Sie den autorisierten Bereich aus, den Sie im vorherigen Schritt erstellt haben:

    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264für Teams Mobile- oder Desktopanwendung.
    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346für Teams Webanwendung.
  13. Navigieren Sie zu API-Berechtigungen. Wählen Sie eine Berechtigung Hinzufügen von Microsoft > Graph delegierte > Berechtigungen aus, und fügen Sie dann die folgenden Berechtigungen aus Graph API hinzu:

    • User.Read ist standardmäßig aktiviert
    • email
    • offline_access
    • Openid
    • Profil
  14. Navigieren Sie zur Authentifizierung.

    Wichtig

    Wenn einer App keine IT-Administratorzustimmung erteilt wurde, müssen Benutzer die Zustimmung erteilen, wenn sie eine App zum ersten Mal verwenden.

    So geben Sie einen Umleitungs-URI ein:

    • Wählen Sie "Plattform hinzufügen" aus.
    • Wählen Sie "Web" aus.
    • Geben Sie den Umleitungs-URI für Ihre App ein. Dieser URI ist der gleiche vollqualifizierte Domänenname, den Sie in Schritt 5 eingegeben haben. Es folgt auch die API-Route, an die eine Authentifizierungsantwort gesendet wird. Wenn Sie einem der Teams Beispiele folgen, lautet der URI https://subdomain.example.com/auth-end . Weitere Informationen finden Sie unter OAuth 2.0-Autorisierungscodefluss.

    Hinweis

    Für Tab-SSO ist keine implizite Genehmigung erforderlich.

Herzlichen Glückwunsch! Sie haben die Voraussetzungen für die App-Registrierung erfüllt, um mit Ihrer Registerkarten-SSO-App fortzufahren.

Hinweis

  • Wenn Ihre AAD-App im selben Mandanten registriert ist, in dem Sie eine Authentifizierungsanforderung in Teams stellen, kann der Benutzer nicht zur Zustimmung aufgefordert werden und erhält sofort ein Zugriffstoken. Benutzer stimmen diesen Berechtigungen nur zu, wenn die AAD App in einem anderen Mandanten registriert ist.
  • Wenn die benutzerdefinierte Domäne nicht zu AAD hinzugefügt wird, wird eine Fehlermeldung angezeigt, die besagt, dass der Hostname nicht auf einer domäne im Besitz des Unternehmens basieren darf. Um AAD eine benutzerdefinierte Domäne hinzuzufügen und zu registrieren, folgen Sie dem Hinzufügen eines benutzerdefinierten Domänennamens zu AAD Prozedur, und wiederholen Sie dann Schritt 5. Sie können diesen Fehler auch erhalten, wenn Sie nicht mit Administratoranmeldeinformationen im Office 365 Mandanten angemeldet sind.
  • Wenn Sie den Benutzerprinzipalnamen (USER Principal Name, UPN) im zurückgegebenen Zugriffstoken nicht erhalten, können Sie ihn als optionalen Anspruch in AAD hinzufügen.

2. Aktualisieren Des Teams Anwendungsmanifests

Verwenden Sie den folgenden Code, um ihrem Teams Manifest neue Eigenschaften hinzuzufügen:

"webApplicationInfo": {
  "id": "00000000-0000-0000-0000-000000000000",
  "resource": "api://subdomain.example.com/00000000-0000-0000-0000-000000000000"
}
  • WebApplicationInfo ist das übergeordnete Element der folgenden Elemente:
  • id – Die Client-ID der Anwendung. Dies ist die Anwendungs-ID, die Sie beim Registrieren der Anwendung bei Azure AD erhalten haben.
  • ressource – Die Domäne und Unterdomäne Ihrer Anwendung. Dies ist der gleiche URI (einschließlich des api:// Protokolls), den Sie beim Erstellen des in Schritt 6 registriert scope haben. Sie dürfen den Pfad nicht access_as_user in Ihre Ressource einschließen. Der Domänenteil dieses URI muss mit der Domäne übereinstimmen, einschließlich aller Unterdomänen, die in den URLs Ihres Teams Anwendungsmanifests verwendet werden.

Hinweis

  • Die Ressource für eine AAD App ist in der Regel der Stamm der Website-URL und der appID (z. B. api://subdomain.example.com/00000000-0000-0000-0000-000000000000 ). Dieser Wert wird auch verwendet, um sicherzustellen, dass Ihre Anforderung von derselben Domäne stammt. Stellen Sie sicher, dass die contentURL Registerkarte dieselben Domänen wie Ihre Ressourceneigenschaft verwendet.
  • Sie müssen die Manifestversion 1.5 oder höher verwenden, um das Feld zu webApplicationInfo implementieren.

3. Abrufen eines Zugriffstokens aus ihrem clientseitigen Code

Verwenden Sie die folgende Authentifizierungs-API:

var authTokenRequest = {
  successCallback: function(result) { console.log("Success: " + result); },
  failureCallback: function(error) { console.log("Failure: " + error); }
};
microsoftTeams.authentication.getAuthToken(authTokenRequest);

Wenn Sie anrufen getAuthToken und die Zustimmung des Benutzers für Berechtigungen auf Benutzerebene erforderlich ist, wird dem Benutzer ein Dialogfeld angezeigt, um seine Zustimmung zu erteilen.

Nachdem Sie das Zugriffstoken im Erfolgsrückruf erhalten haben, decodieren Sie das Zugriffstoken, um Ansprüche für dieses Token anzuzeigen. Optional können Sie zugriffstoken manuell kopieren und in ein Tool einfügen, z. B. jwt.ms. Wenn Sie den UPN im zurückgegebenen Zugriffstoken nicht erhalten, fügen Sie ihn als optionalen Anspruch in AAD hinzu. Weitere Informationen finden Sie unter Zugriffstoken.

Tab single sign-on SSO dialog prompt

Codebeispiel

Beispielname Beschreibung C# Node.js
Registerkarten-SSO Microsoft Teams Beispiel-App für Registerkarten Azure AD SSO View View,
Teams Toolkit

Bekannte Einschränkungen

Abrufen eines Zugriffstokens mit Graph Berechtigungen

Unsere aktuelle Implementierung für SSO erteilt nur die Zustimmung für Berechtigungen auf Benutzerebene, die nicht für Graph Aufrufe verwendet werden können. Um die Berechtigungen (Bereiche) abzurufen, die zum Ausführen eines Graph Aufrufs erforderlich sind, müssen SSO-Lösungen einen benutzerdefinierten Webdienst implementieren, um das vom Teams JavaScript SDK abgerufene Token gegen ein Token auszutauschen, das die erforderlichen Bereiche enthält. Dies erfolgt mithilfe AAD Im-Auftrag-von-Fluss.

Eine einfache Möglichkeit, im Namen einer Organisation als Mandantenadministrator zuzustimmen, besteht darin, auf diese zu https://login.microsoftonline.com/common/adminconsent?client_id=<AAD_App_ID> verweisen.

Ein weiterer Ansatz zum Abrufen Graph Bereichen besteht darin, ein Zustimmungsdialogfeld mithilfe unseres vorhandenen webbasierten Azure AD Authentifizierungsansatzzu präsentieren. Bei diesem Ansatz wird ein Azure AD Zustimmungsdialogfeld angezeigt.

So fordern Sie eine zusätzliche Zustimmung mithilfe der Auth-API an

  1. Das abgerufene Token getAuthToken() muss serverseitig mit AAD Im-Auftrag-von-Fluss ausgetauscht werden, um Zugriff auf diese anderen Graph-APIs zu erhalten. Stellen Sie sicher, dass Sie den v2-Graph-Endpunkt für diesen Austausch verwenden.
  2. Wenn der Austausch fehlschlägt, gibt AAD eine Ausnahme für ungültige Genehmigungen zurück. Es gibt in der Regel eine von zwei Fehlermeldungen invalid_grant oder interaction_required .
  3. Wenn der Austausch fehlschlägt, müssen Sie die Zustimmung anfordern. Zeigen Sie eine Benutzeroberfläche an, auf der der Benutzer aufgefordert wird, eine andere Zustimmung zu erteilen. Diese Benutzeroberfläche muss eine Schaltfläche enthalten, die mithilfe unserer AAD-Authentifizierungs-APIein AAD Zustimmungsdialogfeld auslöst.
  4. Wenn Sie mehr Zustimmung von AAD anfordern, müssen Sie prompt=consent den Abfragezeichenfolgenparameter in AAD einschließen, andernfalls werden AAD nicht nach den anderen Bereichen gefragt.
    • Statt ?scope={scopes}
    • Verwenden Sie diese ?prompt=consent&scope={scopes}
    • Stellen Sie sicher, dass {scopes} alle Bereiche enthalten sind, für die Sie den Benutzer auffordern, z. B. Mail.Read oder User.Read.
  5. Nachdem der Benutzer mehr Berechtigungen erteilt hat, wiederholen Sie den "Im Auftrag von"-Fluss, um Zugriff auf diese anderen APIs zu erhalten.

Nicht-AAD-Authentifizierung

Die oben beschriebene Authentifizierungslösung funktioniert nur für Apps und Dienste, die AAD als Identitätsanbieter unterstützen. Apps, die sich mit nicht AAD basierten Diensten authentifizieren möchten, müssen weiterhin den Popup-basierten Webauthentifizierungsflussverwenden.

Hinweis

SSO wird für kundeneigene Apps innerhalb der AAD B2C-Mandanten unterstützt.