The Platform's Dataspace Concept

The dataspace concept on the CIVITAS/Core platform provides a fine-grained approach for managing user access across various platform components (e.g., FROST, Superset, Stellio, Geoserver). Dataspaces are thematic areas that contain specific data and resources in different components.

Access rights on the platform are dataspace-specific. Based on the concepts of users, groups, roles, and permissions, users are assigned access rights specific for each dataspace.

Dataspaces can be visualized as silos. Data can then be stored in exactly one dataspace and users are assigned access to the dataspace via dataspace-specific roles on different platform components (e.g., dashboards in Superset, APIs in FROST).

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 dataspace 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 dataspace. Permissions are assigned within roles.
  • A permission can be assigned to one or multiple roles.
• Dataspace: A thematic area containing specific data and resources. Roles within a dataspace control what users and groups can do within that dataspace.
  • A dataspace 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
• Dataspace: yellow

Example Dataspace 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 dataspace called 'Soil Moisture'.

The 'Soil Moisture' dataspace 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 dataspace 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 dataspace.

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 dataspace 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 dataspace-specific access rights with Keycloak

Keycloak manages access to dataspaces through all platform components using Realms, Clients, Roles, Users, and Groups. Each dataspace 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 dataspaces are contained in a single realm.
• Client: Represents any platform component, e.g. FROST, 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 dataspace.
• Role Mapping: Assigning roles to users or groups, allowing dataspace-specific roles to control access.

Dataspaces in different platform components

In the following chapters, we explore how the platform's dataspace concept is implemented across different platform components.

Each component of the platform, e.g., FROST or Superset, implements its own interpretation of the dataspace model, aligning with the core functionality of the component.

With Keycloak being used for identity management across all platform components, dataspace-specific roles are configured there and then mapped to the functionality and entities of the individual platform components.

Depending on the interpretation of the dataspace 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 dataspace configuration: How the key entities of the platform are organized into dataspaces 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