Dieses Skript wird nicht weiter aktualisiert

Update 27.02.2022: Da mich immer wieder Meldungen erreichen, dass das Skript in Zwischenzeit nicht mehr funktioniert: PRTG hat die Funktion dieses Skripts in Zwischenzeit in den eigenen Funktionsumfang aufgenommen, deshalb werde ich dieses hier nicht mehr aktualisieren. Bitte stellt eure Sensoren entsprechend um. Folgende Sensoren gibt es aktuell für Microsoft 365 Services:

Update 22.12.2019: In einigen Konstellationen ist für TLS 1.2 in Windows eine Anpassung der Registry notwendig. Wenn das bei euch der Fall ist, setzt die Keys auf dem Beitrag  Enable TLS 1.2 in Windows (Zumindest Keys 1 & 3).

Update 14.12.2019: Und jetzt habe ich auch den Link zum Github Repository (https://github.com/debold/PRTG-O365Monitoring), wo das Skript heruntergeladen werden kann, hinzugefügt.

Update 13.12.2019: Habe das Skript aktualisiert, so dass TLS 1.2 forciert wird. Bitte mal testen!

Update 11.12.2019: Heute hatte ich mehrere Meldungen über Fehler beim Abruf der Daten von Office365. Ich habe die Version auf Github aktualisiert, so dass genauere Fehlermeldungen ausgegeben werden – bitte die neue Version verwenden. Damit sollte man der Ursache einfacher auf die Spur kommen. Und: Ich überarbeite die Seite die nächsten Tage mal, die Oberfläche von AzureAD hat sich so geändert, dass mal wieder kaum ein Screenshot noch stimmt …

Update 01.10.2018: Habe ein Beispiel für die Parameter des Skripts hinzugefügt, der Abschnitt war ungenau.

Update 04.02.2018: So, der Artikel ist nun mit den Screenshots des neuen Admin-Portals aktualisiert und die Freischaltung der App wurde mit aufgenommen. Falls ihr noch was findet, was nicht funktioniert, hinterlasst bitte einen Kommentar.

Office 365 mit PRTG überwachen

Update 28.01.2018: Der Artikel ist nicht mehr ganz aktuell und muss auf das neue Admin-Portal angepasst werden. Die Schritte gehen soweit noch, allerdings scheint eine Authentifizierung der App erforderlich zu sein. In den Kommentaren hat Daniel (Danke dafür) beschrieben, wie das geht. Ich werde den Artikel in den nächsten Wochen aktualisieren … bitte noch etwas Geduld … 

Mit PRTG von Paessler lassen sich schnell und einfach kleine bis mittlere Netzwerke überwachen (kostenlose Testversion bzw. 100er Freeware Version gibt es hier). Vom Ping über WMI, SNMP bis hin zu eigenen Skripten kann über viele Wege das Monitoring von Geräten und Diensten geschehen. Nun kam schon häufiger die Frage auf, wie man denn Office 365 überwachen kann. Da es sich hier um eine Sammlung verschiedener Dienste handelt, die auf tausenden von Servern gehostet werden – zu denen wir natürlich nicht den passenden Zugriff haben – ist das Ganze nicht trivial. Zum Glück stellt Microsoft eine API bereit, mit deren Hilfe wir wunderbar den Status der abonnierten Dienste eines Tenants auslesen können. Nachfolgend wird beschrieben, wie eben diese Überwachung in PRTG eingerichtet werden kann.

Die Einrichtung in PRTG ist denkbar einfach. Man nehme die nachfolgende ZIP Datei (PRTG_O365Monitoring), in der ein Power Shell Skript und eine .OVL Datei enthalten sind. Ladet euch die aktuelle Version des Skripts von Github herunter und legt die Dateien an folgenden Orten ab:

DateiOrtBeschreibung
Get-Office365Status.ps1<PRTG Installationspfad>\Custom Sensors\EXEXMLDas ist das Power Shell Skript, das die Anfrage an Office 365 macht und das Ergebnis als XML an PRTG zurück liefert.
custom.office365.state.ovl<PRTG Installationspfad>\lookups\customDas ist eine Lookup Definition, die die numerischen Rückgabewerte des Skripts in verständliche Status umwandelt und in PRTG anzeigt.

 

Wichtig: Die Lookup Definitionen werden nur durch einen Neustart des Core Service, oder über den Menüpunkt Setup/System Administration/Administrative Tools/Load Lookups eingelesen und angewandt.

Nun erstellt man einen neuen Sensor vom Typ “EXE/Skript Advanced” auf einem beliebigen, passenden Gerät (es werden keine Geräteeigenschaften verwendet). Folgende Einstellungen sind im Sensor noch zu machen:

EinstellungBeschreibung
Sensor NameDer Anzeigename des Sensort, etwa “Office 365 Tenant Health”
EXE/ScriptHier muss das Skript “Get-Office365Status.ps1” ausgewählt werden
ParametersHier müssen 3 tenantspezifische Infos rein. Wie man an diese Infos kommt, ist weiter unten erklärt.

 

ClientID – ID der Azure “Anwendung” mit deren Hilfe wir die Informationen auslesen
ClientSecret – Das dazu passende “Kennwort”
TenantIdentifier – Die GUID des Office 365 Tenants

Das sollte dann etwa so aussehen:

-ClientID Meine_Client_ID -ClientSecret Mein_Kennwort -TenantIdentifier Meine_Tenant_ID

Der weitaus aufwändigere Teil (bis auf das Erstellen des Skripts – aber das habe ja ich übernommen) ist es, Office 365 bzw. Azure dazu zu überreden, uns doch seine Infos preis zugeben. Die folgende Anleitung zeigt alle notwendigen Schritte:

Login auf https://portal.office.com und Aufruf von Azure AD Azure AD
Hier den Punkt “App-Registrierungen” auswählen App-Registrierungen
Neue Anwendung hinzufügen App-Registrierungen
Nun die notwendigen Informationen für die Erstellung der App-Registrierung eingeben. Der Name dient nur der Identifikation des Service im Portal, darf also frei gewählt werden.

 

Als Anwendungstyp muss Web-App/API ausgewählt werden.

Die Anmelde-URL muss auch gefüllt werden, muss allerdings nicht auf eine reale Adresse verweisen. Ich benutze dafür in der Regel https://office365health.mytenant.onmicrosoft.com, wobei mytenant durch den eigenen Tenant Namen ersetzt werden muss.

 Erstellen
Nachdem die App-Registrierung fertig gestellt wurde, wird in der Übersicht die Anwendungs-ID angezeigt.

 

Diese verwenden wir im Skripts als: ! ClientID

 App-Registrierungen
Nun klickt man die neu angelegte App-Registrierung an und öffnet die Einstellungen.Einstellungen
Unter dem Punkt Schlüssel muss nun ein neuer Sicherheitsschlüssel erstellt werden, der für die Authentifizierung gegenüber Azure genutzt wird. Nach der Eingabe einer Beschreibung und des Ablaufzeitraums kann der Eintrag gespeichert werden.

 

Achtung: Nach dem Speichern wird der Schlüsselwert ein einziges Mal angezeigt. Verlässt man diese Seite, kann der Schlüssel nicht wieder angezeigt werden und es muss ein neuer erstellt werden.

Der Schlüssel wird hier verwendet als: ! ClientSecret

Schlüssel
Nun fehlt noch die Berechtigung, auf die Office 365 Service Informationen zuzugreifen. Dazu muss eine neue Berechtigung hinzugefügt werden.API
Als API wird Office 365 Management APIs gewählt, die erforderliche Berechtigung, die wir benötigen, nennt sich Read service health information for your organization.Zugriff aktivieren
Nun benötigen wir noch die ID des Azure AD. Diese finden sich in den Eigenschaften des Azure AD. Der richtige Eintrag ist dort unter Verzeichnis-ID zu finden.

 

Im Skript wird die ID verwendet als: ! TenantIdentifier

Eigenschaften
Nun fehlt noch ein wichtiger Punkt: Die neue App muss einmalig authorisiert werden. Dazu muss eine spezielle URL aufgerufen und die Abfrage dort bestätigt werden:

 

https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id=ClientID

Dabei muss ClientID durch die oben erstellte ID ersetzt werden.

Achtung: Nach der Abfrage wird man ggf. auf seine Redirect-URL weitergeleitet. Diese mussten wir oben angeben, allerdings existiert diese Seite ja gar nicht. Damit kann eine 404-Fehlerseite erscheinen – das ist in Ordnung! Die Authorisierung funktioniert trotzdem.

 App-Authorisierung

Ein paar wichtige Infos zum Betrieb des Skripts:

  • Auf der PRTG Probe muss min. Power Shell 3.0 oder höher installiert sein. Mit Windows Server 2008 R2 wurde Version 2 ausgeliefert, kann aber durch Installation des Windows Management Framework (aktuell Version 5) nachgerüstet werden
  • Die Power Shell Execution Policy auf der Probe sollte auf “RemoteSigned” stehen. Dazu den folgenden Befehl auf der Power Shell 32 Bit ausführen:
    Set-ExecutionPolicy RemoteSigned -Force
  • Kommt immer noch eine Meldung, dass das Skript nicht signiert wurde, dann auch wirklich die 32 Bit Version der Power Shell ausführen. Ja, die heißt auch so 🙂
  • Nach 2 Jahren ist die Gültigkeit der Anwendungsdaten hinfällig, dann muss ein neues ClientSecret erstellt werden

Und falls ihr den Link zum Download nicht gefunden habt: Die aktuelle Version findet ihr immer auf Github unter https://github.com/debold/PRTG-O365Monitoring.

Viel Spaß beim Monitoren.

Für Fragen, Probleme oder Anregungen gerne einen Kommentar hinterlassen.