Waehrend GPT und andere große Sprachmodelle die Art und Weise revolutionieren, wie wir kommunizieren und wie wir massgeschneiderte Loesungen für Unternehmen entwickeln koennen, war die Nachfrage nach intuitiven Frontends, um diese KI-Faehigkeiten an die Endnutzer zu bringen, noch nie so hoch. Genau dafür bauen wir in diesem Beitrag einen eigenen SSO-Teams-Bot. Wenn du dich fragst, ob es einen reibungslosen Weg gibt, einen Bot in Microsoft Teams zu integrieren, hast du Glueck! In diesem Blog fuehre ich dich durch den Prozess, deinen eigenen, auf Microsoft Teams und das Bot Framework von Microsoft zugeschnittenen Bot zu entwickeln und bereitzustellen.
Inhaltsverzeichnis
Meine Erfahrung im Bot-Dschungel
Sich in der Welt der Microsoft-Teams-Bot-Entwicklung zurechtzufinden, kann sich anfuehlen wie der Weg durch einen dichten Dschungel voller veralteter Projekte, nicht funktionierender Beispiele und falscher Anleitungen. Nachdem ich beim Bau meines ersten Bots auf zahlreiche Huerden gestossen war, wurde mir klar, dass eine klare und unkomplizierte Anleitung noetig ist. Deshalb habe ich diesen Blog verfasst, um dir den Einstieg in die Bot-Entwicklung zu erleichtern und dir zu helfen, die Fallstricke zu vermeiden, auf die ich gestossen bin.
Wie funktioniert es?
Um einen Teams-Bot einzurichten, benoetigst du im Grunde 3 Komponenten. Eine davon ist sicherlich die Client-Komponente, wie die Teams-App auf deinem Geraet oder im Browser. Die zweite ist der Bot-Dienst, der in Azure bereitgestellt werden muss (wie das geht, wird weiter unten gezeigt), und die dritte ist dein Bot-Endpunkt, der ein App Service oder ein Container sein kann, der z. B. in AKS (Azure Kubernetes Service) bereitgestellt wird.
Das ist der technische Aufbau für die Infrastruktur und die benoetigten Dienste, aber wir wollen eine SSO-Anwendung (Single Sign-On) bauen. Schauen wir uns nun auch an, wie das Authentifizierungs-Setup funktioniert. Hierbei ist es wichtig, dass es für den Nutzer transparent ist. Das bedeutet, wir wollen zusaetzliche Eingabeaufforderungen vermeiden.
Der erste Schritt ist, dass sich der Nutzer in seinem MS-Teams-Client anmeldet und authentifiziert
App-Registrierung
Das Erste, was wir brauchen, ist eine Entra ID App Registration. Ich moechte dir zeigen, wie du eine Single-Tenant-App erstellst, aber dieselben Schritte gelten auch für eine Multi-Tenant-App. Um diese zu erstellen, navigiere zum Entra ID App Registration Blade und klicke oben links auf “New Registration”.
Gib im Erstellungsdialog einen Namen ein und waehle Single-Tenant-App. Setze danach die Redirect URI auf “https://token.botframework.com/.auth/web/redirect” und klicke auf “Register”.
Die App-Registrierung ist nun erstellt. Als Naechstes muessen wir sie konfigurieren. Aber bevor wir das tun, kopiere die Application/Client ID und die Tenant ID und notiere sie dir.
Das Zweite, was wir brauchen, ist das App Secret. Du findest es im Bereich Certificates & Secrets. Klicke hier auf “New Client Secret” und notiere es dir ebenfalls. Es wird für die weiteren Schritte benoetigt.
Navigiere danach im linken Menue zu “Expose an API“. Lege deine Application ID URL fest. Gib dazu api://botid-{ID_OF_THE_BOT} ein. Die Bot ID ist die ID, die bereits im Feld steht.
Klicke als Naechstes auf “Add a scope“. Gib access_as_user als Scope-Namen ein, setze “Who can consent?” auf “Admins and users” und gib einen Anzeigenamen und eine Beschreibung ein. Stelle sicher, dass State auf Enabled gesetzt ist.
Fuege die folgenden IDs als autorisierte Clients für deine Anwendung hinzu.
Minimum:
- 1fec8e78-bce4-4aaf-ab1b-5451cc387264 – Teams Mobil-/Desktop-Anwendung)
- 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 – Teams Webanwendung)
Navigiere als Naechstes auf der linken Seite zu “API permissions”. Fuege alle benutzerdelegierten Berechtigungen hinzu, die deine App benoetigt, sowie die openid- und profile-Berechtigung. Die meisten Apps benoetigen die User.Read-Berechtigung, um z. B. die User ID oder die E-Mail abzurufen.
Navigiere zu “Authentication” und stelle sicher, dass die Kontrollkaestchen Access tokens und ID tokens aktiviert sind, wie im Screenshot unten gezeigt.
Azure-Bot-Erstellung
Wie oben erwaehnt, benoetigen wir auch eine Bot-Ressource. Um diese zu erstellen, oeffne das Azure Portal und tippe in die Suche Azure Bot ein. Waehle dies aus und klicke auf Erstellen.
Waehle für die Konfiguration “Single Tenant” (optional kannst du auch Multi Tenant waehlen). Aktiviere “Use existing app registration” und gib die oben notierte Client ID und das Secret ein. Klicke beim Azure Bot auf Review + create.
Es ist wichtig, dass du im Konfigurationsbereich den Messaging Endpoint ausfuellst. Die URL dafuer ist der oeffentliche FQDN/die IP deines Bot-Dienstes oder ngrok-Servers plus /api/messages. Aber wir kommen spaeter darauf zurueck, wie du diesen FQDN erhaeltst.
Als Naechstes muessen wir den Teams-Channel aktivieren. Navigiere auf der linken Seite zu Channels, waehle in diesem Menue MS Teams aus und akzeptiere die TOU, um diese Funktion zu aktivieren.
Sobald das erledigt ist, muessen wir auch die SSO-Einstellung festlegen. Das kannst du im Konfigurationsbereich tun. Waehle hier Add OAuth Connection Setting. Fuelle diese Optionen mit den zuvor notierten Informationen aus. Es ist wichtig, sich den Namen zu notieren, den du für die OAuth-Verbindung festlegst; wir brauchen ihn spaeter.
Wenn du eine Multi-Tenant-App hast, setze “common” als Tenant ID, und für eine Single-Tenant-App deine zuvor notierte Tenant ID. Setze als Scope alle Scopes, die du in der App-Registrierung festgelegt hast, in unserem Beispiel ist das “openid profile User.Read”. Sobald das erledigt ist, klicke auf “Save” und die Konfiguration ist für den Moment abgeschlossen.
Wie fuehrt man den Bot lokal aus?
Zuerst musst du dieses Repository klonen https://github.com/JayRHa/TeamsSSOBot.
Als Naechstes wollen wir den Bot mithilfe von ngrok lokal ausfuehren, um einen guten Entwicklungsablauf zum Testen der Aenderungen zu haben. Das Erste, was du tun musst, ist die notierten Informationen (appid, secret, tenantId, connectionNam und den Apptype) in die .env-Datei einzutragen.
Um deinen lokalen Code im Internet erreichbar zu machen, muessen wir den ngrok-Server starten. Das ist eine Moeglichkeit, aber es gibt auch andere Loesungen wie Dev Tunnel, um einem Port auf localhost eine URL zuzuweisen und so einen Tunnel zu deiner lokalen Maschine zu haben. Um den ngrok-Server auszufuehren, musst du ihn zuerst installieren und ein Konto erstellen, um einen API-Key zu erhalten. Sobald das erledigt ist, kannst du ihn mit ngrok http 3978 ausfuehren. Wenn der Server laeuft, zeigt er dir einen Bildschirm mit der zugewiesenen URL an. Diese URL kannst du der Messaging-Endpoint-Konfiguration im Bot-Dienst hinzufuegen.
Das Einzige, was wir jetzt noch tun muessen, ist, den Server-Code mit `npm i && npm start` auszufuehren.
Wie fuegt man die APP zu Teams hinzu?
Das ist der einfachste Teil der ganzen Reise. Das Einzige, was du tun musst, ist zum Ordner appManifest zu navigieren und die manifest.json zu oeffnen. Hier kannst du die APPID und die BotID durch die notierten Werte ersetzen.
Du kannst die Icons verwenden, die bereits im Ordner liegen, oder sie durch eigene ersetzen. Dasselbe gilt für die Links und Beschreibungen in der manifest.json.
Sobald du fertig bist, musst du aus beiden Icons und dem Manifest eine ZIP-Datei erstellen (nicht aus dem Ordner). Danach oeffne deinen Teams-Client, klicke auf Apps, dann auf Manage your apps und klicke auf Upload App.
Wie nimmt man Aenderungen am Bot vor?
Wie du vielleicht weisst, entwickle ich meistens in PowerShell oder Python. Das Bot Framework SDK unterstuetzt 4 Sprachen, naemlich Python, .Net, JS und TS. Mein erster Versuch war mit Python, aber ich konnte es nicht zum Laufen bringen. Nach einigen Recherchen fand ich heraus, dass es in diesem Framework einen Bug gibt, der es unmoeglich macht, einen funktionierenden SSO-Bot in Python zu haben (das koennte behoben sein, wenn du diesen Blog liest). Das war der Grund, warum ich mich entschieden habe, auf JS zu wechseln. JS ist nicht meine groesste Staerke, aber ich hatte in der Vergangenheit einige Projekte damit entwickelt.
Aber lass uns in dieses Thema eintauchen. Bevor ich dir zeige, wie du Aenderungen am Bot-Code vornimmst, erklaere ich dir zunaechst, was der aktuelle Code tut und wie er funktioniert.
Die Hauptdatei ist die Index.js, die den Bot und die (message/api) ausfuehrt.
Dieses Skript hat Abhaengigkeiten zur dialogBot.js und zur teamsBot.js im bot-Ordner. Dies sind beides Dateien, in denen sich die Trigger für onMemberApp und onMessages befinden. Das sind die Trigger, die reagieren, wenn du den Bot hinzufuegst und wenn du eine Nachricht an den Bot sendest.
Zusaetzlich wollen wir auch ein SSO-Token für den Graph-Scope anfordern, um auch zusaetzliche Informationen vom Nutzer zu erhalten. Dies findest du im dialog-Ordner in der mainDialog.js-Datei. Dieser Dialog sammelt dein SSO-Token und speichert es in der userTokenMap, um es in einer der Trigger-Aktionen zu verwenden.
Wenn du auf Nachrichten reagieren oder Buttons hinzufuegen moechtest, kannst du das in der dialogBot.js tun.