Keycloak verbinden

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

Die Verbindung zu Keycloak erfolgt in mehreren Schritten:
Zuerst registrieren Sie den Identity Service als Client in Keycloak. Danach passen Sie die Konfiguration an, damit die Anmeldung an Keycloak erfolgen kann. Testen Sie dann die Konfiguration, indem Sie sich über den Identity Service bei Keycloak anmelden.

Die nachfolgende Beschreibung basiert auf der Version 21.1.1 von Keycloak.

Schritt 1: Identity Service in Keycloak als Client registrieren

Der Identity Service muss in Keycloak als Client registriert werden, um die Anmeldung 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 den Identity Service als Client zu registrieren:

  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: identity-service

  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 Next.

    • Root URL: URL der Identity Service Installation, z.B. https://www.example.com/identity

    • Valid redirect URIs: Geben Sie den account-Pfad vom Identity Service an, z.B. https://www.example.com/identity/account/*

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

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

    • Front channel logout: Off

    • Backchannel logout URL: (Optional) Geben Sie den logout-Endpunkt vom Identity Service an, z.B. https://www.example.com/identity/account/logout

  11. Klicken Sie auf Save

  12. 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 weitere Konfiguration benötigt.

Schritt 2: Identity Service konfigurieren

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

Beispiel-Konfiguration
# .identity-service/application.properties
security.oauth.provider=keycloak
security.oauth.provider.keycloak.url=http://keycloak.example.com
security.oauth.provider.keycloak.realm=yourrealm
security.oauth.clientId=identity-service
security.oauth.clientSecret=NJrrsZXVm8CvnhF7owT6m50CXhbnN55w
security.oauth.provider

Der Wert keycloak legt Keycloak als Identitätsanbieter fest.

security.oauth.provider.keycloak.url

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

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.

Schritt 3: Rollen einrichten

Möglicherweise müssen Sie mit der Anbindung der Produkte zusätzliche Rollen im Keycloak bereitstellen. Beispielsweise erwartet map.apps die Rolle maAdmin für einen administrativen Nutzer. Diese Rolle muss im Keycloak bekannt gemacht werden.

Rollen hinzufügen

Legen Sie eine Rollen wie folgt in Keycloak an:

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

  2. Fügen Sie dort z.B. die Rolle maAdmin per Click auf Create role hinzu.

Mapper anlegen

Der Identity Service 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: identity-service client role mapper

    • Client ID: Selektieren Sie identity-service 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.

Zuordnung von Rollen

Um 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.

Schritt 4: Konfiguration testen

Sie können die Konfiguration von Keycloak als Identitätsanbieter testen, indem Sie eine Anmeldung über den Identity Service durchführen. Führen Sie dazu folgende Schritte aus:

  1. Stellen Sie sicher, dass Sie einen Account bei Keycloak besitzen.

  2. Falls Sie bei Keycloak angemeldet sind: Melden Sie sich ab.

  3. Öffnen Sie die Basis-URL des Identity Service im Browser, z.B. http://www.example.com/identity oder http://www.example.com:8080/identity. Achten Sie darauf, dass die Basis-URL genau der URL entsprechen muss, die Sie bei der Registrierung der Anwendung in ArcGIS Enterprise-Portal in Schritt 1 dieser Dokumentation als Root URL angegeben haben.

    Der Browser zeigt eine Seite mit der Liste der verfügbaren Dienstendpunkte:

    installation check 01

  4. Klicken Sie auf den Link, der mit Login überschrieben ist. Der Browser leitet Sie auf die Login-Seite von Keycloak um.

  5. Geben Sie Kennung und Passwort für Ihren Keycloak-Account ein, um sich anzumelden.

Nach erfolgreicher Anmeldung werden Sie zurück zum "Self"-Endpunkt des Identity Service geleitet (/identity/account/self), wo Ihre Account-Information als JSON präsentiert werden. In diesem Fall haben Sie Keycloak erfolgreich mit dem Identity Service verbunden.

Nächste Schritte

Nachdem Sie Keycloak als Identitätsanbieter mit dem Identity Service verbunden haben, können Sie Dienste, die mit einem Zugriffstoken angefragt werden müssen, als vertrauenswürdige Dienste konfigurieren. Nur dann können Nutzerinnen und Nutzer von Anwendungen, die den Identity Service nutzen, ohne weitere Anmeldung auf diese Dienste zugreifen.