SSO-Integration: Keycloak mit dem MB connect line Portal konfigurieren

Startseite > Produktspezifische Hilfe > RSP Remote Service Portal > SSO-Integration: Keycloak mit dem MB connect line Portal konfigurieren

SSO-Integration: Keycloak mit dem MB connect line Portal konfigurieren

Dieser Artikel beschreibt die Schritte zur Konfiguration von Single Sign-On (OpenID Connect) zwischen einer beliebigen Keycloak-Instanz und dem MB connect line Gatekeeper-Portal.

Gilt für: • RSP • RSP.virtual
 Voraussetzungen 

  • Keycloak-Instanz (Version 20+) mit HTTPS

  • Zugang zur Keycloak Admin Console

  • Zugang zum Portal-Backend als Administrator

  • SSO-Lizenzierung im Portal aktiv

  • Netzwerkzugang vom Portal-Server zur Keycloak-Instanz (Server-to-Server, Port 443)

    • DNS-Auflösung muss auf dem Portal-Server funktionieren

    • Firewalls müssen die Verbindung erlauben

Keycloak vorbereiten

Schritt 1: Realm-URL ermitteln

Die Basis-URL eines Keycloak-Realms hat folgendes Format:

https://<keycloak-host>/realms/<realm-name>

Im Folgenden wird <REALM_URL> als Platzhalter für diese Basis-URL verwendet.

 

Schritt 2: OIDC Discovery prüfen

Jeder Keycloak-Realm stellt automatisch einen Discovery-Endpoint bereit:

<REALM_URL>/.well-known/openid-configuration

Dieser liefert alle Endpoint-URLs. Prüfen Sie die Erreichbarkeit:

curl -s <REALM_URL>/.well-known/openid-configuration | jq .

Aus der Antwort benötigen Sie:

Discovery-Feld Portal-Einstellung
issuer Domain (ISS)
authorization_endpoint Authorization Endpunkt
token_endpoint Secure Token Endpunkt / Refresh Token Endpunkt
jwks_uri JWKS Metadata Endpunkt

 

Schritt 3: Client anlegen

In der Keycloak Admin Console unter Clients > Create client:

Einstellung Wert Erklärung
Client type OpenID Connect  
Client ID frei waehlbar (z.B. portal-sso) Wird im Portal als "Client ID" eingetragen
Client authentication On Confidential Client — erzeugt ein Client Secret
Authorization Off UMA/Fine-grained Auth nicht benötigt
Standard flow An Authorization Code Flow (Pflicht)
Direct access grants Optional Nur für Tests nützlich (Password Grant)
Service account roles Optional Nur wenn Client Credentials Grant benötigt
Implicit flow Aus Veraltet, nicht benötigt

Nach dem Speichern finden Sie das Client Secret unter dem Tab Credentials.

 

Schritt 4: Redirect-URI konfigurieren

Unter dem Tab Settings des Clients:

Einstellung Wert
Valid redirect URIs <https://<portal-host>>/portal/index.php?option=com_sso
Web origins <https://<portal-host>>
Hinweis:

Für Testzwecke kann * als Redirect-URI eingetragen werden. In Produktion sollte die URI immer eingeschränkt werden.

 

Schritt 5: Signatur-Algorithmus prüfen

Unter Clients > \ > Advanced > Fine Grain OpenID Connect Configuration:

Einstellung Empfohlener Wert
ID Token Signature Algorithm RS256 (Default)
Access Token Signature Algorithm RS256 (Default)
Achtung:

Bitte verwenden Sie RS256, nicht HS256. Das Portal verifiziert Tokens über den JWKS-Endpoint (Public Key). Bei HS256 scheitert die Verifikation mit "unable to lookup correct key", da JWKS nur öffentliche Schlüssel enthält.

 

Schritt 6: Benutzer anlegen

Unter Users > Add user einen Benutzer erstellen. Pflichtfelder:

  • Username (wird als preferred_username im JWT ausgegeben)

  • Email (wird als email im JWT ausgegeben)

  • First name + Last name (werden als name, given_name, family_name ausgegeben)

  • Email verified: An

Setzen Sie unter dem Tab Credentials ein Passwort.

Hinweis:

Stellen Sie sicher, dass der Benutzer die Default-Realm-Rollen hat (normalerweise automatisch), damit die Keycloak Account Console funktioniert.

 

Portal konfigurieren

Im Portal-Backend

Schritt 1: Navigieren Sie zum Bereich: Zugriff

Feld Wert Quelle
Aktiv Ja  —
Client ID <Ihr Client ID>  Keycloak: Client ID (Schritt 3)
Client Secret <Ihr Secret>  Keycloak: Clients > Credentials
Domain (ISS) <REALM_URL>  Discovery: issuer 
JWKS Metadata Endpunkt <REALM_URL>/protocol/openid-connect/certs  Discovery: jwks_uri 
Authorization Endpunkt <REALM_URL>/protocol/openid-connect/auth  Discovery: authorization_endpoint
Secure Token Endpunkt <REALM_URL>/protocol/openid-connect/token  Discovery: token_endpoint 
Refresh Token Endpunkt <REALM_URL>/protocol/openid-connect/token  Gleiche URL wie Token Endpunkt
Scope openid profile email Leerzeichengetrennt
Achtung:

  • Tragen Sie alle URLs vollständig ein und kürzen Sie diese nicht ab.

  • Geben Sie den Scope leerzeichengetrennt ein und setzen Sie kein Komma dazwischen.

 

Schritt 2: Navigieren Sie zum Bereich: Sicherheit

Feld Wert
Auth Typ Code
Grant Typ Authorization Code
Algorithmus RS256

 

Schritt 3: Navigieren Sie zum Bereich: Standard-Benutzerdaten

Diese Felder bestimmen, aus welchem JWT-Claim das Portal den Benutzernamen und die E-Mail-Adresse liest. Der Wert muss einem gültigen Claim-Namen aus dem id_token entsprechen.

Feld Empfohlener Wert Alternativen Beschreibung
Benutzerinfo: Feld für Namen name given_name, preferred_username, family_name Bestimmt den Anzeigenamen im Portal
Benutzerinfo: Feld für E-Mail email  — Primärer Identifikator für die User-Zuordnung
Achtung:

Der konfigurierte Feldname muss exakt dem Claim-Namen im JWT entsprechen.
Keycloak nutzt die Standard-OIDC-Claim-Namen (z.B. name, given_name),
nicht firstName, lastName oder ähnliches.
Bei falschem Mapping schlägt die Integration fehl.

 

Verifizierung

Schritt 1: Schnelltest mit curl

Prüfen Sie ob der Keycloak-Server vom Portal-Server erreichbar ist:

# Auf dem PORTAL-SERVER ausführen: 

curl -v https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration

Erwartetes Ergebnis: HTTP 200 mit JSON-Response. Bei Fehlern prüfen Sie bitte:

  • DNS-Auflösung (nslookup <keycloak-host>)

  • TLS-Zertifikat (muss vom Portal-Server vertraut werden)

  • Firewall (Port 443 offen)

 

Schritt 2: Token-Anfrage testen

curl -s -X POST "<REALM_URL>/protocol/openid-connect/token" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=<client-id>" \
  --data-urlencode "client_secret=<client-secret>" \
  --data-urlencode "username=<username>" \
  --data-urlencode "password=<password>" \
  --data-urlencode "scope=openid profile email" | jq .

Erwartete Antwort:

{
  "access_token": "eyJ...",
  "id_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "openid profile email"
}

Hinweis:

Wenn id_token fehlt, ist openid nicht im Scope.

 

Schritt 3: id_token prüfen

Den Payload eines JWT dekodieren (ohne Signaturprüfung):

echo "<id_token>" | cut -d. -f2 | base64 -d 2>/dev/null | jq .

Erwartete Claims:

{
  "iss": "<REALM_URL>",
  "aud": "<client-id>",
  "name": "Max Mustermann",
  "email": "max@example.com",
  "email_verified": true,
  "given_name": "Max",
  "family_name": "Mustermann",
  "preferred_username": "maxm"
}

 

Aktualisiert:

Anderer Artikel