[Docs] Updated Projects plugin documentation

docs/extensions/DataModel-Projects.md

@@ -51,14 +51,47 @@ 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.
 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](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: