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.

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, um einen neuen Client zu erstellen. Verwenden Sie die folgenden Einstellungen:

    • Client ID: mapapps

    • Client Protocol: openid-connect

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

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

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

    • Access Type: confidential

    • Standard Flow Enabled: ON

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

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

  7. Klicken Sie auf Save

  8. Wechseln Sie zum Tab Credentials.

    • Merken Sie sich den Wert im Feld 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 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 in der Ansicht des Clients zum Tab Mappers.

  2. Klicken Sie auf Create, um einen Mapper anzulegen.

  3. Verwenden Sie die folgenden Einstellungen:

    • Name: mapapps client role mapper

    • Mapper Type: User Client Role

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

    • Client Role prefix: Lassen Sie dieses Feld leer.

    • Token Claim Name: roles

    • Claim JSON Type: String

    • Multivalued: ON

    • Add to userinfo: ON

  4. 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 Mappings.

  4. Selektieren Sie aus der Liste Clients Roles den Eintrag mapapps.

  5. Selektieren Sie aus dem Bereich Available roles die Rolle, die zugewiesen werden soll.

  6. Klicken Sie auf Add selected.

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

  8. Die zugewiesene Rolle sollte im Bereich Assigned Roles 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.