Keycloak

Mithilfe des OAuth 2.0 Protokolls kann map.apps die Authentifizierung von Personen an Keycloak delegieren. Dies bedeutet, dass diese sich mit ihrem Keycloak-Account bei map.apps anmelden können.

Durch eine Verbindung mit Keycloak entstehen folgende Möglichkeiten:

  • Vergabe von Rollen für die Nutzung des map.apps Managers

  • Absicherung von Apps

  • Absicherung von Werkzeugen

Durch eine Verbindung mit Keycloak kommt es zu folgenden Einschränkungen:

  • Mit der Funktion "Export für native Apps" exportierte Apps unterstützen keine Authentifizierung. Apps mit anonymem Zugriff funktionieren weiterhin.

Verbindung zwischen map.apps und Keycloak herstellen

Die Verbindung von map.apps mit Keycloak erfolgt in drei Schritten:

  1. Zuerst registrieren Sie map.apps als Client in Keycloak.

  2. Danach passen Sie die Konfiguration von map.apps an, damit map.apps die Anmeldung an Keycloak delegieren kann.

  3. Letztlich konfigurieren Sie ihre Apps, um die Anmeldung an Keycloak nutzen zu können.

Die nachfolgende Beschreibung basiert auf der Version 20.0.1 von Keycloak.

Schritt 1: map.apps in Keycloak als Client registrieren

map.apps muss in Keycloak als Client registriert werden, um die Anmeldung an map.apps mit einem von Keycloak verwalteten Account zu ermöglichen.

Der Client wird in einem sogenannten Realm definiert. Es wird vorausgesetzt, dass bereits ein Realm eingerichtet worden ist.

Für einen Client stehen umfangreiche Konfigurationsparameter zur Verfügung. Es wird davon ausgegangen, dass Parameter, die nachfolgend nicht beschrieben sind, eine passende Standardbelegung haben.

Gehen Sie wie folgt vor, um map.apps als Client zu registrieren:

Einen Client anlegen

  1. Melden Sie sich in der Administrationskonsole von Keycloak mit einem Administrator-Account an.

  2. Wählen Sie den gewünschten Realm aus.

  3. Wählen Sie Clients.

  4. Klicken Sie auf Create Client, um einen neuen Client zu erstellen.

  5. Verwenden Sie die folgenden Einstellungen im Tab General Settings:

    • Client type: OpenID Connect

    • Client ID: mapapps

  6. Klicken Sie auf Next

  7. Verwenden Sie die folgenden Einstellungen im Tab Capability config:

    • Client authentication: On

    • Standard flow: On

  8. Klicken Sie auf Save. Das Tab Settings des neu angelegten Clients wird angezeigt.

  9. Verwenden Sie die folgenden Einstellungen, um den Client weiter zu konfigurieren:

    • Root URL: URL der map.apps Installation, z.B. https://example.com/mapapps

    • Valid redirect URIs: Geben Sie den account-Pfad von map.apps an, z.B. https://example.com/mapapps/account/*

    • Front channel logout: Off

    • Backchannel logout URL: Geben Sie den logout-Endpunkt von map.apps an, z.B. https://example.com/mapapps/account/logout

  10. Klicken Sie auf Save

  11. Wechseln Sie zum Tab Credentials.

    • Merken Sie sich den Wert im Feld Client secret an beliebiger Stelle. Der Wert wird später für die Konfiguration von map.apps benötigt.

Rollen hinzufügen

map.apps verwendet die folgenden Rollen, um Personen zu authentifizieren:

  • maAdmin: Personen mit dieser Rolle können map.apps administrieren.

  • maEditor: Personen mit dieser Rolle können in map.apps Apps editieren.

Legen Sie diese Rollen nun wie folgt in Keycloak an:

  1. Wechseln Sie in der Ansicht des Clients zum Roles Tab.

  2. Fügen Sie dort die Rollen maAdmin und maEditor per Click auf Create role hinzu.

Mapper anlegen

map.apps verwendet den User Information Endpunkt von Keycloak, um Rollen von Personen abzufragen. Durch die Anlage eines Mappers stellen Sie sicher, dass die zuvor angelegten Rollen beim Zugriff auf diesen Endpunkt auch zurückgeliefert werden.

Gehen Sie wie folgt vor, um einen Mapper anzulegen:

  1. Wechseln Sie zur Ansicht Client scopes.

  2. Klicken Sie auf den Eintrag roles des OpenID Connect Protokolls.

  3. Wechseln Sie in der folgenden Ansicht roles zum Tab Mappers.

  4. Klicken Sie auf Add mapper und anschließend auf By configuration.

  5. Wählen Sie das Mapping vom Typ User Client Role aus.

  6. Die Konfiguration des Mappers wird angezeigt.

  7. Verwenden Sie nun die folgenden Einstellungen für den neuen Mapper:

    • Mapper Type: User Client Role

    • Name: mapapps client role mapper

    • Client ID: Selektieren Sie mapapps aus der Client-Liste.

    • Client Role prefix: Lassen Sie dieses Feld leer.

    • Multivalued: ON

    • Token Claim Name: roles

    • Claim JSON Type: String

    • Add to userinfo: ON

  8. Klicken Sie auf Save.

Die Konfiguration des Clients ist nun abgeschlossen.

Zuordnung von Rollen

Ordnen Sie nun die zuvor angelegten Rollen denjenigen Personen bzw. Gruppen zu, die map.apps editieren oder administrieren können sollen.

Um beispielsweise Rollen zu einer Person hinzuzufügen, gehen Sie wie folgt vor:

  1. Klicken Sie auf Users in der Navigation von Keycloak.

  2. Wählen Sie einen User aus. Die Detailseite des Users wird angezeigt.

  3. Wechseln Sie in das Tab Role mapping.

  4. Klicken Sie auf den Button Assign role.

  5. Setzen Sie den Filter auf Filter by clients.

  6. Selektieren Sie aus den angezeigten Rollen diejenigen Rollen, die der Person zugewiesen werden sollen.

  7. Klicken Sie auf Assign.

  8. Eine Meldung über die erfolgreiche Aktualisierung sollte angezeigt werden.

  9. Die zugewiesene Rolle sollte in der Liste der Rollen des Users sichtbar sein.

Nachdem Sie die Rollen zugewiesen haben, können Sie mit dem nächsten Schritt, der Konfiguration von map.apps, fortfahren.

Schritt 2: map.apps konfigurieren

Die folgenden Parameter müssen in der map.apps Konfiguration ergänzt oder geändert werden.

Beispiel-Konfiguration
security.mode=OAUTH
security.oauth.provider=keycloak
# Die nachfolgende URL hängt von der Version von Keycloak ab.
# Siehe Beschreibung des Parameters
security.oauth.provider.keycloak.url=http://keycloak.example.com
security.oauth.provider.keycloak.realm=yourrealm
security.oauth.clientId=mapapps
security.oauth.clientSecret=NJrrsZXVm8CvnhF7owT6m50CXhbnN55w
# Ersetzen Sie "0123456789" durch eine beliebige Zeichenkette mit mindestens 32 Zeichen
security.sharedSecret=0123456789
security.mode

Der Wert OAUTH legt fest, dass das OAuth 2.0 Protokoll zur Authentifizierung verwendet werden soll.

security.oauth.provider

Der Wert keycloak legt Keycloak als OAuth-Provider fest.

security.oauth.provider.keycloak.url

URL der Keycloak-Installation z.B. http://keycloak.example.com.

Wenn Sie Keycloak in der Version 16 oder früher verwenden, müssen Sie /auth an den Pfad anhängen, z.B. so http://keycloak.example.com/auth.

security.oauth.provider.keycloak.realm

Name des Realm.

security.oauth.clientId

ID des Clients, der im ersten Schritt in Keycloak angelegt worden ist.

security.oauth.clientSecret

Wert des Feldes Secret des Clients.

Der Wert wird im Tab Credentials eines Clients in Keycloak angezeigt.

security.sharedSecret

Der Text, den Sie hier eintragen, wird von map.apps als Schlüssel ("shared secret") für die Verschlüsselung von Daten verwendet, die zwischen verschiedenen Anwendungsteilen ausgetauscht werden müssen. Um unautorisierten Zugriff oder die Manipulation von Daten zu verhindern muss der Schlüssel so vertraulich wie ein Passwort behandelt werden. Sie müssen diesen Schlüssel selbst erstellen. Er muss aus Sicherheitsgründen mindestens eine Länge von 32 Zeichen haben.

Einen sicheren Schlüssel erzeugen Sie beispielsweise mit diesen Kommandos:

Windows PowerShell
> [Convert]::ToBase64String((1..32|%{[byte](Get-Random -Minimum ([byte]::MinValue) -Maximum ([byte]::MaxValue))}))
Linux
$ openssl rand -base64 32

In einem Szenario, in dem z.B. zwecks Lastverteilung mehrere Anwendungsinstanzen zum Einsatz kommen, müssen alle Instanzen denselben Wert verwenden.

Schritt 3: Apps konfigurieren

Fügen Sie abschließend das Bundle authentication zu jeder App hinzu, in der eine Anmeldung über Keycloak erfolgen soll.