Projects Data Model Plugin

A fine-grained security definition for FROST-Server, based on Projects.

Users, Projects, Roles, UserProjectRoles

Users are actors that can log in. Users are stored in the USERS table. Test users are:

read
write
admin

The Users entity type is visible to all users, but normal users can only see their own User entry. Only global-admin users and project-admin users can see all users. Password are not visible to anyone, not even to admin users.

Users can change their own password.

Roles embody sets of permissions that a user can have. Roles are stored in the ROLES table. Test roles are:

read
create
obscreate
update
delete
admin

The Roles entity type is only visible to admin users.

Users can have global Roles. The global roles are stored in the USER_ROLES table that directly links Users to Roles.

A global admin user is allowed to do everything.
A user with a global “create” role is allowed to create all entity types except for Users and admin-only types (Roles, UserProjectRoles).
A user with a global “read” role can read all entities, except for other User entities or admin-only types.

Projects are administrative entities grouping data (through Things). Projects are stored in the PROJECTS table. Projects can be public or private. Public projects, and their associated Things, Datastreams, etc., can be read by everyone. Private projects, and their associated Things, Datastreams, etc., can only be read by users associated to the project.

Users can have project-roles. Users are linked to a Project with a certain Role through the USER_PROJECT_ROLE table.

UserProjectRoles Link a User with a specific Role to a Project. A User can have multiple Roles in the same Project.

The UserProjectRoles entity type is only visible to admin users.

Users without a global “read” role, but with a project-related role can only read entities associated with a project they are related to.

Linking entities to Projects

Things, Locations, Sensors and FeaturesOfInterest link directly to one or more Projects. Datastreams link to Projects through their Thing. Observations link to Projects through their Datastream.

Things, Locations, Datastreams and FeaturesOfInterest can be restricted. This means that even if they are associated with a public project, they can still only be read by users associated to that project. When not explicitly specified, these Entities will not be restircted by default.

Locations and FeaturesOfInterest have their normally hidden link exposed, that indicates that a FeatureOfInterest is autogenerated for a specific Location. This means that, when creating a Location, the FeatureOfInterest that will be used for Obserations that do not specify one, can directly be created as well. Automatically generated FeaturesOfInterest inherit their restricted setting and Project links from the Location the Feature is generated from, at the time of generation.

Auth Providers

Users, Roles and the links between those and Projects need to come from somewhere, and a client making a request needs to be able to authenticate as one of those users. These two processes are flexible and depend on the deployment. Creating users and linking users to Roles and Projects can be done from fully manual to fully automatic.

Logging in users is handled by an Auth Provider. FROST-Server comes with following two out of the box: Basic Auth and KeyCloak Auth.

Basic Auth

When using Basic Authentication the user/password table and the role mapping of users to roles are maintained in the SensorThings database. The Users and Roles tables are exposed through the API, and users can change their password using the API. Global admins can create users, links users to roles and to projects. Project admins can link users to projects.

KeyCloak Auth

When using KeyCloak Authentication the contents of the user and roles tables are automatically filled from the data supplied by KeyCloak. The links between Projects and Users/Roles can also be decoded from the KeyCloak data, by using a userRoleDecoder.

Data Model

The image below shows the core STA data model in blue, with the security extension in yellow.

Data Model

Example Data

An example JSON-Batch document is available. When posting this Batch to v1.1/$batch it will create several Projects, User, Roles and STA entities linked to the Projects.

Project

A new project can be created by posting to v1.1/Projects:

{
    "name": "Project 1",
    "description": "The first, public, test project",
    "public": true
}

Conformance Class

The conformance class this extension must register in the SensorThings (v1.1 and up) index document is:

https://fraunhoferiosb.github.io/FROST-Server/extensions/DataModel-Projects.html