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.

https://www.youtube.com/watch?v=h0mUrJ7BSOM

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.

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

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:

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
https://www.youtube.com/watch?v=h0mUrJ7BSOM

Steamdeck Plugin (Am 3.2.2023 erreichbar, ab 4.2.2023 nicht mehr)
https://apps.elgato.com/Plugins/com.microsoft.teams

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.

Es gibt auch einige Bastelprojekte, die durchaus interessant sind, z.B.

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. 

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:

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

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