Outlook REST API für Mail, Kontakte, Termine

Auf der MEC2014 wurde ein neuer Weg für den Zugriff auf Postfachinhalte jeder Art vorgestellt. Ich gehe davon aus, dass dieser Zugriff auch für Exchange On-Prem bald zur Verfügung stehen wird. Auslöser ist sicher, dass in der Cloud keine Zugriffe per MAPI/RPC oder CDO mehr möglich sind, und RPC/HTTP einen größeren Overhead hat. Gefragt sind also einfache Wege auf die Informationen zuzugreifen und EWS ist vielleicht nicht einfach genug. Da sind REST und JSON die neuen Schlagworte. Und der Zugriff ist so schlank, dass man sogar einen RaspberryPI oder Arduino dafür als Client einbinden kann.

End of Live?

Am 4. März hat Microsoft über verschiedene Kanäle das "Ende" von GPAPH/REST für On-Premises Postfächer verkündet. Siehe auch Graph und Exchange On-Premises. Ich gehe davon aus, dass damit auch die On-Premises-Version der REST-API vermutlich nicht mehr weiter geführt wird oder zumindest unklar und damit keine stabile Option mehr ist.

Wer automatisiert mit Exchange On-Premises arbeitet, sollte daher weiter die Exchange Web Services (EWS) nutzen. 

Outlook REST API v2.0 Deprecation Notice (30. Nov 2022)
https://developer.microsoft.com/en-us/office/blogs/outlook-rest-api-v2-0-deprecation-notice/
Achtung: Diese API ist nicht für den öffentlichen Zugriff gedacht sondern wird von Graph in der Cloud als Proxy angesprochen.

Outlook REST API v2.0 and Beta deprecation update (23. Nov 2022)
https://techcommunity.microsoft.com/t5/exchange-team-blog/outlook-rest-api-v2-0-and-beta-deprecation-update/ba-p/3682745
Verschoben aber soll 2023 kommen mit 6 Monaten Vorankündigung. Wir sind also zumindest im Sommer 2023

Interessante Information in einem Twitter-Post von Ross

Shared mailboxes are coming real soon to @Outlook mobile. Requires O365 accounts. #outlook #ems
https://twitter.com/RossSmithIV/status/1136742431830024203

Wenn ich den Text genau lese, dann ist es der Verzicht auf REST, EWS und ActiveSync, warum diese Funktion nur mit Exchange Online funktioniert. Das kann man aber auch so interpretieren, dass REST auch mit Exchange On-Premises ganz legitim genutzt werden kann. Auch in der Beschreibung zu Microsoft Graph befindet sich eine interessante Aussage:

Behind the scenes, when Microsoft Graph identifies that a REST API call is attempting to access an On-Premises mailbox in a hybrid deployment, it proxies the REST request to an On-Premises REST endpoint which then processes the request. This discovery makes accessing the REST API possible.
Quelle: https://docs.microsoft.com/de-de/graph/hybrid-rest-support

Damit sollte klar sein, dass auch das On-Premises-Verzeichnis "/REST" sogar aktiv von Graph aus der Cloud angesprochen wird.

Basis

Die meisten Lösungen erfordern nur wenige Basisfunktionen, die möglichst auf jedem Client zur Verfügung stehen sollten. HTTP bzw. HTTPS ist das präferierte Protokoll und die Parameter werden einfach per Parameter übergeben. Und dann könnte das wie folgt aussehen:

Die Hostnamen in den URLs hier sind keine realen Adressen und funktionieren natürlich nicht und selbst wenn ist natürlich eine Authentifizierung erforderlich.

Sie sehen schon, wie einfach so eine Anfrage ist, wenn der Client sich erst einmal "authentifizieren" und die Rückantworten interpretieren kann. Die API lässt sich für den Zugriff auf die eigene Mailbox als auch auf eine andere Mailbox nutzen. Man muss nur den Pfad entsprechend anpassen:

Auf der MSDN gibt es weitergehende Artikel:

Auf dem Server

Wie Microsoft die Rest-API auf Office 365 umgesetzt hat, kann man leider nicht einsehen. Aber da die Rest API mittlerweile auch auf dem "On-Prem-Server" vorhanden ist, können Sie hier natürlich schauen.

Das virtuelle Verzeichnis /API ist mit Exchange 2016 CU3 erstmals im IIS-Manager aufgetaucht. Das Verzeichnis "/REST" war aber schon seit CU1 in den Installationsquellen aber wurde wohl vorher noch nicht eingebunden.

Das virtuelle Verzeichnis "/API", gibt es sowohl auf dem Frontend Server als auch auf dem Backend:

  • Virtuelles Verzeichnis /API auf dem Frontend
  • Virtuelles Verzeichnis auf dem Backend

Hier noch ein paar weitere Details:

  Frontend Backend
Basisverzeichniss

C:\Program Files\Microsoft\Exchange Server\V15\FrontEnd\HttpProxy\Rest

C:\Program Files\Microsoft\Exchange Server\V15\ClientAccess\rest
ApplicationPool

MSExchangeRestFrontEndAppPool

MSExchangeRestAppPool
Authentication

Anonymous
Windows Authentication

Anonymous
Windows Authentication
SSL Setting

Required, Ignore Client Cert

Required, Ignore Client Cert

Verwaltung per PowerShell

Auch wenn es seit CU3 die virtuellen Verzeichnisse im IIS gibt, so liefern die entsprechenden PowerShell Commandlets auch mit CU3 noch keine Rückgabe.

[PS] C:\Windows\system32>get-command *-RestVirtualDirectory

CommandType     Name
-----------     ----
Function        Get-RestVirtualDirectory
Function        New-RestVirtualDirectory
Function        Remove-RestVirtualDirectory
Function        Set-RestVirtualDirectory

Das virtuelle Verzeichnis ist schon vorhanden aber nicht als "RestVirtualDirectory" gelistet. Ich bin gespannt, ab wann diese Funktion "offiziell" vorhanden ist.

Autodiscover

Mit Autodiscover V2 können Sie sehr einfach ein Einstiegspunkt per REST auf eine Mailbox ermitteln.

Invoke-RestMethod -Uri ‘https://autodiscover.msxfaq.de/autodiscover/autodiscover.json?Email=User@msxfaq.de&Protocol=REST’

Protocol Url
-------- ---
REST     https://outlook.msxfaq.de/api

Authentifizierung

In der Office 365 Umgebung geht das natürlich nicht einfach per "Benutzername/Kennwort", denn in der Cloud sind andere Verfahren, z.B. ADFS, üblich. Ihr Client wird sich daher beim Zugriff einen 401-Fehler einfangen, in dem Der Weg zur Authentifizierungsserver hinterlegt ist. für den Einsatz On-Prem hingegen wird man die Anmeldung gleich als HTTP-Anmeldung mit übergeben.

Beispiele folgen später.

Rückmeldung

Abhängig von Programm, das sie nutzen, sind die Rückgaben bereits aufbereitet. Wer z.B. mit der PowerShell ein "Invoke-RESTMethod" nutzt, bekommt ein schöne PowerShell Objekt zurück, welches sehr einfach ausgewertet werden kann.

Beispiele folgen später

Offen: App Passwort

So schön die Anmeldung per Credentials oder per ADFS-Tokens ist, so risikobehaftet ist dies natürlich insbesondere für Dienste, die auf Postfächer zugreifen wollen. Wie schon auf App Password beschrieben, fehlt mir auch hier die Option ein sehr langes Kennwort für eine Applikation zu hinterlegen, welches dann auch nur für diesen Zugriff genutzt werden kann.

Beispiele folgen später.

Offen: Impersonation

Eine der großen Stärken von EWS ist die Möglichkeit der Impersonation, d.h. sich als anderer Benutzer auszugeben. Ich bin gespannt ob und wann das auch per REST möglich sein wird.

Weitere Links