Verwenden externer OAuth-Anbieter

  • Artikel

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.

Mithilfe der aktualisierten authenticate() API können Sie externe oder Drittanbieter (3P) OAuth-Anbieter wie Google, GitHub, LinkedIn und Facebook unterstützen:

function authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>

Folgendes wird der authenticate() API hinzugefügt, um externe OAuth-Anbieter zu unterstützen:

  • isExternal Parameter
  • Zwei Platzhalterwerte im vorhandenen url Parameter

Die folgende Tabelle enthält eine Liste der authenticate() API-Parameter (AuthenticatePopUpParameters) und -Funktionen sowie deren Beschreibungen:

Parameter Beschreibung
isExternal Der Parametertyp ist Boolean, was angibt, dass das Authentifizierungsfenster in einem externen Browser geöffnet wird.
height Die bevorzugte Höhe für das Pop-up. Der Wert kann ignoriert werden, wenn er außerhalb der akzeptablen Grenzen liegt.
url
Die URL des 3P-App-Servers für das Authentifizierungs-Popup mit den folgenden zwei Parameterplatzhaltern:

- oauthRedirectMethod: Übergeben des Platzhalters in {}. Dieser Platzhalter wird von der Teams-Plattform durch einen Deeplink oder eine Webseite ersetzt, die den App-Server informiert, wenn der Anruf von einer mobilen Plattform kommt.

- authId: Dieser Platzhalter wird durch UUID ersetzt. Der App-Server verwendet es, um die Sitzung aufrechtzuerhalten.
width Die bevorzugte Breite für das Pop-up. Der Wert kann ignoriert werden, wenn er außerhalb der akzeptablen Grenzen liegt.

Weitere Informationen zu Parametern finden Sie unter authenticate(AuthenticatePopUpParameters) -Funktion.

Authentifizierung zu externen Browsern hinzufügen

Hinweis

  • Derzeit können Sie die Authentifizierung zu externen Browsern nur für Registerkarten auf Mobilgeräten hinzufügen.
  • Verwenden Sie die Betaversion von TeamsJS, um die Funktionalität zu nutzen. Betaversionen sind über NPM verfügbar.

Das folgende Bild zeigt den Ablauf zum Hinzufügen der Authentifizierung zu externen Browsern:

authenticate-OAuth

So fügen Sie die Authentifizierung zu externen Browsern hinzu

  1. Initiieren Sie den externen Authentifizierungs- und Anmeldeprozess.

    Die 3P-App ruft die TeamsJS-Funktion authentication.authenticate auf, die isExternal auf true festgelegt ist, um den externen Authentifizierungs-Anmeldeprozess zu initiieren.

    Die übergebene url enthält Platzhalter für {authId} und {oauthRedirectMethod}.

    import { authentication } from "@microsoft/teams-js";
authentication.authenticate({
   url: 'https://3p.app.server/auth?oauthRedirectMethod={oauthRedirectMethod}&authId={authId}',
   isExternal: true,
   successCallback: function (result) {
   //sucess 
   } failureCallback: function (reason) {
   //failure 
    }
});

  2. Der Teams-Link öffnet sich in einem externen Browser.

    Die Teams Clients öffnen die URL in einem externen Browser, nachdem sie die Platzhalter für oauthRedirectMethod und authId durch geeignete Werte ersetzt haben.

    Beispiel

     https://3p.app.server/auth?oauthRedirectMethod=deeplink&authId=1234567890

  3. Der 3P-App-Server antwortet.

    Der 3P-App-Server empfängt und speichert die url mit den folgenden beiden Abfrageparametern:

    Parameter Beschreibung
    oauthRedirectMethod Gibt an, wie die 3P-App die Antwort der Authentifizierungsanforderung zurück an Teams senden muss, mit einem der beiden Werte: Deeplink oder Seite.
    authId Die Anforderungs-ID, die Teams für diese spezifische Authentifizierungsanforderung erstellt haben und die über Deeplink an Teams zurückgesendet werden muss.

    Tipp

    Die 3P-App kann authId, oauthRedirectMethod im OAuth state Abfrageparameter marshallen, während sie die Anmelde-URL für den OAuthProvider generiert. Die state enthält die übergebenen authId und oauthRedirectMethod, wenn OAuthProvider zurück an den 3P-Server umleitet und die 3P-App die Werte zum Senden der Authentifizierungsantwort an Teams verwendet, wie in beschrieben 6. Die Antwort des 3P-App-Servers auf Teams.

  4. Der 3P-App-Server leitet zur angegeben url weiter.

    Der 3P-App-Server leitet zur Authentifizierungsseite des OAuth-Anbieters im externen Browser um. Die redirect_uri ist eine dedizierte Route auf dem 3P-App-Server. Sie können redirect_uri in der Entwicklungskonsole des OAuth-Anbieters als statisch registrieren, die Parameter müssen über das Zustandsobjekt gesendet werden.

    Beispiel

    https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https://3p.app.server/authredirect&state={"authId":"…","oauthRedirectMethod":"…"}&client_id=…    &response_type=code&access_type=offline&scope= …

  5. Melden Sie sich beim externen Browser an.

    Der Benutzer meldet sich beim externen Browser an. Die OAuth-Anbieter leiten zurück zur redirect_uri mit dem Authentifizierungscode und dem Zustandsobjekt.

  6. Der 3P-App-Server überprüft Teams und antwortet darauf.

    Der 3P-App-Server verarbeitet die Antwort und prüft oauthRedirectMethod, die vom externen OAuth-Anbieter im Zustandsobjekt zurückgegeben wird, um zu bestimmen, ob die Antwort über den auth-callback-Deeplink oder über die Webseite, die notifySuccess() aufruft, zurückgegeben werden muss.

    const state = JSON.parse(req.query.state)
if (state.oauthRedirectMethod === 'deeplink') {
   return res.redirect('msteams://teams.microsoft.com/l/auth-callback?authId=${state.authId}&result=${req.query.code}')
}
else {
// continue redirecting to a web-page that will call notifySuccess() – usually this method is used in Teams-Web
…

  7. Die 3P-App generiert einen Deeplink.

    Die 3P-App generiert einen Deeplink für Teams Mobile im folgenden Format und sendet den Authentifizierungscode mit der Sitzungs-ID zurück an Teams.

    return res.redirect(`msteams://teams.microsoft.com/l/auth-callback?authId=${state.authId}&result=${req.query.code}`)

  8. Teams ruft einen Erfolgsrückruf auf und sendet das Ergebnis.

    Teams ruft den Erfolgsrückruf auf und sendet das Ergebnis (Authentifizierungscode) an die 3P-App. Die 3P-App empfängt den Code im Erfolgsrückruf und verwendet den Code, um das Token und dann die Benutzerinformationen abzurufen und die Benutzeroberfläche zu aktualisieren.

    successCallback: function (result) { 
… 
}

Siehe auch