Freigeben über

Authentifizierung für Ihren Teams-Bot hinzufügen

  • Artikel

Sie können Bots in Microsoft Teams erstellen, die im Namen des Benutzers auf Ressourcen zugreifen, z. B. einen E-Mail-Dienst. Sie können die Azure Bot Service v4 SDK-Authentifizierung basierend auf OAuth 2.0 verwenden. Diese Methode erleichtert die Entwicklung eines Bots, der Authentifizierungstoken basierend auf den Anmeldeinformationen des Benutzers verwenden kann. Der Schlüssel ist die Verwendung von Identitätsanbietern.

OAuth 2.0 ist ein offener Standard für die Authentifizierung und Autorisierung, die von Microsoft Entra ID und vielen anderen Identitätsanbietern verwendet wird. Ein grundlegendes Verständnis von OAuth 2.0 ist eine Voraussetzung für die Arbeit mit der Authentifizierung in Teams.

Siehe OAuth 2 Simplified für grundlegende Informationen und OAuth 2.0 für die vollständige Spezifikation.

Weitere Informationen dazu, wie der Azure Bot Service die Authentifizierung verarbeitet, finden Sie unter Benutzerauthentifizierung in einer Unterhaltung.

In diesem Artikel erhalten Sie Informationen zu folgenden Themen:

  • So erstellen Sie einen Bot mit Authentifizierungsfunktion. Verwenden Sie cs-auth-sample , um Anmeldeinformationen für Benutzer und das Generieren des Authentifizierungstokens zu verarbeiten.
  • So stellen Sie den Bot in Azure bereit und ordnen ihn einem Identitätsanbieter zu. Der Anbieter gibt ein Token basierend auf Anmeldeinformationen des Benutzers aus. Der Bot kann das Token für den Zugriff auf Ressourcen verwenden, z. B. einen E-Mail-Dienst, der eine Authentifizierung erfordert. Weitere Informationen finden Sie unter Microsoft Teams-Authentifizierungsflow für Bots.
  • So integrieren Sie den Bot in Microsoft Teams. Sobald der Bot integriert ist, können Sie sich anmelden und Nachrichten mit diesem in einem Chat austauschen.

Voraussetzungen

Erstellen der Ressourcengruppe

Die Ressourcengruppe und der Serviceplan sind nicht unbedingt erforderlich, aber sie ermöglichen es Ihnen, die von Ihnen erstellten Ressourcen bequem freizugeben. Es wird empfohlen, dass Sie Ihre Ressourcen organisiert und verwaltbar halten.

Sie verwenden eine Ressourcengruppe, um einzelne Ressourcen für das Bot-Framework zu erstellen. Stellen Sie aus Leistungsgründen sicher, dass sich diese Ressourcen in derselben Azure-Region befinden.

  1. Melden Sie sich in Ihrem Browser beim Microsoft Azure-Portal an.
  2. Wählen Sie im linken Navigationsbereich Ressourcengruppen aus.
  3. Wählen Sie oben links im angezeigten Fenster die Registerkarte Hinzufügen aus, um eine neue Ressourcengruppe zu erstellen. Geben Sie die folgenden Details an:
    1. Abonnement: Verwenden Sie Ihr vorhandenes Abonnement.
    2. Ressourcengruppe. Geben Sie den Namen für die Ressourcengruppe ein. Ein Beispiel wäre TeamsResourceGroup. Denken Sie daran, dass der Name eindeutig sein muss.
    3. Wählen Sie im Dropdownmenü Region die Option USA, Westen oder eine Region in der Nähe Ihrer Anwendungen aus.
    4. Wählen Sie die Schaltfläche Überprüfen und erstellen aus. Es sollte ein Banner mit der Aufschrift Prüfung bestanden angezeigt werden.
    5. Wählen Sie die Schaltfläche Erstellen aus. Das Erstellen der Ressourcengruppe kann einige Minuten dauern.

Tipp

Wie bei den Ressourcen, die Sie später in diesem Tutorial erstellen, empfiehlt es sich, diese Ressourcengruppe für den einfachen Zugriff an Ihr Dashboard anzuheften. Wenn Sie dies tun möchten, wählen Sie das Stecknadelsymbol 📌 oben rechts im Dashboard aus.

Erstellen des Serviceplans

  1. Wählen Sie im linken Navigationsbereich im Azure-Portal die Option Ressource erstellen aus.
  2. Geben Sie im Suchfeld App-Serviceplan ein. Wählen Sie in den Suchergebnissen die Karte App-Serviceplan aus.
  3. Wählen Sie Erstellen aus.
  4. Geben Sie die folgenden Informationen an:
    1. Abonnement: Sie können ein vorhandenes Abonnement verwenden.
    2. Ressourcengruppe. Wählen Sie die Gruppe aus, die Sie zuvor erstellt haben.
    3. Name. Geben Sie den Namen für den Serviceplan ein. Ein Beispiel wäre TeamsServicePlan. Denken Sie daran, dass der Name innerhalb der Gruppe eindeutig sein muss.
    4. Betriebssystem. Wählen Sie Windows oder Ihr entsprechendes Betriebssystem aus.
    5. Region. Wählen Sie USA, Westen oder eine Region in der Nähe Ihrer Anwendungen aus.
    6. Preisstufe. Wählen Sie Standard S1 aus, was der Standardwert ist.
    7. Wählen Sie die Schaltfläche Überprüfen und erstellen aus. Es sollte ein Banner mit der Aufschrift Prüfung bestanden angezeigt werden.
    8. Wählen Sie Erstellen aus. Die Erstellung des App Service-Plans kann einige Minuten dauern. Der Plan ist in der Ressourcengruppe aufgeführt.

Erstellen der Azure Bot-Ressourcenregistrierung

Die Azure Bot-Ressourcenregistrierung registriert Ihren Webdienst als Bot beim Bot Framework, das Ihnen eine Microsoft App-ID und ein App-Kennwort (geheimer Clientschlüssel) bereitstellt.

Wichtig

Sie müssen Ihren Bot nur registrieren, wenn er nicht in Azure gehostet wird. Wenn Sie einen Bot über das Azure-Portal erstellt haben, ist er bereits beim Dienst registriert. Wenn Sie Ihren Bot über das Bot-Framework oder das Entwicklerportal erstellt haben, ist Ihr Bot nicht in Azure registriert.

  1. Besuchen Sie Azure-Portal und suchen Sie im Abschnitt Erstellen einer Ressource nach Azure Bot.

  2. Öffnen Sie den Azure Bot, und wählen Sie Erstellen aus.

  3. Geben Sie den Namen des Bot-Handle in das Feld Bot-Handle ein.

  4. Wählen Sie Ihr Abonnement aus der Dropdownliste aus.

  5. Wählen Sie Ihre Ressourcengruppe aus der Dropdownliste aus.

  6. Wählen Sie den App-Typ als Mehrinstanzenfähig für die Microsoft-App-ID aus.

    Screenshot: Auswählen von mehrinstanzenfähigem Mandanten für Microsoft AppID

  7. Wählen Sie Überprüfen + erstellen aus.

    Screenshot: Erstellen eines Azure-Bots

  8. Wenn die Prüfung bestanden wurde, wählen Sie Erstellen aus.

    Azure stellt Ihren Bot in wenigen Augenblicken zur Bereitstellung.

    Screenshot: Erfolgreiche Überprüfung des Azure-Bots

  9. Wählen Sie Zu Ressource wechseln aus. Der Bot und die zugehörigen Ressourcen werden in der Ressourcengruppe aufgeführt.

    Screenshot: Auswählen einer Ressourcengruppe

    Ihr Azure-Bot wird erstellt.

    Screenshot: Erstellen von Azure-Botressourcen

So erstellen Sie den geheimen Clientschlüssel:

  1. Wählen Sie in Einstellungen die Option Konfiguration aus. Speichern Sie die Microsoft App-ID (Client-ID) zur zukünftigen Referenz.

    Screenshot: Hinzufügen der Microsoft-App-ID zum Erstellen eines geheimen Clientschlüssels

  2. Wählen Sie neben Microsoft App ID die Option Verwalten aus.

    Screenshot: Erstellen und Verwalten eines Bots

  3. Wählen Sie im Abschnitt Geheime Clientschlüssel die Option Neuer geheimer Clientschlüssel aus. Das Fenster Geheimen Clientschlüssel hinzufügen wird angezeigt.

    Screenshot: Erstellen eines neuen geheimen Clientschlüssels

  4. Geben Sie Beschreibung ein, und wählen Sie Hinzufügen aus.

    Der Screenshot zeigt, wie Eine Beschreibung für den geheimen Clientschlüssel eingegeben wird.

  5. Wählen Sie in der Spalte WertIn Zwischenablage kopieren aus, und speichern Sie die Clientgeheimnis-ID zur späteren Referenz.

    Der Screenshot zeigt, wie Sie die geheime Clientschlüssel-ID zur späteren Referenz speichern.

So fügen Sie den Microsoft Teams-Kanal hinzu:

  1. Wechseln Sie zu Startseite.

    Screenshot: Bot-Startseite

  2. Öffnen Sie Ihren Bot im Abschnitt Zuletzt verwendete Ressourcen .

  3. Wählen Sie im linken Bereich Kanäle und dann Microsoft Teams aus .

    Screenshot: Auswählen von Teams in Kanälen

  4. Aktivieren Sie das Kontrollkästchen, um die Nutzungsbedingungen zu akzeptieren, und wählen Sie Zustimmen aus.

    Screenshot: Festlegen der Bedingungen für

  5. Klicken Sie auf Speichern.

    Screenshot: Hinzufügen eines Microsoft Teams-Kanals

Weitere Informationen finden Sie unter Erstellen eines Bot für Microsoft Teams.

Erstellen des Identitätsanbieters

Sie benötigen einen Identitätsanbieter für die Authentifizierung. In diesem Verfahren verwenden Sie einen Microsoft Entra-Anbieter. Alternativ können Sie auch andere von Microsoft Entra ID unterstützte Identitätsanbieter verwenden.

  1. Wählen Sie im Azure-Portal im linken Navigationsbereich Microsoft Entra ID aus.

    Tipp

    Sie müssen diese Microsoft Entra-Ressource in einem Mandanten erstellen und registrieren, in dem Sie dem Delegieren von Berechtigungen zustimmen können, die von einer Anwendung angefordert werden. Anweisungen zum Erstellen eines Mandanten finden Sie unter Zugreifen auf das Portal und Erstellen eines Mandanten.

  2. Wählen Sie im linken Bereich App-Registrierungenaus.

  3. Wählen Sie im rechten Bereich oben links die Registerkarte Neue Registrierung aus.

  4. Geben Sie die folgenden Informationen an:

    1. Name. Geben Sie den Namen für die Anwendung ein. Ein Beispiel wäre BotTeamsIdentity. Denken Sie daran, dass der Name eindeutig sein muss.
    2. Wählen Sie Unterstützte Kontotypen für Ihre Anwendung aus. Wählen Sie Konten in einem beliebigen Organisationsverzeichnis (Beliebiger Microsoft Entra ID-Mandant – Mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) aus.
    3. Für den Umleitungs-URI:
      ✓Wählen Sie Web aus.
      ✓ Legen Sie die URL auf fest https://token.botframework.com/.auth/web/redirect.
    4. Wählen Sie Registrieren aus.

  5. Nachdem Azure die App erstellt hat, wird die Seite Übersicht für die App angezeigt. Kopieren und speichern Sie die folgenden Informationen in eine Datei:

    1. Der Wert der Anwendungs-ID (Client). Verwenden Sie diesen Wert später als Client-ID , wenn Sie diese Azure-Identitätsanwendung bei Ihrem Bot registrieren.
    2. Der Wert der Verzeichnis-ID (Mandant). Verwenden Sie diesen Wert später als Mandanten-ID , wenn Sie diese Azure-Identitätsanwendung bei Ihrem Bot registrieren.

  6. Wählen Sie im linken Bereich Zertifikate & geheime Schlüssel aus, um einen geheimen Clientschlüssel für Ihre Anwendung zu erstellen.

    1. Wählen Sie unter Geheime Clientschlüsseldie Option Neuer geheimer Clientschlüssel aus ➕.
    2. Fügen Sie eine Beschreibung hinzu, um diesen geheimen Schlüssel von anderen zu identifizieren, die Sie möglicherweise für diese App erstellen müssen, z. B. Bot-Identitäts-App in Teams.
    3. Legen Sie das Ablaufdatum auf das gewünschte Datum fest.
    4. Klicken Sie auf Hinzufügen.
    5. Bevor Sie diese Seite verlassen, den geheimen Schlüssel notieren. Verwenden Sie diesen Wert später als geheimer Clientschlüssel , wenn Sie Ihre Microsoft Entra-Anwendung bei Ihrem Bot registrieren.

Konfigurieren der Identitätsanbieterverbindung und Registrieren beim Bot

Hinweis

Hier gibt es zwei Optionen für Dienstanbieter: Azure Active Directory v1 und Azure Active Directory v2. Die Unterschiede zwischen den beiden Anbietern werden hier zusammengefasst, aber im Allgemeinen bietet v2 mehr Flexibilität in Bezug auf das Ändern von Botberechtigungen. Graph-API-Berechtigungen werden im Feld "Bereiche" aufgeführt, und wenn neue hinzugefügt werden, ermöglichen Bots Benutzern, den neuen Berechtigungen bei der nächsten Anmeldung zuzustimmen. Für v1 muss die Boteinwilligung vom Benutzer gelöscht werden, damit neue Berechtigungen im OAuth-Dialogfeld aufgefordert werden.

Microsoft Azure Active Directory (Azure AD) v1

  1. Wählen Sie im Azure-Portal Ihre Ressourcengruppe aus dem Dashboard aus.

  2. Wählen Sie den Link zur Botregistrierung aus.

  3. Öffnen Sie die Ressourcenseite, und wählen Sie Konfiguration unter Einstellungen aus.

  4. Wählen Sie OAuth-Verbindungseinstellungen hinzufügen aus. In der folgenden Abbildung wird die entsprechende Auswahl auf der Ressourcenseite angezeigt:

    SampleAppDemoBot-Konfiguration

  5. Füllen Sie das Formular wie folgt aus:

    1. Name. Geben Sie einen Namen für die Verbindung ein. Sie verwenden diesen Namen in Ihrem Bot in der appsettings.json Datei. Beispiel: BotTeamsAuthADv1.

    2. Dienstanbieter. Wählen Sie Azure Active Directory aus. Nachdem Sie diese Option ausgewählt haben, werden die Azure Active Directory-spezifischen Felder angezeigt.

    3. Client-ID. Geben Sie die Anwendungs-ID (Client) ein, die Sie für Ihre Azure-Identitätsanbieter-App aufgezeichnet haben.

    4. Geheimer Clientschlüssel. Geben Sie das Geheimnis ein, das Sie für Ihre Azure-Identitätsanbieter-App aufgezeichnet haben.

    5. Gewährungstyp. authorization_code eingeben.

    6. Anmelde-URL. https://login.microsoftonline.com eingeben.

    7. Mandanten-ID: Geben Sie die Directory-ID (Mandant) ein, die Sie zuvor für Ihre Azure-Identitäts-App notiert haben, oder Allgemeines, je nachdem, welchen unterstützten Kontotyp Sie beim Erstellen der Identitätsanbieter-App ausgewählt haben. Um zu entscheiden, welcher Wert zugewiesen werden soll, befolgen Sie die folgenden Kriterien:

      • Wenn Sie entweder Konten nur in diesem Organisationsverzeichnis (nur Microsoft – Einzelner Mandant) oder Konten in einem beliebigen Organisationsverzeichnis (Beliebiger Microsoft Entra ID-Mandant – Mehrinstanzenfähig) ausgewählt haben, geben Sie die Mandanten-ID ein, die Sie zuvor für die Microsoft Entra-App notiert haben. Dies ist der Mandant, der den Benutzern zugeordnet ist, die authentifiziert werden können.

      • Wenn Sie Konten in einem beliebigen Organisationsverzeichnis (Beliebiger Microsoft Entra ID-Mandant – Mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) ausgewählt haben, geben Sie das Wort common anstelle einer Mandanten-ID ein. Andernfalls überprüft die Microsoft Entra-App den Mandanten, dessen ID ausgewählt wurde, und schließt persönliche Microsoft-Konten aus.

    h. Geben Sie für die Ressourcen-URL "https://graph.microsoft.com/" ein. Diese URL wird im Codebeispiel nicht verwendet.
    i. Lassen Sie das Feld Bereiche leer. Die folgende Abbildung dient lediglich als Beispiel:

    Screenshot: Hinzufügen einer Teams-Bot-Authentifizierungsbot-Identitätsverbindung adv1

  6. Klicken Sie auf Speichern.

Microsoft Azure Active Directory (Azure AD) v2

  1. Wählen Sie im Azure-Portal Ihren Azure-Bot aus dem Dashboard aus.

  2. Wählen Sie auf der Ressourcenseite unter EinstellungenKonfiguration aus.

  3. Wählen Sie OAuth-Verbindungseinstellungen hinzufügen aus.
    In der folgenden Abbildung wird die entsprechende Auswahl auf der Ressourcenseite angezeigt:

    Screenshot: Entsprechende Auswahl auf der Ressourcenseite

  4. Füllen Sie das Formular wie folgt aus:

    1. Name. Geben Sie einen Namen für die Verbindung ein. Verwenden Sie diesen Namen in Ihrem Bot in der appsettings.json Datei. Beispiel: BotTeamsAuthADv2.

    2. Dienstanbieter. Wählen Sie Azure Active Directory v2 aus. Nachdem Sie diese Option ausgewählt haben, werden die Azure AD v2-spezifischen Felder angezeigt.

    3. Client-ID. Geben Sie die Anwendungs-ID (Client) ein, die Sie für Ihre Azure-Identitätsanbieter-App aufgezeichnet haben.

    4. Geheimer Clientschlüssel. Geben Sie das Geheimnis ein, das Sie für Ihre Azure-Identitätsanbieter-App aufgezeichnet haben.

    5. Tokenaustausch-URL. Lassen Sie dieses Feld leer.

    6. Mandanten-ID. Geben Sie die Directory-ID (Mandant) ein, die Sie zuvor für Ihre Azure-Identitäts-App notiert haben, oder Allgemeines, je nachdem, welchen unterstützten Kontotyp Sie beim Erstellen der Identitätsanbieter-App ausgewählt haben. Um zu entscheiden, welcher Wert zugewiesen werden soll, befolgen Sie die folgenden Kriterien:

      • Wenn Sie entweder Konten nur in diesem Organisationsverzeichnis (nur Microsoft – Einzelner Mandant) oder Konten in einem beliebigen Organisationsverzeichnis (Beliebiger Microsoft Entra ID-Mandant – Mehrinstanzenfähig) ausgewählt haben, geben Sie die Mandanten-ID ein, die Sie zuvor für die Microsoft Entra-App notiert haben. Dies ist der Mandant, der den Benutzern zugeordnet ist, die authentifiziert werden können.

      • Wenn Sie Konten in einem beliebigen Organisationsverzeichnis (Beliebiger Microsoft Entra ID-Mandant – Mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) ausgewählt haben, geben Sie das Wort common anstelle einer Mandanten-ID ein. Andernfalls überprüft die Microsoft Entra-App den Mandanten, dessen ID ausgewählt wurde, und schließt persönliche Microsoft-Konten aus.

    7. Geben Sie für Bereiche eine durch Leerzeichen getrennte Liste von Graphberechtigungen ein, die für diese Anwendung erforderlich sind, z. B. User.Read, User.ReadBasic.All oder Mail.Read.

  5. Wählen Sie Speichern.

Testen der Verbindung

  1. Wählen Sie den Verbindungseintrag aus, um die erstellte Verbindung zu öffnen.

  2. Wählen Sie oben im Bereich Verbindungseinstellung für DienstanbieterVerbindung testen aus.

  3. Zum ersten Mal wird ein neues Browserfenster geöffnet, in dem Sie aufgefordert werden, ein Konto auszuwählen. Wählen Sie das Konto, das Sie verwenden möchten.

  4. Lassen Sie als Nächstes dem Identitätsanbieter die Verwendung Ihrer Daten (Anmeldeinformationen) zu. Die folgende Abbildung dient lediglich als Beispiel:

    Der Screenshot zeigt, wie Sie die Teams-Bot-Authentifizierungs-Verbindungszeichenfolge adv1 hinzufügen.

  5. Wählen Sie Annehmen aus.

  6. Die Seite Test Connection to <your-connection-name> Succeeded wird geöffnet. Aktualisieren Sie die Seite, wenn ein Fehler angezeigt wird. Die folgende Abbildung dient lediglich als Beispiel:

    Der Screenshot zeigt, wie Sie die Verbindungszeichenfolge adv1 der Teams-App-Authentifizierung hinzufügen.

Der Botcode verwendet den Verbindungsnamen zum Abrufen von Benutzerauthentifizierungstoken.

Vorbereiten des Bot-Beispielcodes

Nachdem die vorläufigen Einstellungen abgeschlossen sind, konzentrieren wir uns auf die Erstellung des Bots, der in diesem Artikel verwendet werden soll.

  1. Klonen Sie cs-auth-sample.

  2. Öffnen Sie Visual Studio.

  3. Wählen Sie auf der Symbolleiste Datei > Projekt/Projektmappe öffnen > aus, und öffnen Sie das Botprojekt.

  4. Aktualisieren Sie in C# appsettings.json wie folgt:

    • Legen Sie ConnectionName auf den Namen der Identitätsanbieterverbindung fest, die Sie der Botregistrierung hinzugefügt haben. Der in diesem Beispiel verwendete Name ist BotTeamsAuthADv1.
    • Legen Sie MicrosoftAppId auf die Bot-App-ID fest, die Sie zum Zeitpunkt der Botregistrierung gespeichert haben.
    • Legen Sie MicrosoftAppPassword auf den geheimen Kundenschlüssel fest, den Sie zum Zeitpunkt der Botregistrierung gespeichert haben.

    Abhängig von den Zeichen in Ihrem Botgeheimnis müssen Sie das Kennwort möglicherweise mit XML-Escapezeichen versehen. Beispielsweise müssen alle kaufmännischen Und-Zeichen (&) als &amp;codiert werden.

    {
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "ConnectionName": "",

  5. Navigieren Sie im Projektmappen-Explorer zum TeamsAppManifest Ordner, öffnen manifest.json Sie und legen Sie id und botId die Bot-App-ID fest, die Sie zum Zeitpunkt der Botregistrierung gespeichert haben. Weitere Informationen finden Sie unter App-Manifest.

Bereitstellen des Bots in Azure

Führen Sie zum Bereitstellen des Bots die Schritte unter Bereitstellen Ihres Bots in Azure aus.

Alternativ können Sie in Visual Studio die folgenden Schritte ausführen:

  1. Wählen Sie im Projektmappen-Explorer von Visual Studio den Projektnamen aus, und halten Sie diesen gedrückt (oder klicken Sie mit der rechten Maustaste darauf).

  2. Wählen Sie im Dropdownmenü Veröffentlichen aus.

  3. Wählen Sie im angezeigten Fenster den Link Neu aus.

  4. Wählen Sie im Dialogfeld App Service und Neu erstellen aus.

  5. Klicken Sie auf die Schaltfläche Veröffentlichen.

  6. Geben Sie im nächsten Dialogfeld die erforderlichen Informationen ein.

    Screenshot: Eingeben der erforderlichen Informationen für den Authentifizierungs-App-Dienst

  7. Wählen Sie Erstellen aus.

  8. Wenn die Bereitstellung erfolgreich abgeschlossen wurde, sollte sie in Visual Studio angezeigt werden. Eine Seite wird in Ihrem Standardbrowser mit der Meldung Ihr Bot ist bereit! geöffnet. Die URL ähnelt https://botteamsauth.azurewebsites.net/. Speichern Sie sie in einer Datei.

  9. Navigieren Sie in Ihrem Browser zum Azure-Portal.

  10. Überprüfen Sie Ihre Ressourcengruppe. Der Bot wird zusammen mit den anderen Ressourcen aufgeführt. Die folgende Abbildung dient lediglich als Beispiel:

    Screenshot: Überprüfen der Ressourcengruppe und des Bots

  11. Wählen Sie in der Ressourcengruppe den Namen der Botregistrierung (Link) aus.

  12. Wählen Sie im linken Bereich Einstellungen aus.

  13. Geben Sie im Feld Messagingendpunkt die URL ein, die Sie gerade abgerufen haben, gefolgt von api/messages. Beispiel: https://botteamsauth.azurewebsites.net/api/messages.

    Hinweis

    Für einen Bot ist nur ein Messagingendpunkt zulässig.

  14. Wählen Sie oben links die Schaltfläche Speichern aus.

Testen des Bots mithilfe von Emulator

Installieren Sie den Microsoft Bot Framework-Emulator. Weitere Informationen finden Sie unter Testen und Debuggen mit dem Emulator.

Damit die Botbeispielanmeldung funktioniert, müssen Sie den Emulator konfigurieren.

Konfigurieren des Emulators für die Authentifizierung

Wenn ein Bot eine Authentifizierung erfordert, müssen Sie den Emulator konfigurieren. So konfigurieren Sie:

  1. Starten Sie den Emulator.
  2. Wählen Sie im Emulator das Zahnradsymbol ⚙ unten links oder die Registerkarte Emulatoreinstellungen in der oberen rechten Ecke aus.
  3. Aktivieren Sie das Kontrollkästchen Authentifizierungstoken der Version 1.0 verwenden.
  4. Geben Sie den lokalen Pfad zum ngrok-Tool ein. Siehe Bot Framework Emulator/ngrok-Tunnelingintegration Wiki. Weitere Toolinformationen finden Sie unter ngrok.
  5. Aktivieren Sie das Kontrollkästchen, indem Sie ngrok ausführen, wenn der Emulator gestartet wird.
  6. Wählen Sie die Schaltfläche Speichern aus.

Wenn der Bot eine Anmeldekarte anzeigt und der Benutzer die Anmeldeschaltfläche auswählt, öffnet der Emulator eine Seite, mit der sich der Benutzer beim Authentifizierungsanbieter anmelden kann. Sobald der Benutzer dies tut, generiert der Anbieter ein Benutzertoken und sendet es an den Bot. Danach kann der Bot im Namen des Benutzers handeln.

Lokales Testen des Bots

Nachdem Sie den Authentifizierungsmechanismus konfiguriert haben, können Sie die eigentlichen Bottests durchführen.

  1. Führen Sie das Botbeispiel lokal auf Ihrem Computer aus, z. B. über Visual Studio.

  2. Starten Sie den Emulator.

  3. Wählen Sie die Schaltfläche Bot öffnen aus.

  4. Geben Sie in der Bot-URL die lokale URL des Bots ein. In der Regel unter http://localhost:3978/api/messages.

  5. Geben Sie in der Microsoft-App-ID die App-ID des Bots aus ein appsettings.json.

  6. Geben Sie im Microsoft-App-Kennwort das App-Kennwort des Bots aus der appsettings.jsonein.

  7. Wählen Sie Verbinden aus.

  8. Nachdem der Bot ausgeführt wurde, geben Sie einen beliebigen Text ein, um die Anmeldekarte anzuzeigen.

  9. Wählen Sie die Schaltfläche Anmelden aus.

  10. Es wird ein Popupdialogfeld angezeigt, in dem Sie bestätigen, dass sie die Url öffnen, um den Benutzer des Bots (Sie) zu authentifizieren.

  11. Wählen Sie Bestätigen aus.

  12. Wenn Sie dazu aufgefordert werden, wählen Sie das Konto des entsprechenden Benutzers aus.

  13. Je nachdem, welche Konfiguration Sie für den Emulator verwendet haben, erhalten Sie eine der folgenden Optionen:

    1. Verwenden des Anmeldungsprüfcodes
      ✓ Ein Fenster mit dem Validierungscode wird geöffnet.
      ✓ Kopieren Sie den Validierungscode, und geben Sie diesen in das Chatfeld ein, um die Anmeldung abzuschließen.
    2. Verwenden von Authentifizierungstoken.
      ✓ Sie sind basierend auf Ihren Anmeldeinformationen angemeldet.

    Die folgende Abbildung zeigt ein Beispiel für die Bot-Benutzeroberfläche nach der Anmeldung:

    Screenshot: Beispiel für die Bot-Benutzeroberfläche nach der Anmeldung

  14. Wenn Sie Ja auswählen, wenn der Bot fragt Möchten Sie Ihr Token anzeigen?, erhalten Sie die folgende Antwort:

    Screenshot: Auswählen der Zustimmung

  15. Geben Sie abmelden in das Eingabechatfeld ein, um sich abzumelden. Das Benutzertoken wird freigegeben, und der Bot kann erst dann in Ihrem Namen handeln, wenn Sie sich erneut anmelden.

Hinweis

Die Bot-Authentifizierung erfordert die Verwendung des Bot Connector-Diensts. Der Dienst greift auf die Bots-Registrierungsinformationen für Ihren Bot zu.

Testen des bereitgestellten Bots

  1. Navigieren Sie in Ihrem Browser zum Azure-Portal.

  2. Suchen Sie Ihre Ressourcengruppe.

  3. Wählen Sie den Ressourcenlink aus. Die Ressourcenseite wird angezeigt.

  4. Wählen Sie auf der Ressourcenseite Testen im Webchat aus. Der Bot startet und zeigt die vordefinierten Begrüßungen an.

  5. Geben Sie etwas in das Chatfeld ein.

  6. Wählen Sie das Feld Anmelden aus.

  7. Es wird ein Popupdialogfeld angezeigt, in dem Sie bestätigen, dass sie die Url öffnen, um den Benutzer des Bots (Sie) zu authentifizieren.

  8. Wählen Sie Bestätigen aus.

  9. Wenn Sie dazu aufgefordert werden, wählen Sie das Konto des entsprechenden Benutzers aus. Die folgende Abbildung zeigt ein Beispiel für die Bot-Benutzeroberfläche nach der Anmeldung:

    Screenshot: Beispiel für die Benutzeroberfläche des Teams-Bots nach der Anmeldung

  10. Wählen Sie die Schaltfläche Ja aus, um Ihr Authentifizierungstoken anzuzeigen. Die folgende Abbildung dient lediglich als Beispiel:

    Screenshot: Auswählen der Schaltfläche

  11. Geben Sie abmelden in das Eingabechatfeld ein, um sich abzumelden.

    Screenshot: Abmelden beim Bot

Hinweis

Wenn Sie Probleme beim Anmelden haben, versuchen Sie erneut, die Verbindung zu testen, wie in den vorherigen Schritten beschrieben. Dadurch kann das Authentifizierungstoken neu erstellt werden. Mit dem Bot Framework Webchat-Client in Azure müssen Sie sich möglicherweise mehrmals anmelden, bevor die Authentifizierung ordnungsgemäß eingerichtet wird.

Installieren und Testen des Bots in Teams

  1. Stellen Sie in Ihrem Botprojekt sicher, dass der Ordner TeamsAppManifest die manifest.json zusammen mit einer outline.png und color.png-Dateien enthält.

  2. Navigieren Sie im Projektmappen-Explorer zum TeamsAppManifest Ordner. Bearbeiten Sie manifest.json, indem Sie die folgenden Werte zuweisen:

    1. Stellen Sie sicher, dass die Bot-App-ID, die Sie zum Zeitpunkt der Botregistrierung erhalten haben, id und botIdzugewiesen ist.
    2. Weisen Sie diesen Wert zu: validDomains: [ "token.botframework.com" ].

  3. Wählen Sie die Dateien manifest.json, outline.png und color.png aus und zippen Sie sie.

  4. Öffnen Sie Microsoft Teams.

  5. Wählen Sie im linken Bereich unten das Apps-Symbol aus.

  6. Wählen Sie im rechten Bereich unten Benutzerdefinierte App hochladen aus.

  7. Wechseln Sie zum TeamsAppManifest Ordner, und laden Sie das gezippte Manifest hoch. Das folgende Fenster wird angezeigt:

    Screenshot: Beispiel für den Bot, nachdem er in Teams hochgeladen wurde

  8. Klicken Sie auf die Schaltfläche Zum Team hinzufügen.

  9. Wählen Sie im nächsten Fenster das Team aus, in dem Sie den Bot verwenden möchten.

  10. Wählen Sie die Schaltfläche Bot einrichten aus.

  11. Wählen Sie im linken Bereich die drei Punkte (●●●) aus. Wählen Sie dann das Symbol Entwicklerportal aus.

  12. Wählen Sie die Registerkarte Manifest-Editor aus. Das Symbol für den hochgeladenen Bot sollte angezeigt werden.

  13. Außerdem sollte der Bot in der Chatliste als Kontakt aufgeführt sein, über den Sie Nachrichten mit dem Bot austauschen können.

Testen des Bots lokal in Teams

Teams ist ein vollständig cloudbasiertes Produkt. Alle Dienste, auf die zugegriffen wird, müssen über HTTPS-Endpunkte aus der Cloud verfügbar sein. Damit der Bot (unser Beispiel) in Teams funktioniert, müssen Sie daher entweder den Code in der Cloud Ihrer Wahl veröffentlichen oder eine lokal ausgeführte Instanz extern über ein Tunneling-Tool zugänglich machen. Wir empfehlen ngrok, wodurch eine extern adressierbare URL für einen Port erstellt wird, den Sie lokal auf Ihrem Computer öffnen. Führen Sie die folgenden Schritte aus, um ngrok als Vorbereitung für die lokale Ausführung Ihrer Teams-App einzurichten:

  1. Wechseln Sie in einem Terminalfenster zu dem Verzeichnis, in dem Sie ngrok.exe installiert haben. Es wird empfohlen, den Pfad Umgebungsvariable so festzulegen, dass er darauf zeigt.

  2. Führen Sie z. B ngrok http 3978 --host-header=localhost:3978 aus. Ersetzen Sie die Portnummer nach Bedarf. Er startet ngrok, um an dem von Ihnen angegebenen Port zu lauschen. Im Gegenzug erhalten Sie eine extern adressierbare URL, die so lange gültig ist, wie ngrok ausgeführt wird. Die folgende Abbildung dient lediglich als Beispiel:

    Screenshot der Authentifizierungs-Verbindungszeichenfolge für die Teams-Bot-App adv1

  3. Kopieren Sie die HTTPS-Weiterleitungsadresse, die der folgenden ähnelt: https://dea822bf.ngrok.io/.

  4. Fügen Sie an /api/messages , um abzurufen https://dea822bf.ngrok.io/api/messages. Dies ist der Nachrichtenendpunkt für den Bot, der lokal auf Ihrem Computer ausgeführt wird und über das Web in einem Chat in Teams erreichbar ist.

  5. Ein letzter Schritt besteht darin, den Nachrichtenendpunkt des bereitgestellten Bots zu aktualisieren. Im Beispiel haben wir den Bot in Azure bereitgestellt. Führen wir also die folgenden Schritte aus:

    1. Navigieren Sie in Ihrem Browser zum Azure-Portal.
    2. Wählen Sie Ihre Bot-Registrierung aus.
    3. Wählen Sie im linken Bereich Einstellungen aus.
    4. Geben Sie im rechten Bereich im Feld Nachrichtenendpunkt die ngrok-URL ein, in unserem Beispiel, https://dea822bf.ngrok.io/api/messages.

  6. Starten Sie Ihren Bot lokal, z. B. im Debugmodus von Visual Studio.

  7. Testen Sie den Bot während der lokalen Ausführung, indem Sie Webchat testen des Bot Framework-Portals verwenden. Wie der Emulator ermöglicht ihnen dieser Test nicht den Zugriff auf Teams-spezifische Funktionalität.

  8. Im Terminalfenster, in dem ngrok ausgeführt wird, wird HTTP-Datenverkehr zwischen dem Bot und dem Webchatclient angezeigt. Wenn Sie eine detailliertere Ansicht wünschen, geben Sie in einem Browserfenster http://127.0.0.1:4040 ein, die Sie aus dem vorherigen Terminalfenster abgerufen haben. Die folgende Abbildung dient lediglich als Beispiel:

    Screenshot: ngrok-Tests für Authentifizierungsbot-Teams

Hinweis

Wenn Sie ngrok beenden und neu starten, ändert sich die URL. Um ngrok in Ihrem Projekt zu verwenden, und abhängig von den verwendeten Funktionen müssen Sie alle URL-Verweise aktualisieren.

Weitere Informationen

TeamsAppManifest/manifest.json

Dieses Manifest enthält Informationen, die Teams benötigt, um eine Verbindung mit dem Bot herzustellen:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "developer": {
    "name": "TeamsBotAuth",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.teams.com/privacy",
    "termsOfUseUrl": "https://www.teams.com/termsofuse"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "name": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "description": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "",
      "scopes": [
        "groupchat",
        "team"
      ],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [ "token.botframework.com" ]
}

Bei der Authentifizierung verhält sich Teams anders als andere Kanäle.

Behandeln der Aufrufaktivität

Anstelle der ereignisbasierten Aktivität, die von anderen Kanälen verwendet wird, wird eine Aufrufaktivität an den Bot gesendet. Dies erfolgt durch Unterklassen des ActivityHandlers.

Bots/DialogBot.cs

    public class DialogBot<T> : TeamsActivityHandler where T : Dialog
    {
        protected readonly BotState ConversationState;
        protected readonly Dialog Dialog;
        protected readonly ILogger Logger;
        protected readonly BotState UserState;

        public DialogBot(ConversationState conversationState, UserState userState, T dialog, ILogger<DialogBot<T>> logger)
        {
            ConversationState = conversationState;
            UserState = userState;
            Dialog = dialog;
            Logger = logger;
        }

        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
        {
            await base.OnTurnAsync(turnContext, cancellationToken);

            // Save any state changes that might have occurred during the turn.
            await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
            await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            Logger.LogInformation("Running dialog with Message Activity.");

            // Run the Dialog with the new message Activity.
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    }
}

Bots/TeamsBot.cs

DieAufrufaktivität muss an das Dialogfeld weitergeleitet werden, wenn OAuthPrompt verwendet wird.

protected override async Task OnTeamsSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with signin/verifystate from an Invoke Activity.");

    // The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.

    // Run the Dialog with the new Invoke Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

TeamsActivityHandler.cs


protected virtual Task OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    switch (turnContext.Activity.Name)
    {
        case "signin/verifyState":
            return OnSigninVerifyStateAsync(turnContext, cancellationToken);

        default:
            return Task.CompletedTask;
    }
}

protected virtual Task OnSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

Codebeispiel

Dieser Abschnitt enthält ein Sdk-Beispiel für die Botauthentifizierung v3.

Beispielname Beschreibung .NET Node.js Python Manifest
Botauthentifizierung In diesem Beispiel wird gezeigt, wie Sie mit der Authentifizierung in einem Bot für Teams beginnen. View View View View
Registerkarten-, Bot- und Nachrichtenerweiterungs-SSO (ME) Dieses Beispiel zeigt Microsoft Entra SSO for Tab, Bot, and ME – search, action, link-unfurling. View View – Anzeigen

Siehe auch