From 1ef26a3308f75dff34963f9276ea50fe38b20dd4 Mon Sep 17 00:00:00 2001 From: Hylke van der Schaaf Date: Wed, 29 Jan 2025 12:07:30 +0100 Subject: [PATCH] [Docs] Updated Projects plugin documentation --- docs/extensions/DataModel-Projects.md | 53 ++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/extensions/DataModel-Projects.md b/docs/extensions/DataModel-Projects.md index ae99d9e65..c7ab3d3f2 100644 --- a/docs/extensions/DataModel-Projects.md +++ b/docs/extensions/DataModel-Projects.md @@ -51,7 +51,14 @@ Users can have project-roles. Users are linked to a Project with a certain Role The `UserProjectRoles` entity type is only visible to admin users. -Users without a global "read" role, but with a project-related "read" role can only read Observations that have a Datastream that has a Thing that is linked to a Project that the user is in. +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. @@ -59,6 +66,32 @@ When not explicitly specified, these Entities will *not* be restircted by defaul **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](https://fraunhoferiosb.github.io/FROST-Server/settings/auth.html#settings-for-the-auth-provider-class-basicauthprovider) 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](https://fraunhoferiosb.github.io/FROST-Server/settings/auth.html#settings-for-the-auth-provider-class-keycloakauthprovider) 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 @@ -67,6 +100,24 @@ The image below shows the core STA data model in blue, with the security extensi ![Data Model](../images/Datamodel-SensorThingsApi-Projects.drawio.png) +## Example Data + +An example JSON-Batch document is [available](https://github.com/hylkevds/FROST-Server.Plugin.Projects/blob/main/scripts/dataBatchPost.json). +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: