Allgemeine Konfiguration

Microsoft Entra ID für den ConnectCloud Login-Provider einrichten

Mit dieser Anleitung richten Sie in Microsoft Entra ID eine App-Registrierung für den in ConnectCloud integrierten OIDC Login-Provider ein.

Empfohlener Weg zur Übergabe

Wir empfehlen Ihnen, die Einrichtung mithilfe unseres Onboarding-Portals durchzuführen. Dort können Sie die technischen Werte erzeugen, Ihre Eingaben direkt per Smoketest prüfen und uns am Ende alle Daten sicher per verschlüsselter Datei zukommen lassen.

Zum Onboarding-Portal (onboarding.mbcom.cloud/authentik)

Sollten Sie die Werte manuell übermitteln müssen, benötigen wir zwingend alle 5 folgenden Angaben:

1. Source-Name (im Onboarding generiert)
2. Redirect-URI (im Onboarding generiert)
3. Application (client) ID (aus Entra ID)
4. Directory (tenant) ID (aus Entra ID)
5. Client Secret VALUE (aus Entra ID)

Voraussetzungen

Für die Einrichtung benötigen Sie:

• Zugriff auf das Onboarding, um die technischen Werte für Ihre Anmeldung zu erzeugen
• einen Namen für die App-Registrierung, zum Beispiel connectcloud-musterfirma
• den im Onboarding generierten Konfigurationsnamen, zum Beispiel oidc-musterfirma-7k4p2q
• die exakte Redirect-URI https://portal.mbcom.cloud/api/registry/v1/oidc/callback

Wichtig: Die Redirect-URI muss exakt dem im Onboarding angezeigten ConnectCloud Callback entsprechen.

Schritt 1: Technische Werte im Onboarding erzeugen

Tragen Sie zuerst im Onboarding Ihren Kunden- oder Firmennamen ein und erzeugen Sie daraus die technischen Werte für die Entra-App.

Dabei erhalten Sie:

• einen vorgeschlagenen App-Namen, zum Beispiel connectcloud-musterfirma
• einen technischen Konfigurationsnamen, zum Beispiel oidc-musterfirma-7k4p2q
• die feste Redirect-URI https://portal.mbcom.cloud/api/registry/v1/oidc/callback

Übernehmen Sie den Source-Namen und die Redirect-URI anschließend unverändert in Microsoft Entra ID. Diese Werte müssen exakt übereinstimmen.

Schritt 2: Neue App Registration anlegen

Melden Sie sich im Microsoft Entra Admin Center an und öffnen Sie:

• Microsoft Entra ID > App registrations > New registration

Schritt 3: Basisdaten eintragen

Tragen Sie in der neuen App-Registrierung die folgenden Werte ein:

• Name: connectcloud-musterfirma
• Supported account types: Accounts in this organizational directory only (Single tenant)
• Redirect URI:
  • Plattform: Web
  • URI: https://portal.mbcom.cloud/api/registry/v1/oidc/callback

Klicken Sie anschließend auf Register.

Schritt 4: Redirect URI nach der Erstellung prüfen

Öffnen Sie anschließend in der App den Bereich Authentication und prüfen Sie, ob dort genau diese Redirect-URI hinterlegt ist:

https://portal.mbcom.cloud/api/registry/v1/oidc/callback

Wichtig ist, dass die URI exakt stimmt:

• mit https
• mit vollständigem Pfad
• ohne Query-Parameter oder Fragment

Schon kleine Abweichungen können dazu führen, dass die Anmeldung später nicht funktioniert.

Schritt 5: Client Secret erzeugen

Öffnen Sie den Bereich Certificates & secrets und klicken Sie auf New client secret. Tragen Sie eine Beschreibung ein (z. B. authentik-musterfirma-secret) und wählen Sie eine passende Laufzeit.

Wichtig: Secret Value vs. Secret ID

Nach dem Speichern zeigt Microsoft zwei Spalten an: Value und Secret ID.

• Wir benötigen ausschließlich den Value (einen längeren, zufälligen String).
• Die Secret ID (ein UUID-Format) wird von uns nicht benötigt.

Kopieren und speichern Sie den Value sofort an einem sicheren Ort. Er wird nach dem Verlassen der Ansicht nie wieder vollständig angezeigt.

Schritt 6: Client ID und Tenant ID notieren

Notieren Sie sich auf der Übersichtsseite der App die folgenden Werte:

• Application (client) ID
• Directory (tenant) ID

Zusammen mit dem Client Secret und dem im Onboarding erzeugten Konfigurationsnamen und der Redirect-URI sind dies die 5 Angaben, die wir für die Einrichtung benötigen.

Sie können diese Werte im Onboarding-Portal eintragen, um die Zugangsdaten direkt zu prüfen und uns anschließend verschlüsselt zu übermitteln.

Schritt 7: Berechtigungen hinzufügen

Öffnen Sie:

• API permissions > Add a permission > Microsoft Graph > Delegated permissions

Fügen Sie die folgenden fünf Berechtigungen hinzu:

1. openid
2. profile
3. email
4. User.Read
5. GroupMember.Read.All

Diese Berechtigungen sind erforderlich, damit die Anmeldung funktioniert und die grundlegenden Benutzerinformationen übernommen werden können.

Schritt 8: Admin Consent erteilen

Klicken Sie anschließend im Bereich API permissions auf:

• Grant admin consent

Damit vermeiden Sie, dass Benutzer beim ersten Login zusätzlich eine Berechtigungsabfrage bestätigen müssen.

Schritt 9: Ergebnis prüfen

Am Ende sollte Ihre App die folgenden Eigenschaften haben:

• [ ] Die App Registration ist erstellt und auf Single tenant gesetzt.
• [ ] Die Redirect-URI entspricht exakt dem Wert aus dem Onboarding.
• [ ] Der Client Secret Value (nicht die ID!) wurde notiert.
• [ ] Application (client) ID und Directory (tenant) ID liegen vor.
• [ ] Alle fünf Berechtigungen (openid, profile, email, User.Read, GroupMember.Read.All) sind freigegeben.
• [ ] Alle 5 Übergabewerte wurden im Onboarding-Portal geprüft und uns verschlüsselt übermittelt (Empfohlen).

Anforderungen an Microsoft Entra Gruppen

Damit die Berechtigungssteuerung innerhalb der ConnectCLOUD fehlerfrei funktioniert, müssen die Gruppennamen in Microsoft Entra ID eindeutig sein.

• Eindeutigkeit: Kein Benutzer darf Mitglied in zwei oder mehr Entra-Gruppen mit identischem Namen sein.
• Beispiel: Wenn ein Benutzer zwei verschiedene Gruppen mit dem Namen Buchhaltung hat, kann dies zu Fehlern bei der Synchronisation und Berechtigungsprüfung führen.

Stellen Sie daher sicher, dass alle Gruppen, die für die ConnectCLOUD relevant sind, über eindeutige Bezeichnungen verfügen.

Unterstützung durch MBCOM

Auf Wunsch kann die vollständige Einrichtung der ConnectCLOUD-Schnittstelle durch MBCOM übernommen werden.

Fehlerbehebung (Troubleshooting)

Redirect-URI Mismatch

Ein häufiger Fehler ist eine Diskrepanz zwischen der in der Entra App-Registrierung hinterlegten Redirect-URI und der in der ConnectCLOUD konfigurierten URI.

• Symptom: Nach der Anmeldung bei Microsoft erscheint eine Fehlermeldung, dass die Redirect-URL nicht übereinstimmt.
• Lösung: Prüfen Sie in der Entra App-Registrierung unter Authentication, ob die Redirect-URI exakt mit dem Wert aus dem Onboarding übereinstimmt (siehe Schritt 4).

Fehlender Admin-Consent (Administratorzustimmung)

Wenn der Admin-Consent nicht erteilt wurde, können Benutzer die Anwendung eventuell nicht nutzen oder erhalten bei jedem Login eine Abfrage.

• Symptom: Benutzer erhalten eine Meldung "Need admin approval" oder müssen Berechtigungen manuell bestätigen.
• Lösung: Ein Administrator muss im Entra Admin Center unter API permissions auf die Schaltfläche Grant admin consent klicken (siehe Schritt 8).

Nicht eindeutige Gruppennamen

Damit die Berechtigungssteuerung fehlerfrei funktioniert, müssen Gruppennamen in Entra ID eindeutig sein.

• Symptom: Berechtigungen werden nicht korrekt angewendet, die Synchronisation oder der Login schlägt fehl.
• Problem: Wenn ein Benutzer Mitglied in zwei verschiedenen Gruppen mit identischem Namen ist (z. B. zweimal Buchhaltung), kann das System die Berechtigungen nicht eindeutig zuordnen.
• Lösung: Stellen Sie sicher, dass alle für die ConnectCLOUD relevanten Gruppen über eindeutige Bezeichnungen verfügen.