Authentifizierung mit OpenID Connect

Allgemeine Informationen zu OpenID Connect

Was ist OpenID Connect?

OpenID Connect (OIDC) ist ein Authentifizierungsprotokoll, das auf OAuth 2.0 aufbaut. Es ermöglicht Clients, die Identität eines Benutzers auf Basis einer Authentifizierung durch einen Authorization Server (OpenID Provider) zu verifizieren. Zusätzlich können grundlegende Profilinformationen des Benutzers abgefragt werden.

Das FirstSpirit OIDC Login Modul unterstützt drei OAuth 2.0 / OpenID Connect-Flows:

• Authorization Code Flow: Browserbasiertes Login mit Redirect zum OpenID Provider (Single Sign-On (SSO))
• Resource Owner Password Credentials Flow: Direkter Login mit Benutzername und Passwort (für API- und CLI-Clients)
• Token Exchange Flow: Authentifizierung mit einem bereits vorhandenen Token (z.B. von einer vorgeschalteten Anwendung)

Modulbeschreibung

Funktionsweise und Architektur

Das FirstSpirit OIDC Login Modul ist ein JAAS-basiertes Authentifizierungsmodul, das als FirstSpirit-Modul (FSM) installiert wird. Es integriert sich in den standardmäßigen JAAS-Login-Mechanismus von FirstSpirit und delegiert die Authentifizierung an einen externen OpenID-Connect-Provider.

Untersützte Authentifizierungsflows

Authorization Code Flow (Browser-Login / SSO)

Der Authorization Code Flow wird für browserbasiertes Login über den ContentCreator oder andere Web-Clients verwendet. Der Ablauf ist wie folgt:

1. Der Benutzer ruft den FirstSpirit-Client im Browser auf.
2. Das Login-Modul leitet den Browser zum Login-Formular des OpenID Providers weiter.
3. Nach erfolgreicher Authentifizierung leitet der Provider den Browser mit einem Authorization Code zurück an FirstSpirit.
4. Das Modul tauscht den Authorization Code gegen ein ID-Token und ein Access-Token ein.
5. Das Modul validiert das ID-Token und ruft optional den UserInfo-Endpoint ab.
6. Der Benutzer wird in FirstSpirit angemeldet.

Dieser Flow unterstützt Single Sign-On (SSO); d.h., ist der Benutzer bereits beim OpenID Provider angemeldet, erfolgt die Authentifizierung ohne erneute Passworteingabe.

Resource Owner Password Credentials Flow (CLI/API)

Der Password Flow wird für nicht-interaktive Clients verwendet, z.B. für API-Zugriffe. Der Ablauf ist wie folgt:

1. Der Client sendet Benutzername und Passwort an FirstSpirit.
2. Das Login-Modul sendet die Zugangsdaten direkt an den Token-Endpoint des OpenID Providers.
3. Der Provider antwortet mit einem ID-Token und einem Access-Token.
4. Das Modul validiert das ID Token und ruft optional den UserInfo-Endpoint ab.
5. Der Benutzer wird in FirstSpirit angemeldet.

Nicht alle OpenID-Provider unterstützen den Password Flow. Prüfen Sie die Dokumentation Ihres Providers.

Token Exchange Flow (Token-basierte Authentifizierung)

Der Token-Exchange-Flow ermöglicht die Authentifizierung mit einem bereits vorhandenen Token. Dies ist nützlich, wenn eine vorgeschaltete Anwendung bereits ein gültiges Token besitzt. Der Ablauf ist wie folgt:

1. Der Client übergibt ein vorhandenes Token (Access Token, ID Token oder Refresh Token) an FirstSpirit.
2. Das Login-Modul tauscht dieses Token beim Token-Endpoint des OpenID Providers gegen ein neues ID Token und Access Token aus (RFC 8693 Token Exchange).
3. Das Modul validiert das neue ID Token und ruft optional den UserInfo-Endpoint ab.
4. Der Benutzer wird in FirstSpirit angemeldet.

Unterstützte Token-Typen:

FS-Connection mit Token aufbauen

Eine FirstSpirit-Verbindung kann mit einem vorhandenen Token über die Verbindungsparameter hergestellt werden:

import de.espirit.firstspirit.access.*; 

// Verbindung mit Access Token (Standard) 
Connection c = ConnectionManager.getConnection( 
    "localhost", 4088, ConnectionManager.SOCKET_MODE, 
    "plain", Map.of("token", "abc123...")
 ); 
c.connect(); 

// Mit explizitem Token-Typ: 
Map.of("token", "abc123...", "tokenType", "refresh") 
Map.of("token", "abc123...", "tokenType", "ID")

Voraussetzungen

Für die Einrichtung des OIDC-Login-Moduls werden die folgenden Voraussetzungen benötigt:

• FirstSpirit Server ab Version 5.2.250606 mit JAAS-Unterstützung
• Registrierter OpenID Connect Provider (Issuer), hier Keycloak
• Client-Registrierung beim Provider:
  • Client ID
  • Client Secret (empfohlen)
  • Konfigurierte Redirect-URI (für den Authorization Code Flow)
• Netzwerkzugriff vom FirstSpirit Server zum OpenID Provider (HTTPS)

Client-Registrierung beim Provider

Registrieren Sie eine neue Client-Anwendung bei Ihrem OpenID Provider mit den folgenden Einstellungen:

Installation und Einrichtung des Moduls

FSM-Datei installieren

• Öffnen Sie den ServerManager und verbinden Sie sich mit dem FirstSpirit Server.
• Navigieren Sie zu Server-Eigenschaften > Module.
• Klicken Sie auf Installieren und wählen Sie die Datei fs-oidc-login-{version}.fsm aus.
• Bestätigen Sie die Installation.

WebApp-Deployment (für Authorization Code Flow)

Wenn der Authorization Code Flow verwendet werden soll, muss die Web-Komponente des Moduls zur Root-WebApp hinzugefügt werden:

• Navigieren Sie im ServerManager zu Projekt-Eigenschaften > Web-Komponenten.
• Fügen Sie die Web-Komponente des OIDC-Moduls zur Root-WebApp hinzu.
• Deployen Sie die Root-WebApp neu.

Ohne diesen Schritt steht der HTTP-Callback-Endpoint für den Authorization Code Flow nicht zur Verfügung.

OIDC-Service starten

Nach der Installation muss der Service OIDC Service gestartet werden:

• Navigieren Sie im ServerManager zu Server-Eigenschaften > Module > fs-oidc-login > OIDC Service.
• Starten Sie den Service über den Start-Button bzw. aktivieren Sie Automatisch starten.

Der Service stellt die Konfigurationsschnittstelle bereit und wird von den Login-Modulen benötigt.

Konfigurationsdatei bearbeiten (ServerManager GUI)

• Doppelklicken Sie auf den OIDC Service um die Konfigurationsoberfläche zu öffnen.
• Die Konfigurationsdatei fs-oidc.conf wird in einem Texteditor angezeigt.
• Passen Sie die Konfiguration an Ihren OpenID Provider an.
• Klicken Sie auf OK um die Konfiguration zu speichern.

Über den Upload-Button können Sie zusätzliche Dateien (z. B. statische Provider-Metadaten) in das Konfigurationsverzeichnis hochladen.

Die Konfigurationsdatei wird im Verzeichnis {FS-Install}/conf/fs-oidc/fs-oidc.conf
gespeichert.

JAAS-Konfiguration anpassen

Passen Sie die JAAS-Konfigurationsdatei fs-jaas.conf an. Der Standardpfad ist {FS-Install}/conf/fs-jaas.conf.

Mehr Informationen zur JAAS-Konfiguration finden Sie in hier.

Konfigurationsdatei (fs-oidc.conf)

Die Konfiguration des OIDC-Login-Moduls erfolgt über die Datei fs-oidc.conf im Verzeichnis {FS-Install}/conf/fs-oidc/. Die Datei verwendet ein INI-ähnliches Format mit Sektionen.

Aufbau und Sektionen

Die Konfigurationsdatei unterstützt mehrere Sektionen. Jede Sektion wird durch [sektionsname] eingeleitet. Die Sektion [default] ist die Standardsektion und dient als Fallback: Wenn ein Wert in einer spezifischen Sektion nicht gefunden wird, wird automatisch der Wert aus [default] verwendet.

Welche Sektion eines Login-Moduls verwendet wird, wird in der JAAS-Konfigurationsdatei fs-jaas.conf über die Option section festgelegt (siehe JAAS-Konfiguration).

Beispielstruktur:

[default]
# Gemeinsame Konfiguration fuer alle Flows
op.issuer=https://idp.example.com/realms/myrealm
rp.clientId=firstspirit
rp.clientSecret=geheim123
import.user=true
user.login=${oidc:preferred_username}

[auth]
# Spezifische Konfiguration fuer den Authorization Code Flow
rp.redirectUri=${request:PROXY}

[pass]
# Spezifische Konfiguration für den Password Flow
op.scopes=openid, profile, email

In diesem Beispiel erben [auth] und [pass] alle Werte aus [default], überschreiben jedoch einzelne Eigenschaften für ihren jeweiligen Anwendungsfall.

OpenID Provider Konfiguration (op.*)

Relying Party Konfiguration (rp.*)

Benutzer-Import Konfiguration (import.*, user.*)

Verhalten beim Benutzer-Import (import.user=true)

• Benutzer werden als extern markiert.
• Das Passwort von nicht-Administrator-Benutzern wird auf einen leeren String gesetzt (Login nur über OIDC möglich).
• Das Passwort des Administrator-Benutzers (Admin) wird nicht verändert, damit ein lokaler Login weiterhin möglich bleibt.
• Bei jedem Login werden die Benutzereigenschaften (Name, E-Mail, Gruppen etc.) aktualisiert.

Gruppen-Mapping (group.*)

Variablenersetzung

Konfigurationswerte in fs-oidc.conf unterstützen Variablenersetzung. Variablen haben die Syntax ${namespace:name} und werden zur Laufzeit aufgelöst.

OIDC-Claims (${oidc:*})

OIDC-Variablen werden aus den Claims des ID Tokens und der UserInfo-Antwort befüllt. UserInfo-Claims haben dabei Vorrang vor JWT-Claims, das heißt, wenn ein Claim sowohl im ID Token als auch in der UserInfo-Antwort vorhanden ist, wird der Wert aus der UserInfo-Antwort verwendet.

Standard-JWT-Variablen

OIDC Standard-Claims

Alle OIDC Standard Claims und JWT Registered Claims können über ${oidc:claimName} referenziert werden.

Häufig verwendete Claims:

Spezial-Variable für Gruppen-Mapping

FirstSpirit-Eigenschaften (${fs:*})

FirstSpirit-Server-Properties können über ${fs:propertyName} referenziert werden. Der Wert wird aus der Server-Konfiguration (fs-server.conf) gelesen.

Beispiel:

rp.redirectUri=https://${fs:SYMBOLIC_HOSTNAME}/fs5/auth

→ Liest den Wert der Server-Property SYMBOLIC_HOSTNAME aus der FirstSpirit-Server-Konfiguration aus.

HTTP-Request-Variablen (${request:*})

Diese Variablen sind nur im Authorization Code Flow verfügbar, da dort ein HTTP-Request vorliegt.

Empfehlung für Reverse-Proxy-Setups

Verwenden Sie ${request:PROXY} oder ${request:FORWARDED} für rp.redirectUri, damit die Redirect-URI die externe (öffentliche) URL des Servers enthält:

# Für Reverse Proxys mit X-Forwarded Headern:
rp.redirectUri=${request:PROXY}

# Für Reverse Proxys mit RFC 7239 Forwarded Header:
rp.redirectUri=${request:FORWARDED}

Standard-Ports (80 für HTTP, 443 für HTTPS) werden in der generierten URL automatisch weggelassen.

Provider-Metadaten und Caching

Das Modul benötigt die Metadaten des OpenID-Providers (Endpoints, unterstützte Algorithmen, Scopes etc.). Diese können auf drei Arten bereitgestellt werden.

Auto-Discovery

Wenn op.metadata leer ist, wird die automatische Discovery verwendet. Das Modul ruft die Standard-URL {op.issuer}/.well-known/openid-configuration ab.

Dies ist die empfohlene Methode, da die Metadaten immer aktuell sind.

Statische Metadaten (Datei oder URL)

Alternativ kann op.metadata wie folgt gesetzt werden:

• Datei: Ein Dateiname (ohne Pfad) im Konfigurationsverzeichnis {FS-Install}/conf/fs-oidc/. Die Datei muss das JSON-Format der OpenID-Provider-Metadaten enthalten. Dateien können über den Upload-Button in der ServerManager-GUI hochgeladen werden.
• URL: Eine URL, die mit http: oder https: beginnt. Das Modul ruft die Metadaten von dieser URL ab.

# Datei im Konfigurationsverzeichnis:
op.metadata=provider-metadata.json

# URL:
op.metadata=https://idp.example.com/.well-known/openid-configuration

Cache-Konfiguration

Provider-Metadaten werden gecacht um wiederholte HTTP-Anfragen zu vermeiden. Die Cache-Dauer wird in folgender Priorität bestimmt:

• Konfigurations-Wert: op.metadata.cacheTime in Sekunden (wenn gesetzt)
• HTTP Cache-Control Header: max-age-Direktive aus der HTTP-Antwort
• HTTP Expires Header: Ablaufzeitpunkt aus der HTTP-Antwort
• Kein Caching: Wenn keine der obigen Informationen verfügbar ist

Für statische Metadaten aus einer Datei beträgt die Standard-Cache-Dauer 10 Minuten.

Beispiel:

# Metadaten 1 Stunde cachen: 
op.metadata.cacheTime=3600

JAAS-Konfiguration

Die Login-Module werden in der JAAS-Konfigurationsdatei fs-jaas.conf (Standardpfad: {FS-Install}/conf/fs-jaas.conf) konfiguriert. Jedes Login-Modul wird mit seinem vollqualifizierten Klassennamen und einem Control-Flag eingetragen.

Authorization Code Flow

fs5 { 
     com.crownpeak.firstspirit.auth.oidc.OidcAuthLoginModule sufficient; 
};

Dieses Login-Modul kann nur für browserbasierte Clients verwendet werden, die HTTP-Redirects unterstützen.

Da das Modul einen HTTP-Redirect auf den IdP durchführt, sollte es immer an letzter Stelle in der jeweiligen JAAS-Konfiguration mit dem Wert sufficient stehen. Für die anderen Login-Flows gilt diese Einschränkung nicht.

Password Flow

fs5 { 
     com.crownpeak.firstspirit.auth.oidc.OidcPassLoginModule sufficient; 
};

Dieses Login-Modul wird für SiteArchitect, ServerManager und CLI-Zugriffe (fs-cli) verwendet.

Token Exchange Flow

fs5 { 
     com.crownpeak.firstspirit.auth.oidc.OidcTokenLoginModule sufficient; 
};

Kombination mehrerer Flows

In der Regel werden mehrere Login-Module kombiniert, um verschiedene Client-Typen zu unterstützen. Die Module werden in der angegebenen Reihenfolge aufgerufen. Das Control-Flag sufficient bewirkt, dass die Verarbeitung bei erfolgreicher Authentifizierung durch ein Modul stoppt.

fs5 { 
      com.crownpeak.firstspirit.auth.oidc.OidcAuthLoginModule sufficient;
      com.crownpeak.firstspirit.auth.oidc.OidcPassLoginModule sufficient; 
};

Typische Konfiguration mit Fallback auf lokale Authentifizierung

fs5 { 
      com.crownpeak.firstspirit.auth.oidc.OidcPassLoginModule sufficient; 
      de.espirit.firstspirit.server.authentication.FSUserLoginModule optional; }
;

websso { 
     de.espirit.firstspirit.server.authentication.FSTicketLoginModule sufficient;
     de.espirit.firstspirit.server.authentication.FSUserLoginModule optional;
     com.crownpeak.firstspirit.auth.oidc.OidcAuthLoginModule sufficient; 
};

Im Block fs5 wird zuerst der Password Flow (CLI/API) und anschließend das lokale FirstSpirit-Login versucht. Der websso-Block wird für browserbasierte Clients verwendet: Zuerst wird ein vorhandenes Ticket geprüft, dann das lokale Login und zuletzt der Auth-Code-Flow mit Redirect zum IdP. Dadurch bleibt ein Login mit lokalen FirstSpirit-Zugangsdaten (z. B. Admin) möglich.

Verwendung von Sektionen

Über die Option section kann jedes Login-Modul auf eine bestimmte Sektion in der fs-oidc.conf verwiesen werden. So können die Flows unterschiedlich konfiguriert werden, obwohl sie dieselbe Konfigurationsdatei nutzen:

fs5 { 
      com.crownpeak.firstspirit.auth.oidc.OidcAuthLoginModule sufficient section="auth"; 
      com.crownpeak.firstspirit.auth.oidc.OidcPassLoginModule sufficient section="pass"; 
};

In diesem Beispiel verwendet der Auth Code Flow die Sektion [auth] und der Password Flow die Sektion [pass] aus der fs-oidc.conf. Werte, die in der jeweiligen Sektion nicht gesetzt sind, werden aus [default] übernommen.

Wenn keine section angegeben ist, wird automatisch die Standard-Sektion benutzt.

Konfigurationsbeispiel - Keycloak

Voraussetzungen bei Keycloak

1. Erstellen Sie einen neuen Client in Ihrem Keycloak Realm.
2. Setzen Sie Client authentication auf On (Confidential).
3. Aktivieren Sie Standard flow (Authorization Code) und optional Direct access grants (Password Flow).
4. Fügen Sie die Redirect-URI hinzu, z. B. https://firstspirit.example.com/*.
5. Optional: Erstellen Sie einen Client-Scope groups mit einem Mapper vom Typ Group Membership, der den Claim groups erzeugt.
   

Konfiguration

fs-oidc.conf

[default]
op.issuer=https://keycloak.example.com/realms/myrealm
op.scopes=openid, profile, email, phone, groups

rp.clientId=firstspirit
rp.clientSecret=IHR_CLIENT_SECRET

import.user=true
user.login=${oidc:preferred_username}
user.email=${oidc:email}
user.phone=${oidc:phone_number}
user.abbreviation=${oidc:preferred_username}
user.realname=${oidc:name}
user.groups=${oidc:groups}
user.section=${oidc:sub} ${oidc:exp}

group.match.mode=contains
group.name=${oidc:groupName}

[auth]
rp.redirectUri=${request:PROXY}

fs-jaas.conf

fs5 { 
      com.crownpeak.firstspirit.auth.oidc.OidcPassLoginModule sufficient;
      de.espirit.firstspirit.server.authentication.FSUserLoginModule optional; 
}; 

websso { 
     de.espirit.firstspirit.server.authentication.FSTicketLoginModule sufficient;
     de.espirit.firstspirit.server.authentication.FSUserLoginModule optional;
     com.crownpeak.firstspirit.auth.oidc.OidcAuthLoginModule sufficient section="auth"; 
};

Fehlererkennung und -behebung

Login schlägt fehl

Redirect-URI-Probleme

Token-Validierungsfehler

Logging und Debug-Ausgaben

Das Modul verwendet das FirstSpirit-Logging-Framework. Für detaillierte Debug-Ausgaben aktivieren Sie das Debug-Logging für die folgenden Pakete:

• com.crownpeak.firstspirit.auth.oidc: Login-Modul und Konfiguration
• com.crownpeak.firstspirit.auth.oidc.impl: Flow-Implementierungen
• com.crownpeak.firstspirit.auth.oidc.nimbus: OIDC/OAuth-Operationen (Token-Requests, Metadaten, Validierung)

Im Debug-Modus werden unter anderem folgende Informationen ausgegeben:

• Provider-Metadaten (Endpoints, unterstützte Algorithmen)
• Authentication Request URLs
• JOSE-Header und JWT-Claims des ID-Tokens
• UserInfo-Antworten
• Warnungen bei unbekannten oder fehlenden Claims/Variablen

Debug-Logging kann sensible Daten (Tokens, Claims) im Log ausgeben. Aktivieren Sie es nur temporär zur Fehleranalyse und deaktivieren Sie es anschließend wieder.