Teams 3rd Party Client-API
In der Teams Version 1.6.00.376 wurde eine neue Client-API bereitgestellt, die vom Anwender aktiviert werden kann. Diese Seite beschreibt, was dahinter steckt.
Die API ist mittlerweile auch im Teams 2.x Client vorhanden.
Historie
Die API hat eine wechselnde Vorgeschichte, denn sie war ziemlich "überraschend" da und dann wieder weg um dann wieder zu kommen. Aktuell gibt es aber keine öffentliche API-Beschreibung und Änderungen sind weiter möglich.
Zeit | Beschreibung |
---|---|
Bis Feb 2023 |
Lange Zeit gab es eigentlich keine API auf dem Teams Client. Entwickler konnten nur über Graph bestimmte Funktionen auf dem Backend ansprechen. Wobei das nicht ganz stimmt, denn Teams.EXE hat lokale sich schon als "Default IM Provider" registriert und auch eine COM-API bereitgestellt, die von Outlook auch genutzt wird. |
1. Feb 2023 |
Anfang Februar 2023 gab es dann die ersten Hinweise, dass auf dem Teams Windows-Client eine neue API erreichbar sein soll, die in den Einstellungen aktiviert werden kann. Auch Microsoft hat darüber gebloggt |
3. Feb 2023 |
Auf der Webseite von Elgado gibt es ein Plugin, mit dem der Microsoft Teams Client über die Elgato Steuerungen fernbedient werden kann. Das geht weit über die bisherige Funktion hinaus, per "Sendkey" einfach Hotkey-Sequenzen an ein Windows Fenster zu senden. Entsprechend umfangreich war auch die Ankündigung. Verschiedene Entwickler haben sich die Elgado-Addons angeschaut und daraus Rückschlüsse auf die Funktion der API abgeleitet und eigene Tools gebaut |
4. Feb 2023 |
Die Ankündigungen und AddOns bei Elgado sind komplett verschwunden. Nur das YouTube-Video ist weiter erreichbar. |
6./7. Feb 2023 |
Microsoft hat die API im Teams Client anscheinend für alle Clients deaktiviert. Ich habe nicht nachvollzogen, ob nun alle Clients ein Update erhalten haben oder über Policies die Funktion ausgeblendet wurde. Fakt ist aber, dass ab der Zeit kein Zugriff auf die API möglich ist. |
13. Feb 2023 |
Neue Version des Streamdeck mit Microsoft
Team Plugin |
20. Feb 2023 |
Von Kollege bei Net at Work wurde ich darauf aufmerksam gemacht, dass in den Teams Einstellungen des Preview-Clients wieder die API aktiviert werden kann. Das Elgado-AddOn oder andere Quellen zur API sind aber nicht verfügbar. |
8 Nov 2023 |
Es tut sich was mit dem New Teams Client / Teams 2.1. Es gibt hier wieder die Einstellung und das Elgado Plugin funktioniert wieder. |
- Microsoft Teams: Support for Stream Deck to interact with
Microsoft Teams within a meeting
https://www.microsoft.com/de-de/microsoft-365/roadmap?filters=&searchterms=96112 - Business Tools: Microsoft Teams
https://apps.elgato.com/plugins/com.microsoft.teams - Update! Teams-PowerPoint Plugins for Elgato Stream Deck and
Mobile
https://techcommunity.microsoft.com/t5/healthcare-and-life-sciences/update-teams-powerpoint-plugins-for-elgato-stream-deck-and/ba-p/3767650
Aktivierung in Teams 2.1
Es hat einige Zeit gedauert, bis Microsoft im neuen Teams Client eine 3rd Party API wieder integriert hat. In den Einstellungen können Sie nun wieder die API aktivieren. Aber anders als bei Teams 1.0 können Sie keine GUID als "Zugangscode" eintragen. Sie steuern erst einmal nur "Ein/Aus.
Die Schrittstelle ist dann aber erreichbar und wenn ich z.B. Elgado Streamdesk starte, dann passiert immer noch nichts. Sobald ich aber eine Aktivität auslösen möchte, dann meldet sich ein Teams-Dialog
Hier muss ich dann als Benutzer einmalig meine Zustimmung (Consent) erteilen oder auch nicht, ob die fragliche Software auf die Schnittstelle zugreifen kann. Nach der Zustimmung sehe ich in Teams auch die App und kann Sie hier auch nachträglich wieder blocken.
Ich habe aber keinen einfachen Weg gefunden, die App hier wieder zu löschen.
Auch ist noch einiges offen, z.B. wie die API genutzt wird, wie sich z.B. Elgado als legitime App ausweist etc.
Der Link unter "Weitere Informationen verweist am 8 Nov 2023 immer noch auf eine Seite, die eine Konfiguration im Teams 1-Client beschreibt und auch die Plugin-Seite auf Elgado beschreibt noch einen APIKey
- Connect to third-party devices in
Microsoft Teams
https://support.microsoft.com/en-us/office/connect-to-third-party-devices-in-microsoft-teams-aabca9f2-47bb-407f-9f9b-81a104a883d6 - Elgado: Microsoft Teams
https://marketplace.elgato.com/product/microsoft-teams-da5e2bbc-197c-4afe-8a85-a9941bf52697
Aktivierung in Teams 1.0
Neben den bekannten Server-APIs (Siehe Teams API Übersicht) gibt es seit ca. Anfang 2023 auch eine Client-API, die 3rd-Party Produkte nutzen können. Mit dem richtigen Client können Sie die Funktion in den Einstellungen unter Datenschutz aktivieren.
Aktuell ist der Default "off" und wenn Sie ihn anschalten, dann erstellt der Teams Client ein API-Token.
Diese API-Token müssen Sie dann an das Programme übergeben, damit diese "Teams fernsteuern" dürfen. Der Link unter "Weitere Informationen" verweist auf die folgende URL, die eine Weiterleitung ist:
- Connect third-party devices to Teams
https://aka.ms/teamscommandpad
https://support.microsoft.com/en-us/office/connect-third-party-devices-to-teams-aabca9f2-47bb-407f-9f9b-81a104a883d6?storagetype=live
Leider steht hier nichts über die API selbst sondern nur, wie sie diese ein- und ausschalten.
Funktion
Laut Microsoft Seite konnten über die API folgende Funktionen gesteuert werden:
- Besprechungsaufzeichnung Starten/Stoppen
- Hand heben und senken
- Reaktionen senden, z.B. Smileys etc.
- Stummschaltung Ein/Ausschalten
- Besprechung verlassen
- Kamera Ein/Aus-Schalten
- Hintergrund unscharf aktivieren und deaktivieren
Zusätzlich kann die API auch den Status zurückliefern
Der Unterschied zu den Teams Hotkeys, welche Sie durchaus auch mit Drittprogrammen wie "AutoHotkey" oder aus Skripten simulieren können, funktionieret diese API auch mit Teams im Hintergrund und ohne Fokus. Die Bedienung ist also "sicherer".
Ich konnte noch nicht in Erfahrung bringen, ob über die API auch der aktuelle Status der möglichen Einstellungen ermittelbar oder der Erhalt anderer Informationen von Teams möglich ist.
Die Schnittstelle ist eine direkte Verbindung auf dem Client und nutzt keine Kommunikation über das Microsoft Teams Backend. Quasi eine lokale Remote Control-API.
Steamdeck u.a.
Es hat dann auch nicht lange gedauert, bis erste 3rd Party Apps die neue Funktionen genutzt haben. So hat Microsoft wohl mit Elgado Steamdeck diese Funktion integriert, damit Sie über diese Hotkeys effektiv ihre Meetings steuern können.
Produkt | Links |
---|---|
Elgado Stream Deck
|
Das Bild zeigt ein Elgado Steamdeck MK.2 für ca. 150€. Ich kann aber nicht sagen, ob es das "Plate" zur Gestaltung tatsächlich gibt oder nur Marketing ist.
Microsoft Teams | Elgato Stream Deck
Plugin Spotlight Steamdeck Plugin (Am 3.2.2023
erreichbar, ab 4.2.2023 nicht mehr) |
MuteDeck |
|
Es ist davon auszugehen, das bald auch weitere Systeme damit Teams steuern können. Es ist ja relativ einfach mit einer kleinen Windows Software z.B. auch einen XBOX-Controller oder einen Arduino oder andere Geräte als Fernsteuerung für Teams aufzubauen.
Bei mir hat die Teams-Integration etwas gehakt, da der in den Teams Einstellungen angezeigte Key nicht mit dem tatsächlich in Teams gespeicherten Wert übereingestimmt hat und damit Streamdeck keine Verbindung aufbauen konnte.
-
Teams Controller
Übersicht von Zusatzsteuerungen für PCs und Teams
Es gibt auch einige Bastelprojekte, die durchaus interessant sind, z.B.
- freedeck-ino
https://github.com/FreeYourStream/freedeck-ino - Build This Yourself for Just $20! FreeTouchDeck.
https://www.youtube.com/watch?v=soIGV6BszcM - https://github.com/DustinWatts/FreeTouchDeck
Community Samples
Es hat auch nicht lange gedauert, bis erste Samples und Tools Public gestellt wurden, die diese API für ganz andere Zwecke verwenden.
- Teams2MQTT
https://github.com/lafe/Teams2Mqtt
Ein lokaler Service auf dem Client überwacht die Teams Client API und meldet Veränderungen per MQTT an einen MQTT-Broker, z.B. Home Assistant. - Teams Monitor
https://github.com/svrooij/teams-monitor
https://twitter.com/svrooij/status/1621252911274631171
Liest auf dem Client den Meeting-Status und sendet diese an einen Webhook. - Teams Client Api Sample
https://github.com/GrillPhil/TeamsClientApiSample
So schön all diese Ansätze sind, so zeigen Sie doch nur, dass es einen Bedarf für solche Abfragen und Aktionen gibt.
Analyse über Steamdeck
In Teams habe ich noch keine direkte Möglichkeit gefunden, die Schnittstelle einfach zu analysieren. Aber die Steamdeck-Software hat ebenfalls eine Diagnose-Schnittstelle, die sie aktivieren können. Hier sehen Sie dann, wie Steamdeck mit Teams kommuniziert:
- Stream Desk SDK: Getting Started: 5. Debugging
https://docs.elgato.com/sdk/plugins/getting-started#5.-debugging
Sie müssen dazu einen RegKey setzen:
Windows Registry Editor Version 5.00 [HKEY_CURRENT_USER\Software\Elgato Systems GmbH\StreamDeck] "html_remote_debugging_enabled"=dword:00000001
Danach können Sie mit einem Browser über http://localhost:23654/ die Schnittstelle debuggen:
Mit einem Klick auf den Link startet sich wieder ein Chromium-Debugger und sie können sich sogar den Sourcecode des Elgado Plugins anschauen.
So sehen wir, dass auch die Version vom Dez 2023 mit dem neuen Teams 2.1-Client weiterhin den Port 8124 nutzt.
Nutzung der API
Die API ist aktuell nicht mehr nutzbar und die Beschreibung daher falsch. Ich habe Sie daher entfernt. Die Schnittstelle war keine COM-API, wie sie die IM-Integration (Siehe Teams Presence und Office IM API) nutzt. Stattdessen hat Teams einen Websocket auf Port 8124 geöffnet.
Sobald ich neue Informationen bekomme, ergänze ich sie hier
- ClientWebSocket Klasse
https://learn.microsoft.com/de-de/dotnet/api/system.net.websockets.clientwebsocket?view=net-7.0 - WebSocket sample
https://learn.microsoft.com/en-us/samples/microsoft/windows-universal-samples/websocket/ - Websockets from scratch
https://www.leeholmes.com/websockets-from-scratch/ - Powershell Slack Bot using the Real Time Messaging API
https://wragg.io/powershell-slack-bot-using-the-real-time-messaging-api/ - Async Websocket PowerShell client (producer/consumer pattern)
https://gist.github.com/byt3bl33d3r/910b3161d54c2d6a3d5e1050c4e1013e - Reddit
https://www.reddit.com/r/elgato/comments/10r73k0/microsoft_teams_official_stream_deck_Plugin/
Admin Control
Leider hat Microsoft diese API im Lauf des Jan/Feb 2023 auf den Client nach und nach bereitgestellt aber noch keine Steuerung durch den Administrator vorgesehen. Ich kann als Administrator über eine ClientPolicy aktuell weder verhindern noch die Nutzung automatisch erlauben oder auf bestimmte Clients beschränken.
Es hat fast den Anschein, dass hier eine API sehr schnell für einem besonderen Event bereitgestellt werden sollte aber weder die Dokumentation noch Steuerung mitgekommen ist.
Sobald ich hier weitere Informationen habe, reiche ich diese nach.
API-Sicherheit
Auch wenn es von Microsoft noch keine offizielle Dokumentation gibt, wurde sehr schnell analysiert, wie die API funktioniert. Microsoft hat ein AddOn für StreamDeck bereitgestellt, welches klassisch "JavaScript" ist und aus dem man erkennen kann, dass eine Websocket-Verbindung auf Port 8124 aufgebaut wird. Ein Blick in den Sourcecode reicht:
%appdata%\Elgato\StreamDeck\Plugins\com.microsoft.teams.sdPlugin\dist\main.js
Wobei der alles andere als direkt lesbar ist. JavaScript, die mittels "EVAL()" weiteren Code ausführt und weiteren Code auch noch "Base64"-codiert enthält. Ein Ausschnitt davon zeigt die Verbindung
* Establish a connection to a running Microsoft Teams process. * @TODO do we need to add a check that the Teams process is running * @param token a string authentication token provided by Teams. if token is * null or undefined, the connection to the server will fail; the plugin itself * will not crash so no input validation is needed. * @param autoreconnect set true if you want to autoreconnect if the conenction fails * @param port the port to connect to, will eventually be parsed from the token */ TeamsMeetingController.prototype.connectToTeams = function (token, autoreconnect, port) { if (autoreconnect === void 0) { autoreconnect = true; } if (port === void 0) { port = 8124; } this.logInfo(\"Connecting to server with token: \" + token + \" and autoreconnect: \" + autoreconnect); this.ipc.connectToTeamsServer(port, token, autoreconnect); }; /** * Disconnect from the running Microsoft Teams process. * Ends current connection and/or ends any ongoing reconnection sequence.
Ein weiterer Abschnitt lässt die APIs erahnen:
... TeamsMeetingController.prototype.toggleMuteCall = function () { this.sendMeetingActionRequestToTeams(\"toggle-mute\" /* ToggleMute */); }; TeamsMeetingController.prototype.toggleVideo = function () { this.sendMeetingActionRequestToTeams(\"toggle-video\" /* ToggleVideo */); }; TeamsMeetingController.prototype.toggleHand = function () { this.sendMeetingActionRequestToTeams(\"toggle-hand\" /* ToggleHand */); }; ...
Auch der Windows Ressource Monitor verrät den Port.
Interessant fand ich daran aber, dass der Firewall-Status nicht eingeschränkt ist und die Adresse "offen" ist. Damit sollte der Port auch über das Netzwerk erreichbar sein. Also habe ich eine Verbindung von eine anderen System auf den Port versucht und sie kam zustande!
Damit ist natürlich noch nicht die Tür offen, denn der Client muss sich schon noch per Token authentifizieren aber die Übertragung scheint unverschlüsselt zu sein. Zudem steht das Token ebenfalls unverschlüsselt in der Teams Konfiguration
Auszug aus %appdata%\Microsoft\Teams\storage.json "enableThirdPartyDevicesService":true, "tpdApiTokenString":"ea8d67e8-4693-40d0-b066-7426a1274bc3"
Ein installiertes Streamdeck hinterlegt das Token auch in der Registrierung:
Windows Registry Editor Version 5.00 [HKEY_CURRENT_USER\Software\Elgato Systems GmbH\StreamDeck] "com.microsoft.teamscom.microsoft.teams"="@ByteArray(xxxxxxx)"
Es wäre daher nicht sonderlich schwer für einen Angreifer, das Token in Erfahrung zu bringen und dann über das LAN den Client anzugehen und zumindest zu "stören"
Weitere Links
- Teams Presence und Office IM API
- Overview of third-party apps in Microsoft Teams
https://learn.microsoft.com/en-us/microsoftteams/overview-third-party-apps - Integrate existing third party APIs
https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/add-api-connection?tabs=basic - Microsoft Teams: Support for Stream Deck
to interact with Microsoft Teams within a
meeting
https://www.microsoft.com/de-de/microsoft-365/roadmap?filters=&searchterms=96112 - Business Tools: Microsoft Teams
https://apps.elgato.com/plugins/com.microsoft.teams - Update! Teams-PowerPoint Plugins for
Elgato Stream Deck and Mobile
https://techcommunity.microsoft.com/t5/healthcare-and-life-sciences/update-teams-powerpoint-plugins-for-elgato-stream-deck-and/ba-p/3767650 - There’s a new client-side API for Microsoft Teams!
https://blog.thoughtstuff.co.uk/2023/02/theres-a-new-client-side-api-for-microsoft-teams/ - Microsoft Teams Client API – coming
soon, not ready yet
https://blog.thoughtstuff.co.uk/2023/03/microsoft-teams-client-api-coming-soon-not-ready-yet/ - Microsoft Teams WebSocket API
https://lostdomain.notion.site/Microsoft-Teams-WebSocket-API-5c042838bc3e4731bdfe679e864ab52a - WebSocket sample
https://learn.microsoft.com/en-us/samples/microsoft/windows-universal-samples/websocket/ - Powershell Slack Bot using the Real Time Messaging API
https://wragg.io/powershell-slack-bot-using-the-real-time-messaging-api/ - Setup and first look at the Elgato
Stream Deck Teams Pluggin for Teams meetings
and webinars !
https://ucmart.uk/2023/02/02/setup-and-first-look-at-the-elgato-stream-deck-teams-pluggin-for-teams-meetings-and-webinars/ - Teamsy with Deckboard (free Stream Deck
on mobile)
https://tdalon.blogspot.com/2023/02/teamsy-with-deckboard.html - https://www.epochconverter.com/