Microsoft Azure AD / Entra ID an Q.wiki anbinden (SCIM+OIDC)

Diese Anleitung ist für IT-Fachpersonal gedacht und unterstützt die selbstständige Anbindung von Q.wiki an Microsoft Entra ID. Bei Unklarheiten helfen die Dokumentationen von Microsoft oder der Q.wiki Support weiter.

Überblick und Limitierungen

Was wird hier erklärt

Diese Anleitung zeigt dir, wie du Q.wiki mit Microsoft Entra ID über SCIM (Nutzersynchronisation) und OIDC (Single Sign-On) verbindest. Der Prozess erfolgt in zwei Schritten und muss in dieser Reihenfolge durchgeführt werden.

Wichtige Limitierungen

• Keine verschachtelten Gruppen: Mit Microsoft Entra ID können nur einzelne Nutzer und Gruppen synchronisiert werden. Verschachtelte Gruppen (Gruppen in Gruppen) werden nicht unterstützt.
• SCIM + OIDC zusammen: Die Einrichtung von SCIM (Nutzersynchronisation) geht zwingend mit der Einrichtung von SSO per OIDC (Anmeldung) einher. Eine getrennte Konfiguration ist nicht möglich.
• Kein Multi-Provider-Betrieb: Microsoft Entra ID kann nicht zusammen mit anderen Providern (z. B. LDAP) konfiguriert werden. Die manuelle Anlage und Verwaltung von Nutzern bleibt immer aktiv und erlaubt es, externe Nutzer in Q.wiki zu registrieren.
• Ein Identity Provider pro Mandant: Es kann nur ein Identity Provider und ein Tenant gleichzeitig angebunden werden.
• E-Mail-Adressen müssen eindeutig sein: Jeder Nutzer muss eine eindeutige E-Mail-Adresse haben, bevor Microsoft Entra ID angebunden werden kann. Der Konfigurationsdialog in Q.wiki weist darauf hin, sollte diese Voraussetzung nicht erfüllt sein. Du kannst doppelt vergebene E-Mail-Adressen über die Nutzerverwaltung in Q.wiki ändern.
• Längenbeschränkung bei Nutzerdaten: Aus Sicherheitsgründen haben alle synchronisierten Nutzerdaten eine Längenbeschränkung von 100 Zeichen. Nutzer mit einem Anzeigenamen über 100 Zeichen können daher nicht synchronisiert werden.

Migration vorhandener Nutzer

Wenn du Entra ID anbindest, werden bestehende Q.wiki-Nutzer mit einer übereinstimmenden E-Mail-Adresse automatisch migriert. Diese Nutzer werden mit den Daten aus Entra ID aktualisiert und von diesem Zeitpunkt an über Entra ID verwaltet.

Migrierte Nutzer melden sich über den Button Unternehmenslogin verwenden an. Die Anmeldung mit Nutzernamen und Passwort ist nicht mehr möglich.

Notfall-Konto einrichten

Sollte es zu einer Fehlfunktion seitens Entra ID kommen oder der Secret-Token auslaufen, ist eine Anmeldung nur noch über manuell in Q.wiki angelegte Nutzer möglich. Aus diesem Grund empfehlen wir, ein manuell verwaltetes Konto der KeyUserGroup hinzuzufügen. Dieses Konto muss über eine gültige E-Mail-Adresse verfügen und darf nicht über Azure provisioniert werden. Eine unpersönliche E-Mail-Adresse wie „service@…" oder „it-support@…" bietet sich an.

Sollte der Secret bereits abgelaufen sein, lies den Artikel 401 Unauthorized Fehlermeldung bei Benutzeranmeldung.

Schritt 1: Nutzersynchronisation mit SCIM einrichten

SCIM sorgt dafür, dass Nutzer und Gruppen aus Entra ID automatisch in Q.wiki erstellt und aktualisiert werden.

1. Öffne Microsoft Entra ID und lege eine neue Enterprise Application an.
   Wichtig: Starte mit einer Enterprise Application (Unternehmensanwendung), nicht mit einer App Registration!
2. Klicke auf Create your own application.
3. Gib den Namen der App ein (z. B. „Q.wiki") und wähle Non-gallery aus.
4. Klicke auf Create.
5. Wähle in der angelegten App Provisioning.
6. Klicke auf Get started.
7. Stelle Provisioning Mode auf Automatic.
8. Wechsle in Q.wiki zu Werkzeuge > Nutzerverwaltung und öffne über das 3-Punkte-Menü Provisionierung konfigurieren.
9. Kopiere die Tenant URL aus dem Dialog in Entra ID in Q.wiki und generiere ein Secret.
10. Klicke auf Test Connection und speichere die Einstellung nach erfolgreicher Verbindung.
11. Aktiviere unter Mappings die Gruppenprovisionierung.
12. Gehe zu Settings > Notification Email und trage die E-Mail des Verantwortlichen ein, der bei Synchronisierungsproblemen benachrichtigt werden soll.
13. Unter Scope musst du die Option Nur zugewiesene Nutzer und Gruppen synchronisieren explizit auswählen (falls vorhanden).
14. Stelle Provisioning Status auf On und speichere.
15. Unter Users and groups fügst du Nutzer und Gruppen hinzu. Wenn alle Benutzer provisioniert werden sollen, kannst du die Standardgruppe Alle Benutzer verwenden.
    Wichtig: Gruppen sind nur eine Option, wenn du über einen aktualisierten Azure Active Directory P1- oder P2-Mandanten verfügst. Die Standard-AD-Planebene ermöglicht nur die Zuweisung einzelner Benutzer zur Anwendung.
    

Nach spätestens 40 Minuten werden die Nutzer in Q.wiki synchronisiert. Du kannst die Konfiguration sofort mit Schritt 2 fortsetzen – die Synchronisation läuft im Hintergrund.

Schritt 2: Single Sign-On mit OIDC einrichten

Mit OIDC werden provisionierte Nutzer automatisch in Q.wiki angemeldet, wenn sie bereits bei Entra ID oder Microsoft 365 authentifiziert sind. Falls nicht, werden sie automatisch zur Microsoft-365-Anmeldung weitergeleitet.

1. Gehe in Q.wiki zu Werkzeuge > Nutzerverwaltung (Key-User-Werkzeuge).
2. Öffne über das 3-Punkte-Menü Identity Provider (IdP) anbinden und wähle Entra ID. Der Q.wiki Dialog wird im Verlauf der Entra-ID-Konfiguration befüllt.
3. Lege in Entra ID eine neue App Registrierung an.
4. Wähle All applications und öffne die zuvor angelegte Q.wiki-Applikation.
5. Kopiere die Application (client) ID und die Directory (tenant) ID und trage sie in den Q.wiki Konfigurationsdialog ein.
6. Wähle Authentication in der linken Menüleiste.
   • Klicke auf Add a platform.
   • Wähle Web application.
7. Kopiere die Redirect URI aus dem Q.wiki Konfigurationsdialog und trage sie hier ein.
8. Klicke auf Configure und wähle dann Certificates & secrets.
9. Klicke auf New client secret, gib eine Beschreibung ein und klicke Add.
   • Kopiere den Wert des generierten Secrets und füge ihn in den Q.wiki Konfigurationsdialog ein.
     Wichtig: Achte darauf, den Wert und nicht die geheime ID zu kopieren!
     
10. Klicke im Q.wiki Konfigurationsdialog auf Speichern.
11. Wähle API permissions.
    • Klicke auf Add a permission.
    • Wähle Microsoft Graph.
    • Wähle Delegated permissions.
    • Unter OpenId permissions wählst du email, openid und profile aus.
    • Klicke auf Add a permission.
    • Klicke auf Grant admin consent und bestätige mit Yes.
12. Ab jetzt sollten provisionierte Nutzer automatisch in Q.wiki angemeldet werden.