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

• Logge dich mit einem administrativen Benutzer im Microsoft Entra Admin Center ein.
• Navigiere zu dem Menü-Punkt „Entra ID“ ► „App-Registrierungen“ und klicke auf „Neue Registrierung“.

• Gib einen beliebigen Namen ein, mit dem du die App wiedererkennen kannst.
• Als Kontotyp musst du „Nur Konten in diesem Organisationsverzeichnis“ auswählen.
• Die Umleitungs-URI setzt sich aus der URL deiner teamspace-Installation und dem Pfad /api/server/oauth2/redirect zusammen. Beispiel: https://xyc.teamspace.de/api/server/oauth2/redirect

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

• Gehe nun auf „Authentication“ ► „Einstellungen“ und aktiviere 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ügst du 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

• Klicke abschließend unten auf „Unternehmensanwendung“. Du gelangst damit zur Unternehmens-App für deine App-Registrierung.

• Hier musst du auf „Grant admin consent“ klicken und den darauf folgenden Dialog von Microsoft bestätigen.

• Gehe als Letztes auf die „Übersicht“ (weiterhin unter Unternehmensanwendung) und notiere dir 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 musst du 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 findest du in der Dokumentation von Microsoft.

• Mit den folgenden drei Befehlen wird das Modul ExchangeOnlineManagement installiert und dein Microsoft-Mandant verknüpft. <tenantId> muss mit deiner Verzeichnis-ID ersetzt werden. Du findest 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ötigst du die ID des soeben erstellten Service Principals:

Get-ServicePrincipal | fl

• Jetzt müssen noch die relevanten Postfächer dem Service Principal zugeordnet werden. Trage dazu die entsprechende E-Mail-Adresse für Identity ein und ersetze <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 du SMTP AUTH für die Postfächer erlaubst:

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

teamspace web.xml anpassen

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

• Bearbeite mit einem Text-Editor die webapp/WEB-INF/web.xml (im Installationsverzeichnis).
• Suche nach dem Wert oauth2Gateway.url und ersetze den Wert darunter zwischen param-value mit der URL deines Servers (i. d. R. identisch mit server.url).
• Starte den Tomcat-Dienst neu.

Falls der context-param für oauth2Gateway.url nicht in deiner web.xml vorkommt, kannst du 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

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

• Trage 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 du den Dialog speicherst, erscheint ein grüner Hinweis, wenn der Zugriff auf den Microsoft-Endpunkt erfolgreich war.

Wenn alles geklappt hat, kannst du 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 du sie in teamspace einrichten kannst.
• 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 – notiere ihn direkt nach der Erstellung.
• Die Anpassung der web.xml ist nur erforderlich, wenn du den Microsoft Single Sign-On nutzen möchtest.

Häufige Probleme

Warum lässt sich die Schnittstelle in teamspace nicht einrichten? Die Schnittstelle muss vorher durch einen Support-Mitarbeiter freigeschaltet werden. Wende dich dafür an das Support-Team, bevor du sie unter „Konfiguration ► Allgemein ► Schnittstellen” anlegst.

Warum schlägt der SMTP-Versand für ein Postfach fehl? Für das betroffene Postfach ist SMTP AUTH nicht erlaubt. Setze ihn per PowerShell mit Set-CASMailbox … -SmtpClientAuthenticationDisabled $false.

Warum wird der „Wert” des Clientschlüssels in Entra ID nicht mehr angezeigt? Der „Wert” erscheint nur einmal direkt nach der Erstellung. Notiere ihn sofort – sonst musst du einen neuen geheimen Clientschlüssel anlegen.

Warum greifen die vergebenen Berechtigungen nicht? Die Berechtigungen wirken erst nach der Zustimmung. Klicke in der Unternehmensanwendung auf „Grant admin consent” und bestätige den Microsoft-Dialog.

Typische Fragen & Anforderungen

Verwandte Themen

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