Hinzufügen der Drittanbieterauthentifizierung zu Ihrer Nachrichtenerweiterung

  • Artikel

Wichtig

Die Codebeispiele in diesem Abschnitt basieren auf Version 4.6 und höheren Versionen des Bot Framework SDK. Wenn Sie nach Dokumentation zu früheren Versionen suchen, lesen Sie den Abschnitt Nachrichtenerweiterungen – v3 SDK im Ordner Ressourcen der Dokumentation.

Hinweis

Nachdem Sie die Authentifizierung zur Nachrichtenerweiterung hinzugefügt haben, müssen Sie dem Abschnitt "validDomains" im Manifest "token.botframework.com" hinzufügen.

Identifizieren des Benutzers

Jede Anforderung an Ihre Dienste umfasst die Benutzer-ID, den Anzeigenamen des Benutzers und Microsoft Entra Objekt-ID.

"from": {
  "id": "29:1C7dbRrC_5yzN1RGtZIrcWT0xz88KPGP9sxdpVpV8sODlgPHeQE9RqQ02hnpuKzy6zZ-AaZx6swUOMj_Dsdse3TQ4sIaeebbFBF-VgjJy_nY",
  "name": "Larry Jin",
  "aadObjectId": "cd723fa0-0591-416a-9290-e93ecf3a9b92"
},

Die Werte id und aadObjectId werden für den authentifizierten Teams-Benutzer garantiert. Sie werden als Schlüssel verwendet, um die Anmeldeinformationen oder einen zwischengespeicherten Status in Ihrem Dienst nachzuschlagen. Darüber hinaus enthält jede Anforderung die Microsoft Entra Mandanten-ID, die verwendet wird, um die organization des Benutzers zu identifizieren. Falls zutreffend, enthält die Anforderung auch die Team-ID und die Kanal-ID, von der die Anforderung stammt.

Authentifizierung

Wenn Ihr Dienst eine Benutzerauthentifizierung erfordert, müssen sich die Benutzer anmelden, bevor sie die Nachrichtenerweiterung verwenden. Die Authentifizierungsschritte ähneln denen eines Bots oder einer Registerkarte. Die Sequenz sieht wie folgt aus:

  1. Der Benutzer stellt eine Abfrage, oder die Standardabfrage wird automatisch an Ihren Dienst gesendet.
  2. Ihr Dienst überprüft, ob der Benutzer authentifiziert ist, indem er die Teams-Benutzer-ID untersucht.
  3. Wenn der Benutzer nicht authentifiziert ist, senden Sie eine auth-Antwort mit einer vorgeschlagenen openUrl- Aktion zurück, einschließlich der Authentifizierungs-URL.
  4. Der Microsoft Teams-Client startet ein Dialogfeld, in dem Ihre Webseite mithilfe der angegebenen Authentifizierungs-URL gehostet wird.
  5. Nachdem sich der Benutzer angemeldet hat, sollten Sie Ihr Fenster schließen und einen Authentifizierungscode an den Teams-Client senden.
  6. Der Teams-Client stellt dann die Abfrage an Ihren Dienst erneut, einschließlich des in Schritt 5 übergebenen Authentifizierungscodes.

Ihr Dienst sollte überprüfen, ob der in Schritt 6 empfangene Authentifizierungscode mit Schritt 5 übereinstimmt. Die Schritte stellen sicher, dass ein böswilliger Benutzer nicht versucht, den Anmeldeflow zu spoofen oder zu kompromittieren. Der Flow "schließt die Schleife", um die sichere Authentifizierungssequenz abzuschließen.

Antworten mit einer Anmeldeaktion

Um einen nicht authentifizierten Benutzer zur Anmeldung aufzufordern, antworten Sie mit einer vorgeschlagenen Aktion vom Typ openUrl , die die Authentifizierungs-URL enthält.

Antwortbeispiel für eine Anmeldeaktion

{
  "composeExtension":{
    "type":"auth",
    "suggestedActions":{
      "actions":[
        {
          "type": "openUrl",
          "value": "https://example.com/auth",
          "title": "Sign in to this app"
        }
      ]
    }
  }
}

Hinweis

  • Damit die Anmeldeerfahrung in einem Teams-Popupfenster gehostet werden kann, muss sich der Domänenteil der URL in der Liste der gültigen Domänen Ihrer App befinden. Weitere Informationen finden Sie unter validDomains im Manifestschema.
  • Die Größe des Authentifizierungs-Popupfensters kann durch Einschließen von Abfragezeichenfolgenparametern der Breite und Höhe Value = $"{_siteUrl}/searchSettings.html?height=600&width=600" definiert werden.

Starten des Anmeldeflusses

Ihre Anmeldeerfahrung muss reaktionsfähig sein und in ein Popupfenster passen. Es sollte in die JavaScript-Clientbibliothek von Microsoft Teams integriert werden, die nachrichtenübergaben verwendet.

Wie bei anderen eingebetteten Erfahrungen, die innerhalb von Microsoft Teams ausgeführt werden, muss Ihr Code im Fenster zuerst app.initialize() aufrufen. Wenn Ihr Code einen OAuth-Fluss ausführt, können Sie die Teams-Benutzer-ID an Ihr Fenster übergeben, das sie dann an die OAuth-Anmelde-URL übergibt.

Abschließen des Anmeldeflusses

Wenn die Anmeldeanforderung abgeschlossen ist und zurück zu Ihrer Seite leitet, müssen die folgenden Schritte ausgeführt werden:

  1. Generieren Sie einen Sicherheitscode, eine Zufallszahl. Sie müssen diesen Code in Ihrem Dienst mit den Anmeldeinformationen zwischenspeichern, die über den Anmeldeflow abgerufen werden, z. B. OAuth 2.0-Token.
  2. Rufen Sie authentication.notifySuccess auf, und übergeben Sie den Sicherheitscode.

An diesem Punkt wird das Fenster geschlossen, und die Kontrolle wird an den Teams-Client übergeben. Der Client stellt nun die ursprüngliche Benutzerabfrage zusammen mit dem Sicherheitscode in der Eigenschaft state erneut aus. Ihr Code kann den Sicherheitscode verwenden, um die zuvor gespeicherten Anmeldeinformationen nachzuschlagen, um die Authentifizierungssequenz abzuschließen und dann die Benutzeranforderung abzuschließen.

Beispiel für neu ausgestellte Anforderung

{
    "name": "composeExtension/query",
    "value": {
        "commandId": "insertWiki",
        "parameters": [{
            "name": "searchKeyword",
            "value": "lakers"
        }],
        "state": "12345",
        "queryOptions": {
            "skip": 0,
            "count": 25
        }
    },
    "type": "invoke",
    "timestamp": "2017-04-26T05:18:25.629Z",
    "localTimestamp": "2017-04-25T22:18:25.629-07:00",
    "entities": [{
        "locale": "en-US",
        "country": "US",
        "platform": "Web",
        "type": "clientInfo"
    }],
    "text": "",
    "attachments": [],
    "address": {
        "id": "f:7638210432489287768",
        "channelId": "msteams",
        "user": {
            "id": "29:1A5TJWHkbOwSyu_L9Ktk9QFI1d_kBOEPeNEeO1INscpKHzHTvWfiau5AX_6y3SuiOby-r73dzHJ17HipUWqGPgw",
            "aadObjectId": "fc8ca1c0-d043-4af6-b09f-141536207403"
        },
        "conversation": {
            "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
        },
        "bot": {
            "id": "28:c073afa8-7e77-4f92-b3e7-aa589e952a3e",
            "name": "maotestbot2"
        },
        "serviceUrl": "https://smba.trafficmanager.net/amer-client-ss.msg/",
        "useAuth": true
    },
    "source": "msteams"
}

Codebeispiel

Beispielname Beschreibung .NET Node.js Manifest
Nachrichtenerweiterungen – Authentifizierung und Konfiguration Eine Nachrichtenerweiterung, die über eine Konfigurationsseite verfügt, Suchanforderungen akzeptiert und Ergebnisse zurückgibt, nachdem sich der Benutzer angemeldet hat. View View Anzeigen

Siehe auch

Aktivieren des einmaligen Anmeldens für Ihren Bot und Ihre Nachrichtenerweiterungs-App