OIDC mit Workspace

OpenID Connect OIDC ist ein Identitätsprotokoll, das auf OAuth 2.0 aufbaut und eine sichere Authentifizierung sowie Autorisierung für Web- und Mobile-Anwendungen ermöglicht.
Es erlaubt Nutzer, sich sicher bei verschiedenen Diensten anzumelden, während Dienstanbieter gleichzeitig auf verifizierte Identitätsinformationen zugreifen können.

In dieser Anleitung wird die Konfiguration von OIDC in Relution am Beispiel von Google Workspace erläutert.

Bei der Anmeldung über OIDC werden keine Klassen oder Gruppen synchronisiert. Benutzer werden erst beim ersten erfolgreichen Login in Relution angelegt, und nur dann, wenn in der OIDC-Konfiguration der Schalter Unbekannte Benutzer in Relution anlegen aktiviert ist. Ist er deaktiviert (Standard), ist ein Login nur für Benutzer möglich, die bereits in Relution vorhanden sind. Neu angelegte Benutzer fügt Relution automatisch der Gruppe <Name des Anbieters> Users hinzu, über die sich Berechtigungen vergeben lassen.

Einrichtung Projekt und Client (Google Cloud Console)

Zunächst muss in der Google Cloud Console eine Anwendung registriert werden, um die erforderlichen Anmeldedaten zu erhalten.

  1. Unter console.cloud.google.com → anmelden.

  2. Ein neues Projekt erstellen oder ein bestehendes auswählen.

    Neues Projekt in der Google Cloud Console erstellen oder auswählen

    Projektdetails in der Google Cloud Console eingeben und bestätigen

  3. Im Menü zu APIs & Services → OAuth consent screen navigieren und diesen bei Bedarf konfigurieren.

    OAuth Consent Screen in Google Cloud Console unter APIs und Services konfigurieren

  4. Zu Credentials wechseln, auf Create Credentials klicken und OAuth client ID auswählen.

    OAuth Client ID in Google Cloud Console unter Credentials erstellen

  5. Als Application type die Option Web application wählen.

    Web application als Application type für OAuth Client in Google Cloud auswählen

  6. Unter Authorized JavaScript origins die eigene Server-URL hinterlegen (z. B. https://support.relution.io). Hinweis: Das Feld für die Authorized redirect URIs vorerst offen lassen oder vorläufig die URL eintragen; diese wird später mit den Redirect-URIs aus Relution aktualisiert.

    Server-URL als Authorized JavaScript Origin in Google Cloud OAuth Client eintragen

  7. Nach dem Speichern wird die Client ID angezeigt. Diese kopieren.

    Generierte Client ID nach Speichern in Google Cloud Console kopieren

  8. Den neu erstellten Client erneut bearbeiten, um die Details einzusehen.

    Erstellten OAuth Client in Google Cloud Console zur Detailansicht öffnen

  9. Das Client Secret kopieren. ID und Secret für die spätere Verwendung in Relution sicher aufbewahren.

    Client Secret aus Google Cloud Console OAuth Client Details kopieren


Einrichtung SSO (Google Admin Console)

Parallel dazu muss das Single Sign-On (SSO) Profil in der Admin-Konsole hinterlegt werden.

  1. Zur Google Admin Console → navigieren.

  2. Unter Security → Authentication → SSO with third-party IdP ein neues OIDC-Profil erstellen.

    SSO Profil mit OIDC in Google Admin Console unter Security Authentication anlegen

  3. Die Client ID und das Client Secret aus dem vorherigen Kapitel eingeben.

    • Für die Issuer URL sowie die Change password URL die eigene Relution-Server-URL verwenden (z. B. https://support.relution.io).
      Client ID und Client Secret im Google Admin Console OIDC Profil hinterlegen

OIDC Einrichtung in Relution

Nun werden die gesammelten Daten in Relution eingepflegt, um die Brücke zu Google zu schlagen.

  1. In Relution die OIDC-Einstellungen unter Einstellungen → Benutzerverwaltung → OpenID Connect öffnen.

    OIDC Einstellungen in Relution unter OpenID Connect öffnen

  2. Unter Name des Anbieters eine eindeutige Bezeichnung vergeben (z. B. „Google Workspace“). Der Name erscheint auf dem Login-Button und lässt sich nach dem Speichern nicht mehr ändern.

  3. Bei Bedarf Unbekannte Benutzer in Relution anlegen aktivieren, damit neue Benutzer beim ersten Login automatisch angelegt werden.

  4. Die Client ID und das Client Secret aus der Google Cloud Console in die Felder ClientID und Client Secret eintragen.

  5. Im Abschnitt Server URIs die Option Discovery-Endpunkt verwenden wählen und im Feld Issuer URI die URL https://accounts.google.com eintragen.

  6. Die Konfiguration kurz speichern und erneut öffnen, um die generierten Felder zu sehen.

  7. Im Abschnitt Geltungsbereichsbeschränkte OIDC URLs alle angezeigten Redirect-URL-Einträge kopieren (je ein Eintrag für management und device, mit Education-Lizenz zusätzlich teacher).

    Generierte Redirect-URL aus Relution OIDC Einstellungen kopieren

  8. Zurück zur Google Cloud Console → wechseln.

  9. Den eigenen OAuth-Client bearbeiten und unter Authorized redirect URIs alle gerade aus Relution kopierten URLs eintragen. Zusätzlich die Redirect-URIs ergänzen, die das Portal nicht anzeigt, mindestens die für die Geräte-Einschreibung (/api/enrollment/), siehe Scoped Redirect-URIs.

    Relution Redirect-URL als Authorized Redirect URI im Google OAuth Client eintragen

Unter Erweiterte Konfiguration wird festgelegt, wie Relution den angemeldeten Benutzer zuordnet: Das Benutzername-Attribut vom OIDC-Provider (Standard: email) wird mit der im Feld Benutzernamen-Attribut von Relution gewählten Benutzereigenschaft abgeglichen (Benutzername, E-Mail, UUID oder Fremdschlüssel (UID); Standard: E-Mail). Bei UUID werden keine unbekannten Benutzer angelegt. Der Umfang ist standardmäßig openid, email, profile. Über Konfiguration prüfen lässt sich die Konfiguration vor dem Speichern validieren.

Scoped Redirect-URIs

Neu in 26.4

Migrationshinweis — Scoped Redirect-URIs (ab 26.4.0). Mit 26.4.0 hat sich das Schema der Redirect-URIs geändert: Login-Callbacks sind nun scoped, sodass sie am Reverse-Proxy zukünftig pfadbasiert abgesichert werden können. Welche Redirect-URIs verwendet werden, hängt davon ab, ob die OIDC-Konfiguration noch die bisherigen Pfade nutzt: Ab 26.4 neu angelegte Konfigurationen verwenden immer die scoped Redirect-URIs. Konfigurationen, die vor 26.4 angelegt wurden, verwenden weiterhin die bisherige Redirect-URI (/login/oauth2/code/), bis sie auf die scoped Pfade umgestellt werden (siehe Bestehende Konfigurationen umstellen).

Ab 26.5.0 laufen außerdem die Logins während einer Geräte-Einschreibung (enrollment), im Relution Agent (agent), in Relution Assets (assets) und im Self-Service-Portal (selfService) über eigene Scopes. Nutzt die Konfiguration die scoped Pfade und werden diese Logins mit OIDC genutzt, müssen die zugehörigen URIs beim Identity Provider eingetragen sein.

Wo sie zu finden sind: Die Redirect-URIs für die eigene Instanz werden im Relution-Portal unter Einstellungen → Benutzerverwaltung → OpenID Connect in der Konfiguration im Abschnitt Geltungsbereichsbeschränkte OIDC URLs angezeigt, sobald die Verbindung gespeichert wurde, und lassen sich dort kopieren. Das Portal zeigt allerdings nur die Einträge Redirect-URL (management), Redirect-URL (device) und, mit Education-Lizenz, Redirect-URL (teacher) an. Die URIs für die Geräte-Einschreibung (/api/enrollment/), den Relution Agent (/api/agent/), Relution Assets (/api/assets/), das Self-Service-Portal (/api/selfService/) und Relution als Identity Provider → (/api/idp/) zeigt es derzeit nicht an. Sie werden nach dem unten aufgeführten Schema manuell ergänzt, soweit die jeweilige Funktion mit OIDC genutzt wird.

Bisherige Pfade (vor 26.4 angelegte Konfigurationen, eine Redirect-URI):

https://<host>/login/oauth2/code/<registrationId>

Scoped Pfade (ab 26.4 angelegte oder umgestellte Konfigurationen, alle zutreffenden registrieren):

https://<host>/api/management/login/oauth2/code/<registrationId>       # Relution-Portal
https://<host>/api/enrollment/login/oauth2/code/<registrationId>       # Geräte-Einschreibung (ADE, User Enrollment, Android Enterprise), ab 26.5
https://<host>/api/teacher/login/oauth2/code/<registrationId>          # nur Education-Lizenz
https://<host>/api/agent/login/oauth2/code/<registrationId>            # Relution Agent, ab 26.5
https://<host>/api/assets/login/oauth2/code/<registrationId>           # Relution Assets, ab 26.5
https://<host>/api/selfService/login/oauth2/code/<registrationId>      # Self-Service-Portal, ab 26.5
https://<host>/api/idp/login/oauth2/code/<registrationId>              # Relution als Identity Provider (Beta), ab 26.5
https://<host>/api/device/login/oauth2/code/<registrationId>           # nur 26.4.x, ab 26.5 von keinem Login mehr genutzt

Die <registrationId> ist die OIDC-Konfigurations-UUID, die in Relution angezeigt wird.

Logout-URLs: Zusätzlich zeigt das Portal im selben Abschnitt zwei Logout-URLs an. Sie sind keine Redirect-URIs:

  • Logout-URL für Front-Channel: https://<host>/api/management/v1/logout/connect/front-channel/<registrationId>
  • URL für Back-Channel-Logout: https://<host>/api/management/logout/connect/back-channel/<registrationId>

Bestehende Konfigurationen umstellen

Konfigurationen, die vor 26.4 angelegt wurden, verwenden nach dem Update weiterhin die bisherige Redirect-URI. In der Konfiguration erscheint dann zusätzlich der Abschnitt OIDC bisherige URLs mit der aktuell aktiven Redirect-URL und der bisherigen URL für Back-Channel-Logout. Die Umstellung erfolgt in zwei Schritten:

  1. Alle zutreffenden scoped URIs werden zum bestehenden Google OAuth-Client hinzugefügt. Die bisherige URI bleibt vorerst eingetragen.
  2. In Relution wird unter Einstellungen → Benutzerverwaltung → OpenID Connect die Konfiguration geöffnet, im Abschnitt OIDC bisherige URLs auf Bereichbeschränkte OIDC-Pfade aktivieren geklickt und der folgende Dialog bestätigt.
Die Umstellung kann nicht rückgängig gemacht werden. Danach verwendet Relution für diese Konfiguration nur noch die scoped URIs. Fehlt eine davon beim Identity Provider, schlagen die betroffenen Logins fehl.

Bei neu angelegten Konfigurationen erscheint der Abschnitt nicht, da sie die scoped URIs von Anfang an verwenden. Die bisherige URI ist veraltet und kann in einer zukünftigen Version entfernt werden.

Redirect-URI für die Geräte-Einschreibung

Neu in 26.5

Ab Relution 26.5.0 laufen alle Logins während einer Einschreibung über den eigenen Scope enrollment. Das betrifft die Automatische Geräteregistrierung (ADE, im Portal: DEP) von Apple, das Apple Account-Driven User Enrollment, die Android Enterprise Einschreibung sowie die Anmeldung im Android Enterprise DPC. Bei Konfigurationen mit scoped Pfaden funktionieren diese Logins nur, wenn die oben aufgeführte /api/enrollment/-URI beim Identity Provider registriert ist. Konfigurationen mit den bisherigen Pfaden nutzen auch für Einschreibungen weiterhin die bisherige URI.

Fehlerbild bei fehlender URI: Die Anmeldung am Relution-Portal funktioniert weiterhin, da sie über die /api/management/-URI läuft. Erst die Einschreibung eines Geräts schlägt fehl, und zwar mit einer Meldung zur ungültigen Redirect-URI (invalid_redirect_uri, bei Google Error 400: redirect_uri_mismatch). Tritt dieser Fehler bei einer Konfiguration mit scoped Pfaden während einer Einschreibung auf, fehlt die /api/enrollment/-URI im Google OAuth-Client.


Backchannel Logout

Relution unterstützt den Backchannel Logout ab der Server-Version 5.32.0.

Szenario: Ein Benutzer ist über SSO bei mehreren Anwendungen gleichzeitig angemeldet. Sobald die Abmeldung beim zentralen SSO-Dienst erfolgt, sorgt der Backchannel Logout dafür, dass auch die Sitzungen in Relution und anderen angebundenen Anwendungen im Hintergrund sicher beendet werden.


Logout-Verifizierung

Vor der Inbetriebnahme werden die Logout-Pfade überprüft:

  • Abmeldung beim IdP beim Ausloggen aus Relution: Nach Klick auf Ausloggen wird die Sitzung in Relution widerrufen. Ist unter Erweiterte Optionen der Schalter Benutzer von OIDC abmelden, wenn er sich von Relution abmeldet aktiv (Standard: aus) und ist ein Endpunkt zum Beenden der Sitzung bekannt (manuell im Feld Endpunkt der Sitzung beenden hinterlegt oder per Discovery vom IdP gemeldet), wird der Browser zusätzlich zum Logout-Endpunkt des IdP weitergeleitet.
  • Front-Channel-Logout: Meldet sich der Benutzer beim IdP ab, ruft der IdP die im Portal angezeigte Logout-URL für Front-Channel auf und Relution widerruft die Sitzung. Dafür muss diese URL beim IdP hinterlegt sein.
  • Back-Channel-Logout: Der IdP sendet eine Logout-Benachrichtigung an die URL für Back-Channel-Logout — die Sitzung wird ohne Benutzerinteraktion widerrufen.

Durch Tests dieser Pfade wird sichergestellt, dass eine vom IdP initiierte Sitzungsbeendigung (z. B. über die IdP-Administrationskonsole) korrekt an Relution weitergegeben wird.

Wie hilfreich war dieser Artikel?