Eigene Microsoft App-Registrierung

Kunden, die teamspace selbst hosten oder das Standardhosting verwenden, können bei der Anbindung von Microsoft eine eigene App-Registrierung nutzen. Der größte Vorteil dabei ist die Möglichkeit, den client credentials grant flow zu nutzen. Bei der Anbindung von Microsoft 365 Postfächern in teamspace wird normalerweise ein OAuth-2.0-Login verlangt, der durch einen berechtigten Benutzer durchgeführt werden muss. Mit dem client credentials grant flow kann teamspace ohne einen Login eines Benutzers auf die Postfächer zugreifen und erleichtert somit die Verwaltung mehrerer Mail-Accounts.

Für die Einrichtung sind folgende Schritte notwendig:

1. Erstellung einer App-Registrierung im Microsoft Entra Admin Center
2. Registrierung eines Service Principals in Exchange über eine PowerShell
3. Anpassung der teamspace web.xml
4. Einrichtung der Schnittstelle in teamspace

Hinweis: Damit die Schnittstelle in teamspace eingerichtet werden kann, muss sie vorher durch einen Support-Mitarbeiter von uns freigeschaltet werden.

App-Registrierung erstellen

• Loggen Sie sich mit einem administrativen Benutzer im Microsoft Entra Admin Center ein.
• Navigieren Sie zu dem Menü-Punkt „Entra ID“ ► „App-Registrierungen“ und klicken Sie auf „Neue Registrierung“.

• Geben Sie einen beliebigen Namen ein, mit dem Sie die App wiedererkennen können.
• Als Kontotyp müssen Sie „Nur Konten in diesem Organisationsverzeichnis“ auswählen.
• Die Umleitungs-URI setzt sich aus der URL Ihrer teamspace-Installation und dem Pfad /api/server/oauth2/redirect zusammen. Beispiel: https://xyc.teamspace.de/api/server/oauth2/redirect

• Als Nächstes müssen Sie einen geheimen Clientschlüssel unter „Zertifikate & Geheimnisse“ anlegen. Geben Sie eine Beschreibung ein und wählen Sie, wie lange der Schlüssel gültig sein soll. Es muss nach der Ablaufzeit immer wieder ein neuer Schlüssel erstellt werden.
• Notieren Sie sich den „Wert“, da er später in teamspace benötigt wird und nicht noch einmal in Entra ID angezeigt wird.

• Gehen Sie nun auf „Authentication“ ► „Einstellungen“ und aktivieren Sie die Optionen „Zugriffstoken“ und „ID-Token“.

Als Nächstes müssen mehrere Berechtigungen für die App hinzugefügt werden:

• Office 365 Exchange Online: IMAP.AccessAsApp – wird für den E-Mail-Empfang per IMAP benötigt.
• Office 365 Exchange Online: SMTP.SendAsApp – wird für den E-Mail-Versand benötigt.
• Microsoft Graph: Calendars.ReadWrite – damit Teams-Termine über den teamspace Kalender erstellt werden können.
• Microsoft Graph: CallRecords.ReadAll – erlaubt es teamspace, die Anrufhistorie von Teams abzurufen.
• Microsoft Graph: Domain.ReadAll – damit die Anrufhistorie, das Erstellen von Teams-Terminen und der SSO funktionieren, müssen die teamspace Benutzer mit den Microsoft Benutzern verknüpft werden. Mit diesem Recht kann teamspace die Microsoft Benutzer besser filtern.
• Microsoft Graph: openid – erforderlich für den Microsoft Single Sign-On.
• Microsoft Graph: profile – erforderlich für den Microsoft Single Sign-On.
• Microsoft Graph: User.ReadAll – erforderlich für den Microsoft Single Sign-On und die Teams-Integration.

Die Berechtigungen für Office 365 Exchange Online fügen Sie wie folgt hinzu:

• Office 365 Exchange Online: SMTP.SendAsApp

• Office 365 Exchange Online: IMAP.AccessAsApp

Die Berechtigungen für Microsoft Graph befinden sich unter einem anderen Menü-Punkt:

• Microsoft Graph: Calendars.ReadWrite

• Microsoft Graph: CallRecords.ReadAll

• Microsoft Graph: Domain.ReadAll

• Microsoft Graph: User.ReadAll

• Microsoft Graph: openid

• Microsoft Graph: profile

• Klicken Sie abschließend unten auf „Unternehmensanwendung“. Sie gelangen damit zur Unternehmens-App für Ihre App-Registrierung.

• Hier müssen Sie auf „Grant admin consent“ klicken und den darauf folgenden Dialog von Microsoft bestätigen.

• Gehen Sie als Letztes auf die „Übersicht“ (weiterhin unter Unternehmensanwendung) und notieren Sie sich die Anwendungs-ID und die Objekt-ID.

Service Principal registrieren

Damit die zuvor erstellte Unternehmensanwendung auf die gewünschten Postfächer zugreifen kann, muss ein Service Principal registriert werden, der Zugriff auf die Postfächer erhält. Dazu müssen Sie mit einem Microsoft Benutzer, der administrative Rechte im Exchange-Bereich besitzt, einige Befehle über die PowerShell ausführen. Die groben Schritte werden hier aufgeführt; Details finden Sie in der Dokumentation von Microsoft.

• Mit den folgenden drei Befehlen wird das Modul ExchangeOnlineManagement installiert und Ihr Microsoft-Mandant verknüpft. <tenantId> muss mit Ihrer Verzeichnis-ID ersetzt werden. Sie finden diese z. B. in der vorherigen App-Registrierung in der Zusammenfassung auf der Übersichtsseite: Verzeichnis-ID (Mandant).

Install-Module -Name ExchangeOnlineManagement
Import-module ExchangeOnlineManagement
Connect-ExchangeOnline -Organization <tenantId>

• Service Principal erstellen (<APPLICATION_ID> und <OBJECT_ID> mit den Werten aus dem letzten Schritt der App-Registrierung ersetzen):

New-ServicePrincipal -AppId <APPLICATION_ID> -ObjectId <OBJECT_ID>

• Für den nächsten Schritt benötigen Sie die ID des soeben erstellten Service Principals:

Get-ServicePrincipal | fl

• Jetzt müssen noch die relevanten Postfächer dem Service Principal zugeordnet werden. Tragen Sie dazu die entsprechende E-Mail-Adresse für Identity ein und ersetzen Sie <SERVICE_PRINCIPAL_ID> mit der vorher ermittelten ID.

Add-MailboxPermission -Identity "john.smith@contoso.com" -User <SERVICE_PRINCIPAL_ID> -AccessRights FullAccess

• Unter Umständen kann es noch notwendig sein, dass Sie SMTP AUTH für die Postfächer erlauben:

Set-CASMailbox -Identity "john.smith@contoso.com" -SmtpClientAuthenticationDisabled $false

teamspace web.xml anpassen

Hinweis: Dieser Schritt kann übersprungen werden, falls Sie nicht vorhaben, den Microsoft Single Sign-On in teamspace zu nutzen.

• Bearbeiten Sie mit einem Text-Editor die webapp/WEB-INF/web.xml (im Installationsverzeichnis).
• Suchen Sie nach dem Wert oauth2Gateway.url und ersetzen Sie den Wert darunter zwischen param-value mit der URL Ihres Servers (i. d. R. identisch mit server.url).
• Starten Sie den Tomcat-Dienst neu.

Falls der context-param für oauth2Gateway.url nicht in Ihrer web.xml vorkommt, können Sie ihn in der Mitte, hinter einem anderen context-param, hinzufügen:

<context-param>
  <param-name>oauth2Gateway.url</param-name>
  <param-value>https://www.mein-teamspace.de</param-value>
</context-param>

Schnittstelle in teamspace hinzufügen

• Klicken Sie unter „Konfiguration ► Allgemein ► Schnittstellen“ auf den „+“-Knopf, um eine neue Schnittstelle zu erstellen.
• Wählen Sie als Typ „Eigene Microsoft App-Registrierung“ aus.

• Tragen Sie nun die zuvor notierten Daten ein:
  • Anwendungs-ID der Unternehmensanwendung (identisch mit der ID aus der App-Registrierung)
  • Verzeichnis-ID, welche in der Übersicht der App-Registrierung zu finden ist
  • Anwendungs-Schlüssel ist der „Wert“, der nach der Erstellung des Clientschlüssels angezeigt wurde

Nachdem Sie den Dialog speichern, erscheint ein grüner Hinweis, wenn der Zugriff auf den Microsoft-Endpunkt erfolgreich war.

Wenn alles geklappt hat, können Sie jetzt in den Mail-Accounts von teamspace als Authentifizierung „Microsoft 365 als App“ auswählen.

Hinweise

• Die Schnittstelle muss vorab durch einen Support-Mitarbeiter freigeschaltet werden, bevor Sie sie in teamspace einrichten können.
• Der geheime Clientschlüssel besitzt eine Ablaufzeit. Nach Ablauf muss ein neuer Schlüssel erstellt und in teamspace hinterlegt werden.
• Der „Wert“ des Clientschlüssels wird in Entra ID nur einmal angezeigt – notieren Sie ihn direkt nach der Erstellung.
• Die Anpassung der web.xml ist nur erforderlich, wenn Sie den Microsoft Single Sign-On nutzen möchten.

Typische Fragen & Anforderungen

Verwandte Themen

• Mailaccounts einbinden Konfiguration Konfiguration
• Single Sign-On (SSO) einrichten Konfiguration Konfiguration