📋 Outlook Add-In (neu): Zentrale Konfiguration via PowerShell

Diese Anleitung beschreibt die automatisierte Einrichtung des Outlook Add-Ins für Administratoren mithilfe eines PowerShell-Skripts zur zentralen Konfiguration von Server-Einstellungen für Benutzer und Gruppen.

Schritt 1 – Download und Entpacken der Dateien

Laden Sie im ersten Schritt das erforderliche Setup-Paket über den folgenden Link herunter:

Hier klicken: Setup-Skript für das Outlook Add-In herunterladen

Speichern Sie die heruntergeladene ZIP-Datei auf Ihrem Computer, zum Beispiel in Ihrem Ordner Downloads. Entpacken Sie die ZIP-Datei anschließend vollständig (Rechtsklick auf die Datei und "Alle extrahieren" wählen).

Öffnen Sie nun den gerade entpackten Ordner. Darin sehen Sie einen Ordner namens setup. Öffnen Sie diesen setup-Ordner.

Unter einem Pfad wie beispielsweise C:\Users\IhrBenutzername\Downloads\setup\setup müssen nun genau diese drei Dateien liegen:

1. config.json (die Konfigurationsdatei, die Sie anpassen müssen)

2. README.md (eine englische Textanleitung)

3. setup.ps1 (das eigentliche Skript, das später ausgeführt wird)

Schritt 2 – Voraussetzungen prüfen

Stellen Sie sicher, dass Ihr System über Windows mit PowerShell 5.1 oder PowerShell 7+ verfügt. Ein Internetzugang ist zwingend erforderlich, um das benötigte Modul Microsoft.Graph automatisch zu installieren.

Sie benötigen zudem ein Microsoft 365 Administratorkonto mit den Rollen Globaler Administrator oder Benutzer-Administrator. Falls Sie das Outlook Add-In an ganze Gruppen verteilen möchten, ist zusätzlich die Rolle Gruppen-Administrator erforderlich.

Schritt 3 – Konfigurationsdatei anpassen

Öffnen Sie die Datei config.json aus Ihrem setup-Ordner mit einem einfachen Texteditor (zum Beispiel dem vorinstallierten Windows Editor/Notepad) und passen Sie die Werte an Ihre Umgebung an.

Zuweisung der Server-URL

Geben Sie unter ftapiUrl die URL Ihres FTAPI-Servers an, beispielsweise https://ihr-server.ftapi.com.

"ExtensionSettings": {    "ftapiUrl": "https://ihr-server.ftapi.com"}

Benutzer und Gruppen definieren

Sie können das Add-In entweder für einzelne Benutzer, für ganze Gruppen oder für beides gleichzeitig konfigurieren:

Tragen Sie in der UserList die Object IDs einzelner Benutzer ein – oder lassen Sie das Feld weg, wenn Sie ausschließlich Gruppen verwenden.
Tragen Sie in der GroupList die Object IDs von Microsoft 365 Gruppen ein, deren Mitglieder konfiguriert werden sollen – oder lassen Sie das Feld weg, wenn Sie ausschließlich Einzelbenutzer verwenden.

Wichtig: Verwenden Sie ausschließlich die Object ID (eine lange Zahlen- und Buchstabenkombination), nicht den Anzeigenamen oder die E-Mail-Adresse. Diese IDs finden Sie im Microsoft Entra Admin Center unter Identity → Users bzw. Identity → Groups.

Schritt 4 – Ausführung des Setups in der PowerShell

Öffnen Sie eine PowerShell-Konsole exakt in dem Verzeichnis, in dem Ihre entpackten Dateien liegen. Navigieren Sie in der PowerShell also in den Pfad, der die Datei setup.ps1 enthält (zum Beispiel C:\Users\IhrBenutzername\Downloads\setup\setup).

Führen Sie das Skript mit genau folgendem Befehl aus:

.\setup.ps1

Falls eine rote Fehlermeldung zur Ausführungsrichtlinie erscheint, führen Sie vorab diesen Befehl aus und bestätigen Sie mit Enter:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Bei der allerersten Ausführung wird das Modul Microsoft.Graph automatisch installiert, was einige Minuten dauern kann. Bestätigen Sie die Sicherheitsabfrage zur PSGallery (PowerShell Gallery) unbedingt mit der Taste Y.

Wichtig: Aus dem Internet heruntergeladene Dateien werden von Windows blockiert (Mark of the Web / Zone.Identifier). Der Befehl Set-ExecutionPolicy allein hebt diese Blockierung nicht auf. RemoteSigned verlangt bei unsignierten Skripten aus dem Internet weiterhin, dass die Blockierung zuvor entfernt wird. Lässt sich setup.ps1 trotz gesetzter Ausführungsrichtlinie nicht starten, entfernen Sie die Blockierung mit einem der folgenden Wege.

Blockierung der ZIP-Datei vor dem Entpacken entfernen (empfohlen)

Klicken Sie mit der rechten Maustaste auf die heruntergeladene ZIP-Datei und wählen Sie Eigenschaften. Aktivieren Sie unten die Option Zulassen (englisch Unblock) und bestätigen Sie mit OK. Entpacken Sie die Datei erst danach. So werden alle enthaltenen Dateien ohne Blockierung entpackt.

Bereits entpackte Dateien per PowerShell entsperren

Sind die Dateien bereits entpackt, können Sie die Blockierung per PowerShell entfernen. Führen Sie den folgenden Befehl im setup-Ordner aus, um alle enthaltenen Dateien zu entsperren:

Get-ChildItem -Path . -Recurse | Unblock-File

Für eine einzelne Datei genügt:

Unblock-File -Path .\setup.ps1

Skriptinhalt manuell übertragen (letzter Ausweg)

Falls die vorherigen Wege nicht möglich sind, öffnen Sie die Datei setup.ps1 in einem Texteditor, kopieren Sie den vollständigen Inhalt und fügen Sie ihn in eine selbst erstellte lokale Datei setup.ps1 ein. Lokal erstellte Dateien unterliegen nicht der Blockierung und lassen sich direkt ausführen.

Schritt 5 – Überprüfung der Ergebnisse

Prüfen Sie am Ende die Textausgabe in der PowerShell. Bei einer erfolgreichen Einrichtung sehen Sie Meldungen wie Successfully created extension oder Successfully updated existing extension neben den IDs der Nutzer.

Zur weiteren Verifikation können Sie die Konfiguration direkt über den Microsoft Graph Explorer prüfen:

Öffnen Sie https://developer.microsoft.com/en-us/graph/graph-explorer und melden Sie sich mit Ihrem Administratorkonto an.
Führen Sie folgende Abfrage aus (ersetzen Sie <userId> durch die Object ID des Benutzers):

GET https://graph.microsoft.com/v1.0/users/<userId>/extensions/com.ftapi.settings

Die Antwort sollte den Eintrag "ftapiUrl" mit Ihrer konfigurierten Server-URL enthalten.

Einmalige Anmeldung im Add-In

Nach erfolgreicher zentraler Konfiguration ist noch eine einmalige Anmeldung erforderlich. Betroffene Nutzer müssen sich einmalig im Outlook Add-In anmelden, damit es aktiv wird. Ohne diese einmalige Anmeldung bleibt das Add-In trotz korrekt geschriebener Konfiguration inaktiv.

Skript erneut ausführen

Das Skript kann jederzeit erneut ausgeführt werden – zum Beispiel um neue Benutzer oder Gruppen hinzuzufügen oder die ftapiUrl nach einer Server-Migration zu aktualisieren. Bereits vorhandene Konfigurationen werden dabei aktualisiert, es entstehen keine Duplikate.

Fehlerbehebung

Das Skript lässt sich nicht ausführen / wird blockiert

Aus dem Internet heruntergeladene Dateien werden von Windows blockiert (Mark of the Web). Der Befehl Set-ExecutionPolicy allein hebt diese Blockierung nicht auf. Entfernen Sie die Blockierung wie in Schritt 4 beschrieben: entweder per Rechtsklick auf die ZIP-Datei über Eigenschaften > Zulassen vor dem Entpacken, oder per Unblock-File in der PowerShell. Als letzter Ausweg lässt sich der Skriptinhalt in eine selbst erstellte lokale setup.ps1 übertragen.

Die Modul-Installation schlägt fehl

Prüfen Sie Ihre Internetverbindung. Sie können die PSGallery manuell als vertrauenswürdig markieren, indem Sie diesen Befehl ausführen:

Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

Authentifizierung schlägt fehl oder Zugriff wird verweigert

Stellen Sie sicher, dass das verwendete Konto die erforderlichen Rollen besitzt. Prüfen Sie außerdem, ob Conditional Access Policies die Anmeldung von Ihrem Gerät oder Standort einschränken, oder ob Ihr Tenant die App-Zustimmung bzw. den Zugriff auf die Graph API beschränkt.

Gruppenmitglieder werden nicht gefunden

Überprüfen Sie, ob die Group Object ID in der Datei config.json korrekt hinterlegt ist und Sie beim Kopieren keine versehentlichen Leerzeichen eingefügt haben. Stellen Sie sicher, dass Ihr Admin-Konto die Berechtigung Group.Read.All besitzt und die Gruppe nicht gelöscht wurde.

„Failed to process user"

Prüfen Sie, ob die User Object ID in der config.json korrekt ist. Die genaue Fehlermeldung in der PowerShell-Ausgabe gibt weiteren Aufschluss über die Ursache.

Das Add-In übernimmt die Server-URL nicht

Vergewissern Sie sich zunächst, dass die Extension erfolgreich geschrieben wurde (siehe Schritt 5). Bitten Sie den betroffenen Benutzer, Outlook neu zu starten. Stellen Sie außerdem sicher, dass die unter ftapiUrl eingetragene URL aus dem Netzwerk des Benutzers erreichbar ist.