Konfigurieren der OAuth-IdP-Authentifizierung von Drittanbietern

  • Artikel

Hinweis

Damit die Authentifizierung für Ihre Registerkarte auf mobilen Clients funktioniert, stellen Sie sicher, dass Sie Version 1.4.1 oder höher der Microsoft Teams JavaScript-Clientbibliothek (TeamsJS) verwenden.

Ihre Microsoft Teams-App muss möglicherweise mit verschiedenen Diensten wie Facebook, Twitter und Teams interagieren. Die meisten dieser Dienste erfordern eine Authentifizierung und Autorisierung für den Zugriff. Teams speichert Benutzerprofilinformationen in Microsoft Entra-ID mithilfe von Microsoft Graph. Dieser Artikel konzentriert sich hauptsächlich auf die Verwendung Microsoft Entra-ID für die Authentifizierung, um auf diese Informationen zuzugreifen.

OAuth 2.0, ein offener Standard für die Authentifizierung, wird von Microsoft Entra ID und zahlreichen anderen Dienstanbietern verwendet. Das Verständnis von OAuth 2.0 ist für die Authentifizierung in Teams und Microsoft Entra-ID von entscheidender Bedeutung. In den bereitgestellten Beispielen wird der Flow "Implizite OAuth 2.0-Genehmigung" verwendet, der die Profilinformationen des Benutzers aus Microsoft Entra-ID und Microsoft Graph abruft.

Der Code in diesem Artikel stammt aus der Microsoft Teams-Beispiel-Authentifizierungsbeispiel (Node) der Teams-Beispiel-App. Sie enthält eine statische Registerkarte, die ein Zugriffstoken für Microsoft Graph anfordert, und zeigt die grundlegenden Profilinformationen des aktuellen Benutzers aus Microsoft Entra ID an.

Eine Übersicht über den Authentifizierungsfluss für Registerkarten finden Sie unter Authentifizierungsfluss auf Registerkarten.

Der Authentifizierungsfluss in Registerkarten unterscheidet sich vom Authentifizierungsflow in Bots.

Hinweis

Dieses Thema enthält Version 2.0.x der Microsoft Teams JavaScript-Clientbibliothek (TeamsJS). Wenn Sie eine frühere Version verwenden, finden Sie in der Übersicht über die TeamsJS-Bibliothek Anleitungen zu den Unterschieden zwischen den neuesten Versionen von TeamsJS und früheren Versionen.

Konfigurieren Ihrer App für die Verwendung Microsoft Entra ID als Identitätsanbieter

OAuth 2.0, die Identitätsanbieter unterstützen, authentifizieren keine Anforderungen von nicht registrierten Anwendungen. Daher ist es wichtig, Ihre Bewerbungen im Voraus zu registrieren. Führen Sie zum Registrieren einer Anwendung mit Microsoft Entra-ID die folgenden Schritte aus:

  1. Öffnen Sie das Anwendungsregistrierungsportal.

  2. Wählen Sie Ihre App aus, um deren Eigenschaften anzuzeigen, oder wählen Sie die Schaltfläche "Neue Registrierung" aus. Suchen Sie den Abschnitt Umleitungs-URI für die App.

  3. Wählen Sie im Dropdownmenü Web aus, und aktualisieren Sie die URL für Ihren Authentifizierungsendpunkt. In den Auf GitHub verfügbaren TypeScript/Node.js- und C#-Beispiel-Apps folgen die Umleitungs-URLs einem ähnlichen Muster:

    Umleitungs-URLs: https://<hostname>/bot-auth/simple-start

Ersetzen Sie durch <hostname> Ihren tatsächlichen Host. Dieser Host kann eine dedizierte Hostingwebsite wie Azure, Glitch oder ein ngrok-Tunnel zu localhost auf Ihrem Entwicklungscomputer sein, z abcd1234.ngrok.io. B. . Wenn Sie nicht über diese Informationen verfügen, stellen Sie sicher, dass Sie Ihre App (oder die Beispiel-App) abgeschlossen oder gehostet haben. Setzen Sie diesen Prozess fort, wenn Sie über diese Informationen verfügen.

Hinweis

Sie können einen beliebigen OAuth-Drittanbieter wie LinkedIn, Google und andere auswählen. Der Prozess zum Aktivieren der Authentifizierung für diese Anbieter ähnelt der Verwendung Microsoft Entra ID als OAuth-Drittanbieter. Weitere Informationen zur Verwendung eines OAuth-Drittanbieters finden Sie auf der Website des jeweiligen Anbieters.

Initiieren des Authentifizierungsflows

Hinweis

Wenn die experimentelle Speicherpartitionierung von Drittanbietern aktiviert ist, schlägt die Drittanbieterauthentifizierung fehl. Die App fordert wiederholt zur Authentifizierung auf, da die Werte nicht lokal gespeichert werden.

Lösen Sie den Authentifizierungsflow durch eine Benutzeraktion aus. Vermeiden Sie das automatische Öffnen des Authentifizierungs-Popupfensters, da dies wahrscheinlich den Popupblocker des Browsers auslöst und den Benutzer verwirren wird.

Fügen Sie Ihrer Konfigurations- oder Inhaltsseite eine Schaltfläche hinzu, damit sich der Benutzer bei Bedarf anmelden kann. Dies kann auf der Registerkartenkonfigurationsseite oder auf einer beliebigen Inhaltsseite erfolgen.

Microsoft Entra-ID lässt wie die meisten Identitätsanbieter nicht zu, dass der Inhalt in einem iframeplatziert wird. Dies bedeutet, dass Sie eine Popupseite hinzufügen müssen, um den Identitätsanbieter zu hosten. Im folgenden Beispiel ist /tab-auth/simple-startdiese Seite . Verwenden Sie die authentication.authenticate() Funktion der TeamsJS-Bibliothek, um diese Seite zu starten, wenn die Schaltfläche ausgewählt ist.

import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
    url: window.location.origin + "/tab/simple-start-v2",
    width: 600,
    height: 535})
.then((result) => {
    console.log("Login succeeded: " + result);
    let data = localStorage.getItem(result);
    localStorage.removeItem(result);
    let tokenResult = JSON.parse(data);
    showIdTokenAndClaims(tokenResult.idToken);
    getUserProfile(tokenResult.accessToken);
})
.catch((reason) => {
    console.log("Login failed: " + reason);
    handleAuthError(reason);
});

Anmerkungen

  • Die URL, an die Sie übergeben, authenticate() ist die Startseite des Authentifizierungsflusses. In diesem Beispiel ist dies /tab-auth/simple-start. Dies sollte mit dem übereinstimmen, was Sie im Microsoft Entra Anwendungsregistrierungsportal registriert haben.

  • Der Authentifizierungsfluss muss auf einer Seite beginnen, die sich in Ihrer Domäne befindet. Diese Domäne sollte auch im validDomains Abschnitt des Manifests aufgeführt werden. Wenn dies nicht der Vorgang ist, wird ein leeres Popupfenster angezeigt.

  • Wenn Sie nicht verwenden authenticate()können, wird das Popupfenster am Ende des Anmeldevorgangs möglicherweise nicht geschlossen, was zu einem Problem führt.

Navigieren Sie von Ihrer Popupseite zur Autorisierungsseite.

Wenn Ihre Popupseite (/tab-auth/simple-start) angezeigt wird, wird der folgende Code ausgeführt. Das Standard Ziel der Seite besteht darin, zu Ihrem Identitätsanbieter umzuleiten, damit sich der Benutzer anmelden kann. Diese Umleitung kann serverseitig mithilfe von HTTP 302 erfolgen. In diesem Fall erfolgt dies jedoch auf der Clientseite mithilfe eines Aufrufs von window.location.assign(). Dies ermöglicht app.getContext() auch das Abrufen von Hinweisinformationen, die an Microsoft Entra ID übergeben werden können.

app.getContext().then((context) => {
    // Generate random state string and store it, so we can verify it in the callback
    let state = _guid(); // _guid() is a helper function in the sample
    localStorage.setItem("simple.state", state);
    localStorage.removeItem("simple.error");

    // Go to the Azure AD authorization endpoint
    let queryParams = {
        client_id: "{{appId}}",
        response_type: "id_token token",
        response_mode: "fragment",
        scope: "https://graph.microsoft.com/User.Read openid",
        redirect_uri: window.location.origin + "/tab/simple-end",
        nonce: _guid(),
        state: state,
        // The context object is populated by Teams; the loginHint attribute
        // is used as hinting information
        login_hint: context.user.loginHint,
    };

    let authorizeEndpoint = `https://login.microsoftonline.com/${context.user.tenant.id}/oauth2/v2.0/authorize?${toQueryString(queryParams)}`;
    window.location.assign(authorizeEndpoint);
});

Nachdem der Benutzer die Autorisierung abgeschlossen hat, wird er auf die Rückrufseite umgeleitet, die Sie für Ihre App unter angegeben haben /tab-auth/simple-end.

Anmerkungen

  • Informationen zum Erstellen von Authentifizierungsanforderungen und URLs finden Sie unter Abrufen von Benutzerkontextinformationen . Beispielsweise können Sie den Anmeldenamen des Benutzers als login_hint Wert für Microsoft Entra Anmeldung verwenden, was bedeutet, dass der Benutzer möglicherweise weniger eingeben muss. Denken Sie daran, dass Sie diesen Kontext nicht direkt als Identitätsnachweis verwenden sollten, da ein Angreifer Ihre Seite in einem schädlichen Browser laden und ihr beliebige Informationen bereitstellen kann.
  • Obwohl der Registerkartenkontext nützliche Informationen zum Benutzer bereitstellt, verwenden Sie diese Informationen nicht, um den Benutzer zu authentifizieren, unabhängig davon, ob Sie sie als URL-Parameter für Ihre Registerkarteninhalts-URL oder durch Aufrufen der app.getContext() Funktion in der Microsoft Teams JavaScript-Clientbibliothek (TeamsJS) erhalten. Ein böswilliger Akteur könnte ihre Registerkarteninhalts-URL mit eigenen Parametern aufrufen, und eine Webseite, die die Identität von Microsoft Teams angibt, könnte Ihre Registerkarteninhalts-URL in einen iframe laden und ihre eigenen Daten an die getContext() Funktion zurückgeben. Sie sollten die identitätsbezogenen Informationen im Registerkartenkontext einfach als Hinweise behandeln und vor der Verwendung überprüfen.
  • Der state Parameter wird verwendet, um zu bestätigen, dass der Dienst, der den Rückruf-URI aufruft, der Dienst ist, den Sie aufgerufen haben. Wenn der state Parameter im Rückruf nicht mit dem Parameter übereinstimmt, den Sie während des Aufrufs gesendet haben, wird der Rückgabeaufruf nicht überprüft und sollte beendet werden.
  • Es ist nicht erforderlich, die Domäne des Identitätsanbieters in die Liste in die validDomains Datei manifest.json der App aufzunehmen.

Die Rückrufseite

Im letzten Abschnitt haben Sie den Microsoft Entra-Autorisierungsdienst aufgerufen und Benutzer- und App-Informationen übergeben, sodass Microsoft Entra ID dem Benutzer eine eigene monolithische Autorisierungsoberfläche bieten kann. Ihre App hat keine Kontrolle darüber, was in dieser Benutzeroberfläche geschieht. Es weiß nur, was zurückgegeben wird, wenn Microsoft Entra ID die von Ihnen bereitgestellte Rückrufseite aufruft (/tab-auth/simple-end).

Auf dieser Seite müssen Sie den Erfolg oder Fehler basierend auf den Informationen ermitteln, die von Microsoft Entra ID zurückgegeben werden und oder authentication.notifyFailure()aufrufenauthentication.notifySuccess(). Wenn die Anmeldung erfolgreich war, haben Sie Zugriff auf Dienstressourcen.

// Split the key-value pairs passed from Azure AD
// getHashParameters is a helper function that parses the arguments sent
// to the callback URL by Azure AD after the authorization call
let hashParams = getHashParameters();
if (hashParams["error"]) {
    // Authentication/authorization failed
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
} else if (hashParams["access_token"]) {
    // Get the stored state parameter and compare with incoming state
    let expectedState = localStorage.getItem("simple.state");
    if (expectedState !== hashParams["state"]) {
        // State does not match, report error
        localStorage.setItem("simple.error", JSON.stringify(hashParams));
        authentication.notifyFailure("StateDoesNotMatch");
    } else {
        // Success -- return token information to the parent page.
        // Use localStorage to avoid passing the token via notifySuccess; instead we send the item key.
        let key = "simple.result";
        localStorage.setItem(key, JSON.stringify({
            idToken: hashParams["id_token"],
            accessToken: hashParams["access_token"],
            tokenType: hashParams["token_type"],
            expiresIn: hashParams["expires_in"]
        }));
        authentication.notifySuccess(key);
    }
} else {
    // Unexpected condition: hash does not contain error or access_token parameter
    localStorage.setItem("simple.error", JSON.stringify(hashParams));
    authentication.notifyFailure("UnexpectedFailure");
}

Dieser Code analysiert die Schlüssel-Wert-Paare, die von Microsoft Entra-ID in window.location.hash empfangen werden, mithilfe der getHashParameters() Hilfsfunktion. Wenn ein gefunden access_tokenwird und der state Wert mit dem wert übereinstimmt, der zu Beginn des Authentifizierungsflusses angegeben wurde, wird das Zugriffstoken durch Aufrufen notifySuccess()von an die Registerkarte zurückgegeben. Andernfalls wird ein Fehler mit notifyFailure()gemeldet.

Anmerkungen

NotifyFailure() weist die folgenden vordefinierten Fehlerursachen auf:

  • CancelledByUser Der Benutzer hat das Popupfenster geschlossen, bevor er den Authentifizierungsflow abgeschlossen hat.

    Hinweis

    Es wird empfohlen, keine - oder same-origin-allow-popups -Werte für Cross-Origin-Opener-Policy den Antwortheader auf den Anmeldeseiten zu verwendensame-origin, da dadurch die Verbindung mit dem übergeordneten Fenster unterbrochen wird und der Authentifizierungs-API-Aufruf vorzeitig mit einem CancelledByUser Fehler zurückgegeben wird.

  • FailedToOpenWindow das Popupfenster konnte nicht geöffnet werden. Wenn Microsoft Teams in einem Browser ausgeführt wird, bedeutet dies in der Regel, dass das Fenster durch einen Popupblocker blockiert wurde.

Bei erfolgreicher Ausführung können Sie die Seite aktualisieren oder neu laden und inhalte anzeigen, die für den jetzt authentifizierten Benutzer relevant sind. Wenn die Authentifizierung fehlschlägt, wird eine Fehlermeldung angezeigt.

Ihre App kann ein eigenes Sitzungscookies festlegen, sodass sich der Benutzer nicht erneut anmelden muss, wenn er zu Ihrer Registerkarte auf dem aktuellen Gerät zurückkehrt.

Hinweis

  • Chrome 80, das Anfang 2020 veröffentlicht werden soll, führt neue Cookiewerte ein und erzwingt standardmäßig Cookierichtlinien. Es wird empfohlen, die beabsichtigte Verwendung für Ihre Cookies festzulegen, anstatt sich auf das Standardverhalten des Browsers zu verlassen. Weitere Informationen finden Sie unterSameSite-Cookie-Attribut (Update 2020).
  • Um das entsprechende Token für Microsoft Teams Free- und Gastbenutzer zu erhalten, stellen Sie sicher, dass Ihre Apps den mandantenspezifischen Endpunkt https://login.microsoftonline.com/**{tenantId}**verwenden. Sie können die tenantId aus der Botnachricht oder dem Registerkartenkontext abrufen. Wenn Ihre Apps verwenden https://login.microsoftonline.com/common, erhalten Benutzer möglicherweise falsche Token, sodass sie sich beim "Home"-Mandanten anmelden und nicht beim Mandanten, bei dem sie derzeit angemeldet sind.

Weitere Informationen zum einmaligen Anmelden (Single Sign-On, SSO) finden Sie im Artikel Automatische Authentifizierung.

Codebeispiel

Beispielcode, der den Tab-Authentifizierungsprozess mit Microsoft Entra-ID zeigt:

Beispielname Beschreibung .NET Node.js Manifest
Registerkarten-SSO Diese Beispiel-App zeigt Microsoft Entra SSO für Registerkarten in Teams. Anzeigen Ansicht,
Teams Toolkit		 –
Registerkarten-, Bot- und Nachrichtenerweiterungs-SSO (ME) Dieses Beispiel zeigt SSO für Tab-, Bot- und ME-Suche, Aktion, Link unfurl. View View Anzeigen

Siehe auch