The Platform's Data space Concept
The data space concept on the CIVITAS/CORE platform provides a fine-grained approach for managing user access across various platform components (e.g., FROST-Server, Superset, Stellio, GeoServer). Data spaces are thematic areas that contain specific data and resources in different components.
Access rights on the platform are data space-specific. Based on the concepts of users, groups, roles, and permissions, users are assigned access rights specific to each data space.
Data spaces can be visualized as silos. Data is stored in exactly one data space , and users are assigned access to the data space via data space-specific roles on different platform components (e.g., dashboards in Superset, APIs in the FROST-Server).
Main Entities
In the following, we describe the main entities of the CIVITAS/CORE platform.
- User: Any individual or entity that accesses the platform.
- A user belongs to one or multiple groups.
- A user can have one or multiple roles.
- Group: A collection of users that inherit roles assigned to that group.
- A group can have one or multiple users.
- Role: A set of permissions granted to either a user or group. These roles are specific to each data space and define what actions the user or group can perform.
- A role can be assigned to one or multiple users.
- A role can be assigned to one or multiple groups.
- A role can have one or multiple permissions.
- Permission: Defines the authorization to perform a specific action, such as reading, writing, or administrating resources within a data space. Permissions are assigned within roles.
- A permission can be assigned to one or multiple roles.
- Data space: A thematic area containing specific data and resources. Roles within a data space control what users and groups can do within that data space.
- A data space can have one or multiple roles.
The entities are visualized in the following image. We use this color code to illustrate the mapping of the platform entities to the entities of individual platform components in the following:
- User: green
- Group: blue
- Role: red
- Permission: purple
- Data_space: yellow
Example Data space for Soil Moisture Analysis
A use case for the CIVITAS/CORE platform could be the sustainable irrigation of urban trees using sensor-based demand assessment. For this use case, there may be a data space called 'Soil Moisture'.
The 'Soil Moisture' data space contains all the data and resources related to soil moisture analysis. It requires specific roles that control what users and groups can do with the data across various components of the platform (e.g., dashboards in Superset). The roles within this data space define access rights, for example, to view or edit the soil moisture data.
The 'Soil Moisture' group represents a collection of users with access rights to data and resources related to soil moisture analysis. This group will have assigned roles that grant specific permissions. Hence, a user can have specific roles in the data space.
For example, there may be a role called "Soil_Moisture_Editor." This role grants permissions to edit and update data related to soil moisture analysis and includes the necessary permissions. The "Soil_Moisture_Viewer" role in this data space grants read-only access to the data related to soil moisture analysis.
Let’s take Alice and Bob as examples:
- Alice is a data analyst and works with soil moisture data. For example, she creates charts and dashboards in Superset to visualize the data. She is assigned the "Editor" role, which allows her to edit, delete, and add new records for her analysis.
- Bob also works on the sustainable irrigation of urban trees. He is a project manager and wants to check information, for example, about the sensors used. Therefore, he only needs to view the records and search through the data, but he does not need to modify or delete any information. Hence, he is assigned the "Viewer" role.
Alice's, and Bob's roles hold through each platform component.
Managing data space-specific access rights with Keycloak
Keycloak manages access to data spaces through all platform components using Realms, Clients, Roles, Users, and Groups. Each data space is represented by specific roles in Keycloak, and access is managed through role assignments to users or groups.
Keycloak Entities
- Realm: A "top-level container" that holds all users, roles, groups, and permissions for the platform. Each realm is independent (currently one platform is supported). All data spaces are contained in a single realm.
- Client: Represents any platform component, e.g. FROST-Server, that interacts with Keycloak to authenticate users and collects their roles (see role mapping below) and passes them to the corresponding platform components.
- Realm Role: A role that applies across all clients within a realm, not specific to individual clients.
- Client Role: A client-specific role applied to control access to resources within a specific client.
- Composite Role: A role aggregating other roles (both realm roles and client roles), allowing complex hierarchies.
- User: An entity authenticated and authorized to access platform resources. Users are assigned roles, directly or through group memberships.
- Group: A collection of users. Assigning roles to a group grants all users within that group the assigned roles for the corresponding data space.
- Role Mapping: Assigning roles to users or groups, allowing data space-specific roles to control access.
Data spaces in different platform components
In the following chapters, we explore how the platform's data space concept is implemented across different platform components.
Each component of the platform, e.g., FROST-Server or Superset, implements its own interpretation of the data space model, aligning with the core functionality of the component.
With Keycloak being used for identity management across all platform components, data space-specific roles are configured there and then mapped to the functionality and entities of the individual platform components.
Depending on the interpretation of the data space concept in the different platform components, the entity configuration in Keycloak slightly differs. Additionally, some components require the administration of permissions in the component itself, while others can work directly with the roles defined in Keycloak.
To illustrate this for each component, we explain in the following chapters:
- The data space configuration: How the key entities of the platform are organized into data spaces in Keycloak
- The role management and assignment: How roles are assigned to users through Keycloak and how these roles map to specific permissions in the component
- The permission enforcement: How the component enforces access controls based on the roles defined in Keycloak