PRTG – Office 365 Status überwachen

PRTG – Office 365 Status überwachen

Office 365 mit PRTG überwachenMit 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. Man lege die Dateien an folgenden Orten ab:

Datei Ort Beschreibung
Get-Office365Status.ps1 <PRTG Installationspfad>\Custom Sensors\EXEXML Das 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\custom Das 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.

Update: Windows markiert heruntergeladene Dateien aus dem Internet als potentiell unsicher. Dadurch wird die Ausführung in PowerShell erst einmal unterbunden. Das Skript muss also zuvor entweder per PowerShell oder über die Eigenschaften der Datei im Explorer freigeschaltet werden.

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:

Einstellung Beschreibung
Sensor Name Der Anzeigename des Sensort, etwa „Office 365 Tenant Health“
EXE/Script Hier muss das Skript „Get-Office365Status.ps1“ ausgewählt werden
Parameters Hier 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

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  O365Mon01
Die entsprechende (einzige) Instanz des Azure AD auswählen  O365Mon02
Im ausgewählten AAD Menüpunkt „Anwendungen“ wählen  O365Mon03
Neue Anwendung hinzufügen  O365Mon04
Eigene Anwendung auswählen  O365Mon05
Einen Namen zur Identifikation der Applikation eintragen  O365Mon06
In den Eigenschaften eine URL und APP-ID-URI eintragen. Diese wird nicht wieder verwendet, der Wert ist also egal.

Hier sollte etwas, wie „https://office365health.mytenant.onmicrosoft.com“ genutzt werden, entsprechend den Tenant Namen noch anpassen.

 O365Mon07
Die neu erstellte Applikation konfigurieren  O365Mon08
Hier wird die erste wichtige Information angezeigt:

! ClientID

 O365Mon09
Einen neuen Schlüssel mit entsprechender Gültigkeit erstellen lassen. Der Schlüsselwert (=ClientSecret) wird erst nach dem Speichern angezeigt.  O365Mon10
Speichern  O365Mon12
Den Schlüssel hier kopieren und speichern. Danach kann der Schlüssel nicht wieder angezeigt werden! Der Schlüssel wird für folgenden Parameter verwendet:

! ClientSecret

 O365Mon13
Nun fehlt noch die Berechtigung, auf die Office 365 Service Informationen zuzugreifen. Dazu muss eine Anwendungsberechtigung hinzugefügt werden  O365Mon14
Die „Office 365 Management API“ auswählen und das „+“ anklicken. Danach mit dem Häkchen unten rechts den Dialog bestätigen  O365Mon15
Unter Anwendungsberechtigung den Eintrag „Read service health information for your organization“ auswählen und speichern.  O365Mon16
In der URL Zeile der Website, in der wir gerade arbeiten (Azure AD Verwaltung) wird nun auch der folgende Wert angezeigt:

! TenantIdentifier

Er wird als Teil der URL angezeigt und ist im GUID Format.

 O365Mon17

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:
  • 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

Viel Spaß beim Monitoren.

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

18 Gedanken zu “PRTG – Office 365 Status überwachen

  1. Hallo! Erst einmal vielen Dank für das Skript, echt genial! Ich habe noch eine kleine Verbesserung die in meiner eigenen Infrastruktur aufgetreten ist. PRTG läuft bei uns mit einem eigenen Service-User. Hat man sich noch nie mit diesem User auf dem PRTG-Server angemeldet und den Internet Explorer gestartet, so meckert das Skript mit der folgenden Meldung:

    Der Antwortinhalt kann nicht analysiert werden, da das Internet Explorer-Modul nicht verfügbar ist,
    oder die Konfiguration beim ersten Start von Internet Explorer ist nicht abgeschlossen. Geben Sie den
    UseBasicParsing-Parameter an, und wiederholen Sie den Vorgang.

    2 Lösungsmöglichkeiten:
    –> 1. Mit dem User anmelden auf dem PRTG-Server und der Internet Explorer 1x starten (eher nicht empfohlen)
    –> 2. Im PS-Skript bei Zeile 109 (Invoke-Webrequest) den Parameter -UseBasicParsing anfügen. Fertig.

    • Hallo PlayOrDie. Danke für das detaillierte Feedback. Ich habe die vorgeschlagene Änderung in das Skript eingebaut, konnte es jetzt noch nicht testen, werde ich aber demnächst noch nachholen.

  2. Hallo sorry,

    ich nochmal weil ich vergessen habe etwas zu erwähnen. Ich der „lookup“ Datei hat sich auch noch einen Fehler eingeschlichen. Die „ID“ ist von „bechtle.office365.state“ in „custom.office365.state“ umzubenennen. Danach die Lookups in den Administrativen Werkzeugen neuladen und dann klappts auch 🙂

    • Na ja, da war ich mal wieder mit mir selbst uneins, wie ich das benennen soll. Habe ich aber auch angepasst. Danke.

  3. Hello Marc,

    I tried your script, but my output is:
    What is my mistake?

    Ollie

    Exchange Online
    11
    custom.office365.state

    Skype for Business
    5
    custom.office365.state

    Mobile Device Management for Office 365
    0
    custom.office365.state

    Identity Service
    0
    custom.office365.state

    Office 365 Portal
    0
    custom.office365.state

    Office Subscription
    0
    custom.office365.state

    Planner
    0
    custom.office365.state

    Power BI
    0
    custom.office365.state

    Rights Management Service
    0
    custom.office365.state

    SharePoint Online
    0
    custom.office365.state

    Sway
    0
    custom.office365.state

    Yammer Enterprise
    9
    custom.office365.state

    • Thanks Ollie! Good to see, that it works for you. After adding a lookup file, PRTG needs to reload the lookup repository. That can either be done by restarting the core service (as you did), or by hitting „Load Lookups“ within PRTG, found under Setup/System Administration/Administrative Tools. I’ll add that to the description, so thanks for the hint there.

    • Well now you got me … 😉
      I just took a look and thought by myself: „That doesn’t look too complicated…“, and now you got me sitting here and scripting it.
      Great idea, rather easy to do (already got it up and running), just give me a couple of days for finetuning and testing. I’ll post a new blog entry, as it is finished. Stay tuned, we’ll have it by the weekend, I hope.

  4. Hi Marc,
    thanks for sharing this script. In addition to your great manual I like to add that I had to execute the following Powershell commands on Windows Server 2012R2 to be able to overcome authorization errors:

    Unblock-File -Path „C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML\Get-Office365Status.ps1“

    Unblock-File -Path „C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML\Get-PRTGO365Licenses.ps1“

  5. Hallo erstmal und Vielen Dank für das Script.
    Habe das Ganze wie beschrieben eingerichtet und habe immer den Fehler „Error retrieving data“ erhalten.
    Erst als ich der neu erstellen Applikation expliziten Zugriff auf die Berechtigungen gegeben habe, hat die Anfrage funktioniert.
    Der Zugriff für die neue Applikation ist in diesem MS Artikel beschrieben:
    https://msdn.microsoft.com/office-365/get-started-with-office-365-management-apis

    „Office 365 tenant admin consent

    Now that your application is configured with the permissions it needs to use the Office 365 Management APIs, a tenant admin must explicitly grant your application these permissions in order to access their tenant’s data by using the APIs. To grant consent, the tenant admin must log in to Azure AD, using the following specially constructed URL, where they can review your application’s requested permissions. This step is not required when using the APIs to access data from your own tenant.

    https://login.windows.net/common/oauth2/authorize?response_type=code&resource=https%3A%2F%2Fmanage.office.com&client_id={your_client_id}&redirect_uri={your_redirect_url }“

    War dieses Vorgehen bei Erstellung des Scripts noch nicht nötig?
    Können Sie Ihre Anleitung entsprechend anpassen für zukünftige Einrichtungen?
    Falls dies bereits irgendwo enthalten sein sollte und ich es überlesen habe, bitte ich um Entschuldigung.

    • Hallo Philipp,

      das explizite Setzen der Berechtigungen habe ich eigentlich in der Anleitung drin … steht in der Tabelle unter „Nun fehlt noch die Berechtigung, auf die Office 365 Service Informationen zuzugreifen…“. Hast du diese Schritte ausgeführt, oder hat sich diese Option in Zwischenzeit geändert? Azure ändert sich doch relativ oft, deshalb kann es auch gut sein, dass auch hier etwas passiert ist. Vielleicht kannst du das noch einmal prüfen und Feedback geben?

      Gruß,
      Marc

  6. Hello, Thanks for this nice post! I’m trying to implement in our infrastructure but the sensor is not working. I get the followinf error in PRTG : XML: The returned XML does not match the expected schema. (code: PE233) — JSON: The returned JSON does not match the expected structure (Invalid JSON.). (code: PE231)

    In the sensor settings, when you have to specify your parameters, I presume the the format is : -ClientID=XXXX -ClientSecret=XXX -TenantIdentifier=XXX

    Another question, I can’t see in the sensor settings where we specify the lookup file to use…

    Thanks for your help!

    Fred

  7. The command line mention by Frank solved my issue: Unblock-File -Path „C:\Program Files (x86)\PRTG Network Monitor\Custom Sensors\EXEXML\Get-Office365Status.ps1“

    Thanks a lot for this!

    • Perfect, so your lookup should work now, too. You needn’t specify the file, as it is done by the sensor itself.

      I had a sentence about the blocking of downloaded script files in another post, just copied it over to help future readers 🙂

      Thanks for your feedback.

  8. Hallo,
    ich bekomme leider nur ein „Error authenticating“.

    PRTG ist ziemlich neu für mich und ich denke es liegt an der Eingabe der Parameter.

    -ClientID:“anfangleerzeichenrest“ -ClientSecret:“XXX“ -TenantIdentifier:“XXX“

    Bei der ClientID ist ein Leerzeichen zwischen den „Nummern“. Evtl. hier der Fehler?

    Könntet Ihr mir bitte helfen?
    Danke!

    mfg
    Alex

    • Hallo Alex,

      eigentlich sollten in der ClientId (meiner Meinung nach) keine Leerzeichen enthalten sein. In den PRTG Parametern kannst du das aber mit einfachen Anführungszeichen durchaus machen, wie in folgendem Beispiel zu sehen:

      -ClientId '000a0000-aa00-0000-a0a0-aa00a0aa0000' -ClientSecret 'xxxxxx11111xxx11xxxxx111xx11=' -TenantIdentifier '000b0000-bb00-0000-b0b0-bb00b0bb0000'

      So setze ich die Parameter in meinen Installationen und da funktioniert das einwandfrei. Und da hatte ich bisher auch noch keine Leerzeichen in den Parametern, technisch funktionieren würde es so allerdings.

      Gruß,
      Marc

Schreibe einen Kommentar

%d Bloggern gefällt das: