doc: First draft of users and rights management

docs/admin_guide/index.en.md

@@ -0,0 +1,5 @@
+# Administrator guide
+
+## Table of Contents
+
+TODO: insert Table of contents.

docs/admin_guide/index.fr.md

@@ -0,0 +1,7 @@
+# Guide de l'utilisateur
+
+## Sommaire
+
+sommaire
+
+

docs/admin_guide/users_management/index.en.md

@@ -0,0 +1,21 @@
+# Managing users and access rights in geOrchestra
+
+geOrchestra is composed of several modules, some of which have their own separate life (GeoNetwork, GeoServer, etc). As such the access rights management have their own logic in each of those apps.
+
+geOrchestra tries to make its best in order to provide you a more unified experience: the console provides you with a user management interface extended by a system of *roles*, that are used to define which actions and rights you are allowed to. What each module will do of those roles is at least partially delegated to the modules' own logic. At least for now.
+
+Users and access management relates to the following concepts: 
+
+- [Users](users.md)
+- [Organizations](organizations.md)
+- [Roles](roles.md)
+- [Rights management](rights_management/index.md)
+
+
+## Behind the scenes, how does it work ?
+
+Users, organizations and roles are typically stored in the LDAP instance of your platform.
+
+Some modules, like GeoNetwork, synchronize this information, on a regular basis, with its own internal database. 
+
+When you are logged in the platform, the Single Sign-On (SSO) system remembers it and provides the downstream modules, in each http request, with the information of who you are, what organization you belong to and which roles you have been given. Then the access management is delegated to the downstream module (GeoNetwork, GeoServer etc) according to their own logic.

docs/admin_guide/users_management/index.fr.md

@@ -0,0 +1,24 @@
+# Sommaire
+
+
+Sommaire de la partie Administrer
+
+Cette partie de la documentation est dédiée à l'administration du contenu:
+
+
+-  gestion des données
+-  mise à jour des données
+-  gestion des utilisateurs
+-  ...
+
+
+Mettre les images dans le répertoire `images`.
+
+
+![](images/gestion_donnees.jpg)
+
+
+
+
+
+

docs/admin_guide/users_management/organizations.en.md

@@ -0,0 +1,30 @@
+
+# Organizations
+
+What organizations really represent might depend on your platform.  
+They are entities used to organise people in groups that make sense in the context of your platform.
+
+It is basically assumed that they will represent companies, NGOs, administrations, municipalities etc. Your employer, in a sense. But on some platforms, it may be decided to rather attach users to projects, for instance, or research units. 
+
+## Users and organizations
+A given user can be member of only one organization. This is a design choice.
+
+But be reassured, roles will give you a lot of flexibility in access rights management. See [rights management page](rights_management/index.md).
+
+## Creation of a new organization
+There are two scenarios where an organization can be created:
+
+- When someone is registering a new account. If they don't find a matching organization, they can require the creation of a new organization. In this event, the platform's administrators will be informed by email and asked to validate (or not) the new organization.
+
+![Create a new organisation during self-registration process](images/registration-create-org.jpg)
+
+- A platform administrator can create a new organization from the console admin panel.
+
+![A platform administrator is creating a new organization](images/admin-creates-org.jpg)
+
+### Area of competence
+
+You can select on a map the entities on which the organization is active/ has a competence.
+
+This is a concept that is used on several applications, but not all.  
+Some applications will use this information to filter some privileged accesses. Please see [rights management page](rights_management/index.md).

docs/admin_guide/users_management/rights_management/acl-geoserver.en.md

@@ -0,0 +1,24 @@
+# GeoServer 
+
+## Managing the access to layers and services using geOrchestra roles
+
+TODO: this is a draft. Check and review everything
+
+GeoServer natively supports a very similar system for its security policies, relying on users, groups and roles.  
+Please read the [GeoServer's documentation about Security management](https://docs.geoserver.org/latest/en/user/security/index.html#security) for reference.
+
+With geOrchestra, on GeoServer, users are matched against the LDAP registry and will be available, but you cannot set access rules based on user. You have to rely on roles.
+
+The roles from the geOrchestra console will not be synchronized automatically in the roles list. You will have to create corresponding roles in GeoServer for the role-matching to work. Compared to the console's role names, they will have to be prefixed by `ROLE_`.
+
+Then you can use those roles in the security policy rules.
+
+## Example
+*I want, for my `psc` workspace, to grant people matching the `GS_PSC` role to access to the administration web UI.*
+
+1. I create the `GS_PSC` role in the geOrchestra console, see 
+2. In GeoServer, I create a `ROLE_GS_PSC` role
+3. Still in GeoServer, in security->data policies, I add a rule `psc.*.a` and give it to `ROLE_GS_PSC`
+4. 
+
+TODO: add screenshots

docs/admin_guide/users_management/rights_management/acl-mapstore.en.md

@@ -0,0 +1 @@
+TODO

docs/admin_guide/users_management/rights_management/index.en.md

@@ -0,0 +1,22 @@
+# Rights management
+
+Rights management is done using the [roles](../roles.md) assigned to a [user](../users.md). By creating new roles, you can design more access rules.
+
+This is on a per-applications basis. Some applications are likely to make use of new roles, others not so much.
+
+Here is a list of core applications that can use new roles and how to leverage it:
+
+- [GeoNetwork](acl-geonetwork.md)
+- [GeoServer](acl-geoserver.md)
+- [GeoFence](acl-geofence.md)
+- [MapStore](acl-mapstore.md)
+- [Cadastrapp](https://docs.georchestra.org/cadastrapp/latest/guides_techniques/installer/roles_ldap/)
+
+Some other core applications also can leverage new roles, but require access to the configuration files, which is more technical and usually restricted to sysadmin users. They are documented [in the technical guides](../../../technical_guides/rights_management/index.md).
+
+
+
+TODO:
+
+Area of competence -> privileged accesses in some apps. Document
+

docs/admin_guide/users_management/roles.en.md

@@ -0,0 +1,59 @@
+# Roles
+
+Roles' purpose is to associate users with some permissions in the apps. Users are assigned some roles. And the apps are configured to grant users some permissions based on those roles.
+
+At the core, a role is just a label, stored in the LDAP registry. A role gets useful when an application aknowledges its existence and configures some logic based on the user's belonging or not to that role.
+
+Example: if you assign the `ADMINISTRATOR` and the `GN_EDITOR` to a user, this one will granted
+- admin profile on GeoServer
+- editor profile on GeoNetwork
+
+## Core roles
+On a brand new geOrchestra instance, some core roles are defined and are already used by the applications.
+
+The roles:
+
+ * ```SUPERUSER``` grants access to the console webapp (where one can manage users and roles),
+ * ```ADMINISTRATOR``` is for GeoServer administrators,
+ * ```GN_ADMIN``` is for GeoNetwork administrators,
+ * ```GN_EDITOR``` is for metadata editors,
+ * ```GN_REVIEWER``` is for metadata reviewers,
+ * ```MAPSTORE_ADMIN``` is for MapStore administrators,
+ * ```REFERENT``` allows users to edit their own organisation (basic information only),
+ * ```EMAILPROXY``` allows to use the emailProxy webservice from the console,
+ * ```IMPORT``` allows users to publish data with the importer application (also called datafeeder),
+ * ```ORGADMIN``` is automatically granted to all users holding an admin delegation,
+ * ```USER``` is for the basic SDI users.
+
+Other roles can be defined by the platform administrator, using the console (or directly in the LDAP registry).
+
+## Roles delegation
+TODO
+
+## Using additional roles
+
+### 1. Create a new role
+
+A person having the `SUPERUSER` role has the capacity to create new roles. At this stage, a new role is just a label with a description (optional).
+
+This is done on the console UI, role tab.
+
+![Create a new role](images/create-new-role.jpg)
+
+### 2. Assign a new role to a user
+
+Then, it is possible to assign this new role to users. There are 2 ways to do it, on the console interface: 
+
+- either on the user's profile, in the `roles` tab
+- or in the console's roles tab: open the new role's configuration interface, in the `users` tab, you can select the users.
+
+![Assign a role to users](images/add-users-to-role.jpg)
+
+*Remark*: this second way is more handy when you want to assign the role to several users
+
+### 3. Configure an application to use a new role
+
+This is on a per-applications basis. Some applications are likely to make use of new roles, others not so much.
+
+On the [Rights management](rights_management/index.md) section is a list of core applications that can use new roles and how to leverage it.
+

docs/admin_guide/users_management/users.en.md

@@ -0,0 +1,72 @@
+# Users
+
+In order to access to functionalities beyond public consultation of the platform, you needs to login using a user account. 
+You may already have been provided with such an account by your platform administrator. Or you can ask for the creation of a new account.
+On some platforms, you may also be offered the possibility to connect using an external identity provider like France Connect.
+
+## Sample users
+
+On a brand new deployment, some sample users are predefined: 
+
+ * ```testuser``` has the USER role. The password is **testuser**.
+ * ```testreviewer``` has the USER & GN_REVIEWER roles. The password is **testreviewer**.
+ * ```testeditor``` has the USER & GN_EDITOR roles. The password is **testeditor**.
+ * ```testadmin``` has the USER, GN_ADMIN, ADMINISTRATOR and MOD_\* roles. The password is **testadmin**.
+ * ```testdelegatedadmin``` has the USER role. Is able to grant the EXTRACTORAPP & GN_EDITOR roles to members of the psc & c2c orgs. The password is **testdelegatedadmin**.
+ * ```testpendinguser``` is inside the pending users organizational unit, which means an admin has to validate it. The password is **testpendinguser**.
+
+***Please note that `test*` users should be deleted before going into production !***
+
+## Creating a user
+
+### Scenario 1: Self-registration
+If your platform has enabled self-registration, a new user can create his own account and ask for its validation.
+
+![self-registration](images/self-registration.jpg)
+
+In the registration form, the user will be asked to select the organization he/she belongs to. Organization play an important role in geOrchestra for data management. 
+
+![self-registration-form](images/self-registration-form.jpg)
+
+You can select an existing organization or [ask for the creation of a new one](organizations.md).
+
+On most platforms, your registration (and the organization creation) will be moderated, e.g. it will have to be validated by a platform administrator. You will receive emails keeping you informed of the creation steps, so ***this is important that you provide a valid email address***.
+
+Validation is done by a platform administrator. The platform administrators are notified by email. An alert is also displayed on the user administration console mentioning that users are pending validation.
+
+![A user is pending validation](images/a-user-is-pending-validation.jpg)
+
+![Users pending validation](images/users-pending-validation.jpg)
+
+![Validate pending user](images/validate-pending-user.jpg)
+
+
+### Scenario 2 : A platform admin creates a new user in the console interface
+If your platform has disabled self-registration, an existing user with admin rights in the console can create a new user:
+
+![Create a new user](images/user-creation-2.jpg)
+
+User creation form:
+
+
+![User creation form](images/user-creation-form.jpg)
+
+Some fields are mandatory. Their list depend on the platform's configuration. By default, `the following fields are mandatory:
+
+- First name
+- Second name
+- Email (this **must** be a valid email as the platform will use it to communicate with you)
+- Password (some security constraints on the password strength may be activated, depending on the platform)
+- Organization you belong to.
+
+The created user will then receive an email informing him of the account creation and asking him to set a new password.
+
+## Using an external identity provider
+
+TODO
+
+## Users on geOrchestra apps
+
+geOrchestra is binding together several web applications, some of which are internal to the project, others external projects, integrated into geOrchestra. How users are managed depends on the platform we are talking about. 
+
+Please consult the [access rights management documentation](rights_management/index.md) to know more about how the applications leverage the users information.

docs/technical_guides/rights_management/acl-gateway.en.md

@@ -0,0 +1,16 @@
+# Filtering the access to a path, using roles
+
+The security-proxy is able to limit the access to a given path only for people belonging to a set of roles.
+This is configured in the geOrchestra datadir, in gateway/gateway.yaml
+
+The `services` block declares, for each service (application) a list of path (`intercept-url`) and an associated list of roles allowed to access them (`allowed-roles`)
+
+Example: 
+```yaml
+     import:
+        target: ${georchestra.gateway.services.import.target}
+        access-rules:
+        - intercept-url: /import/**
+          anonymous: false
+          allowed-roles: SUPERUSER,IMPORT
+```

docs/technical_guides/rights_management/acl-sp.en.md

@@ -0,0 +1,45 @@
+# Filtering the access to a path, using roles
+
+The security-proxy is able to limit the access to a given path only for people belonging to a set of roles.
+This is configured in the geOrchestra datadir, in security-proxy/security-mappings.xml.
+
+Each line takes 2 parameters:
+- `pattern` is a path or a regular expression matching some paths,
+- `access` is a role or a list of roles that are granted access.
+
+The lines are checked in their order of appearance. This has some importance since, for instance, the last line defines access to `.*` (all paths).
+
+Some sample lines : 
+```xml
+  <intercept-url pattern="/console/manager/public/.*" access="IS_AUTHENTICATED_ANONYMOUSLY" />
+  <intercept-url pattern="/console/manager/.*" access="ROLE_SUPERUSER,ROLE_ORGADMIN" />
+  ...
+  <intercept-url pattern="/testPage" access="IS_AUTHENTICATED_FULLY" />
+  ...
+  <intercept-url pattern="/import/.*" access="ROLE_SUPERUSER,ROLE_IMPORT" />
+  <intercept-url pattern=".*" access="IS_AUTHENTICATED_ANONYMOUSLY,ROLE_USER,ROLE_GN_EDITOR,ROLE_GN_REVIEWER,ROLE_GN_ADMIN,ROLE_ADMINISTRATOR,ROLE_SUPERUSER,ROLE_ORGADMIN" />
+```
+
+## Pattern examples
+
+- `/console/manager/.*` is a regular expression. It configures the access to all the paths starting by `/console/manager/`
+- `/console/account/new` is a simple path, configuring access to this exact same path, and only that
+- `.*` is a regular expression matching everything
+
+## Access: list of roles
+
+You might have noticed a few weird things on the sample lines above:
+
+- roles tags don't exactly match those defined in [the roles documentation](../../admin_guide/users_management/roles.md)
+- there are some additional roles not listed in the above-mentioned doc.
+
+### `ROLE_` prefix
+
+The standard roles (ADMINISTRATOR, GN_ADMIN, IMPORT, etc) are prefixed with `ROLE_`. This is due to the way the Single Sign On (SSO) system passes along the list of roles, in the http headers.
+
+### Meta-roles
+
+There are some additional meta-roles:
+
+- `IS_AUTHENTICATED_ANONYMOUSLY`: matches people that are not logged in
+- `IS_AUTHENTICATED_FULLY`: matches people that are logged in

docs/technical_guides/rights_management/index.en.md

@@ -0,0 +1,22 @@
+# Managing access rights in geOrchestra
+
+Please read first the section of the admin guide called 
+ "[Managing users and access rights in geOrchestra](../../admin_guide/users_management/index.md)" to understand how geOrchestra uses the concepts of user, organization and roles.
+
+ Some applications can leverage new roles automatically or from the graphical user interface. Those are documented in the admin guide: [Configure an application to use a new role](../../admin_guide/users_management/roles.md#3-configure-an-application-to-use-a-new-role)
+
+ TODO: use an anchor to open the proper paragraph
+
+ Other applications can leverage new roles, but require access to the configuration files. Those belong to sysadmin users:
+
+- [Security-proxy](acl-sp.md)
+- [Gateway](acl-gateway.md)
+
+## Behind the scenes, how does it work ?
+
+Users, organizations and roles are typically stored in the LDAP instance of your platform.
+
+Some modules, like GeoNetwork, synchronize this information, on a regular basis, with its own internal database. 
+
+When you are logged in the platform, the Single Sign-On (SSO) system remembers it and provides the downstream modules, in each http request, with the information of who you are, what organization you belong to and which roles you have been given. Then the access management is delegated to the downstream module (GeoNetwork, GeoServer etc) according to their own logic.
+

docs/technical_guides/rights_management/index.fr.md

@@ -0,0 +1,24 @@
+# Sommaire
+
+
+Sommaire de la partie Administrer
+
+Cette partie de la documentation est dédiée à l'administration du contenu:
+
+
+-  gestion des données
+-  mise à jour des données
+-  gestion des utilisateurs
+-  ...
+
+
+Mettre les images dans le répertoire `images`.
+
+
+![](images/gestion_donnees.jpg)
+
+
+
+
+
+