Entra ID Apps

hinweis

«CUSTOMER.com» steht nur beispielhaft für eine Domain und ist durch die eigene URL zu ersetzen.

Im Entra ID (ehemals Azure AD) muss eine Application registriert werden. In der Regel reicht eine «Single tenant»-Registrierung. Nur falls die Installation für mehrere Entra IDs erreichbar sein soll, muss «Multitenant» aktiviert werden.

warnung

ACHTUNG
«Personal Microsoft accounts» werden nicht unterstützt.

Entra ID App Erstellung

Als Redirect URI «Web» als Plattform wählen und eine solche URL eintragen:

https://CUSTOMER.com/ids/oidc-signin-office365auth

«CUSTOMER.com» steht für die Zieladresse, unter welcher primedocs später erreichbar sein wird.

Application (client) ID und Directory (tenant) ID

Nach der Erstellung zeigt die Seite Overview (Übersicht) der App-Registrierung zwei GUIDs, die später in die primedocs.config gehören:

Wert auf der Seite «Overview»	Verwendung in der primedocs.config
Application (client) ID (Anwendungs-ID)	clientId im Knoten office365Auth
Directory (tenant) ID (Verzeichnis-ID)	{TENANTGUID} in der authority beider Knoten, also https://login.microsoftonline.com/{TENANTGUID}

Die Object ID derselben Seite wird nicht benötigt. Welche Werte wohin gehören, zeigt die Tabelle unter primedocs.config › Werte aus den App-Registrierungen.

Entra ID App Authentication

Nach der Erstellung die folgende Konfiguration hinzufügen:

Unter Redirect URIs muss Folgendes aufgelistet sein:

https://CUSTOMER.com/ids/oidc-signin-office365auth
https://CUSTOMER.com/datasourceadminapp/office365adminconsent

Unter Front-channel logout URL:

https://CUSTOMER.com/ids/

Unter «Implicit grant and hybrid flows» aktivieren:

• Access tokens
• ID tokens

Entra ID Certifications und secret

Danach unter Certificates & secrets ein Client secret erstellen. Eine ausreichende Gültigkeit wählen, denn dieses Secret wird später in der primedocs.config hinterlegt und muss aktuell gehalten werden.

Nach dem Erstellen den Inhalt der Spalte Value (Wert) kopieren und sicher ablegen. Dieser Wert gehört als clientSecret in den Knoten office365Auth. Er ist nur unmittelbar nach dem Erstellen sichtbar, danach zeigt die Seite nur noch die Secret ID, die in der primedocs.config nicht verwendet wird. Ist der Wert verloren, ein neues Secret erstellen.

Entra ID API Permissions

Der Applikation folgende «Delegated permissions» unter «Microsoft Graph» geben:

• email
• offline_access
• openid
• profile
• User.Read

Für die «Application permissions» gibt es zwei Betriebsarten: den Standardbetrieb mit Application permissions und den Betrieb ohne Application permissions.

Standardbetrieb mit Application permissions

Im Standardbetrieb erhält die Applikation zusätzlich folgende «Application permissions» unter «Microsoft Graph»:

• GroupMember.Read.All: Über diese Berechtigung stellt primedocs die Gruppenmitgliedschaften eines Benutzers fest und schlägt Gruppen nach. Vorlagen, Snippets, Profile usw. können in primedocs auf Entra-ID-Gruppen berechtigt werden. Um herauszufinden, ob ein Benutzer in einer bestimmten Gruppe ist, wird dieses Recht benötigt.
• User.Read.All: Über diese Berechtigung schlägt primedocs Benutzer nach, durchsucht das Verzeichnis im Web-Admin und synchronisiert Benutzer über den Microsoft Graph.

Den «Consent» für diese Applikation erteilen.

hinweis

Installationen, denen Directory.Read.All erteilt ist, laufen unverändert weiter. Diese Berechtigung gibt primedocs Lesezugriff auf das ganze Verzeichnis, GroupMember.Read.All genügt. Der HealthMonitor weist mit einer Information darauf hin. Fehlt eine nötige Berechtigung, nennt er sie beim Namen.

Betrieb ohne Application permissions

Sollen der Applikation keine Application permissions erteilt werden, wird das pro Datasource eingestellt: im Web-Admin unter Integrationen › Identitätsanbieter mit dem Schalter «Ohne Application Permissions betreiben». Die primedocs.config bleibt dabei unverändert. Die Umstellung wirkt nach etwa ein bis zwei Minuten und lässt sich jederzeit zurücksetzen. Bei Datasources mit SCIM oder Active Directory hat die Einstellung keine Wirkung.

primedocs fragt Microsoft Graph dann nicht mehr mit Application permissions ab. Die Anmeldung über Entra ID funktioniert weiterhin, ebenso Funktionen mit delegierten Berechtigungen wie das Speichern in SharePoint oder OneDrive. Es gelten aber folgende Einschränkungen:

• Entra-ID-Gruppen wirken nicht. Es gelten nur Freigaben für einzelne Benutzer, für alle Benutzer und für App-Gruppen von primedocs. App-Gruppen, deren Mitglieder Entra-ID-Gruppen sind, wirken ebenfalls nicht.
• Die Suche im Verzeichnis liefert keine Treffer, Benutzer und Gruppen aus Entra ID lassen sich nicht hinzufügen. Benutzer und Gruppen, die primedocs bereits kennt, bleiben auffindbar. Neue Benutzer entstehen weiterhin bei ihrer ersten Anmeldung.
• Die Benutzersynchronisierung über den Microsoft Graph steht nicht zur Verfügung. Ist eine solche Quelle im Benutzer-Sync konfiguriert, wird sie übersprungen, ohne die Benutzer als fehlerhaft oder zur Löschung zu markieren.
• Die Synchronisation der Verzeichnisgruppen (Gruppen-Sync) wird übersprungen. Gruppen erhalten keine Warnung und werden nicht automatisch gelöscht.
• Die Organisationssynchronisation gleicht die Berechtigungen der Organisationseinheiten nicht ab, bestehende Berechtigungen bleiben unverändert. Struktur, Titel und Felder werden weiterhin synchronisiert.
• Die Namensregel für den Anzeigenamen wirkt nicht. Benutzer heissen so, wie es die Anmeldung über Entra ID meldet.
• Der Principal-Cache für Gruppenmitgliedschaften wird nicht genutzt. Ist er aktiviert, weist der HealthMonitor mit einer Information darauf hin.

Der HealthMonitor meldet den Betrieb ohne Application permissions selbst als Information und nicht als Fehler. Über die API liefert er pro Datasource, ob die Application permissions erteilt sind, fehlen oder bewusst nicht verwendet werden: siehe Principal Connector und Application permissions.

warnung

Ist die Überprüfung der Profile mit Korrektur aktiv, entfernt sie in diesem Betrieb Organisationseinheiten, die nur über Entra-ID-Gruppen berechtigt sind. Ein späteres Zurücksetzen des Schalters stellt diese Zuordnungen nicht wieder her.

hinweis

Sollen Entra-ID-Gruppen ohne Application permissions wirken, kann die SCIM Schnittstelle für die Benutzer- und Gruppensynchronisierung genutzt werden. Sie wird in der primedocs.config eingerichtet.

Optionale «Delegated permissions»:

• Files.ReadWrite.All & Sites.ReadWrite.All wird für die Integration in Microsoft SharePoint und Microsoft Teams (Anwendungsfälle) benötigt.

Weitere Konfiguration dieser App Registration

• Add-In-SSO (Silent SSO): Für den stillen Single Sign-On in den Office-/Teams-Add-Ins muss diese Registration zusätzlich um eine SPA-Plattform (brk-multihub://<webapp-domain>), Expose an API (Scope access_as_user, Application ID URI im Standardwert api://<client-id>) und vorautorisierte Client-Applikationen erweitert werden. Die vollständige Anleitung steht unter Single Sign-On (SSO) › App Registration für Add-In-SSO.
• groups-Claim: Sollen Datasources nur für bestimmte Benutzergruppen sichtbar sein (allowedForGroups), muss auf dieser Registration zusätzlich der groups-Claim konfiguriert werden. Details siehe primedocs.config › Multitenancy-Modus.

---

Entra ID App Erstellung DataSourceAdminApp

App Registration

Die DataSourceAdminApp ist nicht mit dem Rechte- und Rollenkonzept verbunden, sondern als Applikation entworfen, um die initiale Konfiguration und den Betrieb zu unterstützen.

In einer klassischen OnPrem-Umgebung würde man z. B. nur die Administratoren per Windows-Gruppen auf diese Applikation berechtigen. Im Azure-Umfeld bildet eine weitere Entra App Registration dies ab.

Hierfür eine weitere Anwendung registrieren und als Redirect URI Folgendes angeben:

https://CUSTOMER.com/ids/oidc-signin-datasourceadmin 

Unter «Implicit grant and hybrid flows» aktivieren:

• Access tokens
• ID tokens

Für diese Anwendung ebenfalls ein Client-Secret festlegen.

Die Application (client) ID dieser zweiten Registrierung und der Value ihres Client Secrets gehören als clientId und clientSecret in den Knoten dataSourceAdminAppAuth der primedocs.config. Die Directory (tenant) ID ist dieselbe wie bei der ersten Registrierung.

Anschliessend bei den API Permissions ebenfalls den «Consent» für diese Applikation erteilen.

Enterprise Application: User Assignment

Der Zugriff auf die DataSourceAdminApp sollte stark eingeschränkt sein. Hierfür die Möglichkeit der «User Assignments» bei der Enterprise Application nutzen.

Die eben erstellte App Registration der DataSourceAdminApp suchen, «Assignment required» aktivieren und die Benutzer auswählen, welche Zugriff bekommen sollen (in der Regel nur technische Personen und Administratoren, die Pakete exportieren oder importieren müssen, um den Betrieb sicherzustellen).