Keycloak

Keycloak serves as the central hub for managing authentication, authorization, and user-related configurations across the whole platform. It provides comprehensive control over user access, client services, groups, realms, and user management functionalities.

Access Information

• URL: idm.<DOMAIN>
• User: admin@<DOMAIN>

3.1. Authentication Realms

A realm in Keycloak represents a security environment where all the users, credentials, applications, and roles are stored and managed. It acts as a container for managing identity and access control within a specific context or domain.

Keycloak realms provide isolation and segregation of resources, allowing organizations to manage multiple sets of users, applications, and policies independently within different realms. Each realm has its own user database, authentication mechanisms, authorization policies, client applications, and configuration settings.

The realm to be used is identified by the ID of the stage (e.g., tst, dev, prd). This allows the management of different platform installations using a single Keycloak instance. The ID is specified in the inventory (see inventory customization guide).

The master realm is not used for the platform management, it is only used for managing keycloak itself.

Realms are configured in the section Realm settings. To create a new realm, navigate to Realms and create a new realm representing the environment for the platform and dataspaces (e.g., CCPlatformRealm).

The general configuration of the realm is pre-configured by the installation of the platform. If you extend the scope of the platform installation/deployment, the needed configuration objects can be added later by the installation/deployment. Objects that are configured in Keycloak will not be deleted by the installation/deployment scripts. Details about these objects are describe in the following.

3.2. Clients

Keycloak clients are applications or services that utilize Keycloak for authentication and authorization. They can be web apps, mobile apps, or backend services. Clients interact with Keycloak for user authentication, session management, and access control. Keycloak provides various client adapters for different platforms to simplify integration and enforce security policies.

The Clients section displays the pre-configured clients (services) available on the platform. Currently, the "geostack_public" client, designated for the masterportal service, is the only client that allows access without authentication.

Client scopes are predefined sets of permissions that can be assigned to clients. They define access rights and are reusable across clients, simplifying management. Three pre-defined scopes of importance are the api* scopes that add permissions to read, write, and delete on API endpoints.

3.3. Groups

Keycloak groups are logical collections of users that simplify user management in applications. They allow administrators to organize users based on roles, permissions, or any other criteria.

Groups with the attributes service and tenant set to true are utilized for dataspaces (see below). Child groups are currently not used (only applicable for CKAN). To create a new group, navigate to Groups and create a group for each dataspace, such as Dataspace_A, Dataspace_B.

3.4. Events

Keycloak events are notifications triggered by various actions within the Keycloak identity and access management system. These events provide insights into user authentication, authorization, and other system activities, aiding in auditing, monitoring, and security analysis. They cover actions such as login attempts, user creation, role assignments, and more, enhancing visibility and control over the system's operation.

Events such as user logins and administrative changes are automatically activated.

3.5. Themes

Keycloak themes allow customization of the appearance and layout of the Keycloak authentication pages for a specific realm. They include login, registration, and password reset screens.

3.6. User Management

Users are individuals or entities granted access to applications or services on the platform. They're managed centrally, allowing single sign-on across the specific realm. If you use more than one realm, the user must be created in each realm, explicitly.

Users are added via the "Add User" entry, providing email, first name, and last name details. Here roles can be added, too. In addition, the user credentials can be reset.

For a new user this must be performed once. Thereby, the new user receives an email with the tasks that are selected: Normally you choose "confirm_email" and "reset_password". Optionally you can configure, that the user has to add two-factor authentication for the new account.

After configuring the needed tasks, keycloak sends an email to the user with a personalized link, that allows performing the tasks. This user has to perform them in one take - the link is not reusable.

3.6.1. Role Assignment

Users can be assigned specific roles via "Assign Roles". Important roles include

• dataConsumer and dataProducer, granting read and write access respectively on APIs.
• geoAdmin, assigned for specific administrative in the geoserver.
• supersetViewer, supersetEditor, and supersetAdmin to govern access and management of Superset dashboards.
• grafanaViewer, grafanaEditor, and grafanaAdmin to govern access and management of Superset dashboards.

You can assign users to the previously created groups (e.g., Dataspace_A) by accessing the user profile and selecting the appropriate group under Groups. You can use Role Mapping to assign users or groups specific Client Roles** or Realm Roles required for certain dataspaces.