Merge pull request 'doc_users_v2' (#17) from jmplace/DocScoDoc:doc_users_v2 into master

Reviewed-on: https://scodoc.org/git/viennet/DocScoDoc/pulls/17

docs/AdminUsers.md

@@ -7,25 +7,180 @@ une base de données SQL.
 <img src="/img/alert.png" style="vertical-align: bottom; margin:0 0 0 0;" alt="/!\" /> Il est prévu de développer un connecteur vers LDAP, mais ce n'est pas encore disponible (avis aux volontaires, voir https://www-lipn.univ-paris13.fr/projects/scodoc/ticket/140)
 
 
-###  Base de données utilisateurs 
+###  Principes généraux 
-Il est conseillé de placer la table utilisateurs dans une base de données séparées de celle
-des notes, afin de pouvoir la partager entre plusieurs UFRs ou départements sans compromettre
-la sécurité des données. Dans l'installation standard ([GuideInstallDebianDix](GuideInstallDebianDix.md)), il s'agit de la base
-**SCOUSERS**.
 
-La table **sco_users** contient:
+Depuis ScoDoc 9.0, la liste des utilisateurs est enregistrée dans la base de données unique SCODOC (en production) (voir la partie implémentation pour plus de détails)
+
+Les entités gérées par scodoc sont :
+- Les utilisateurs ;
+- les rôles ;
+- en liaison avec les départements.
+
+#### L'entité utilisateur
+- possède les propriétés habituelles (nom, prénom, user_name, email)
+- peut être associé à un département ou pas (cas d'un administrateur gérant plusieurs départements) 
+- assure un ou plusieurs rôles
+
+#### L'entité rôle
+Un rôle est le regroupement d'un certain nombre de privilèges. 
+C'est généralement la combinaison d'un département et d'un type d'utilisation.
+Actuellement au nombre de quatre (susceptible d'être étendu) :
+- Administrateur
+- Secrétariat
+- Enseignant
+- Observateur
+Le type d'utilisation donne certains privilèges (par exemple la faculté de saisir des notes, de justifier des absences, de modifier la définition des programmes, ...)
+
+_Exemple:_ 
+
+L'utilisateur 'Dupont' est responsable scodoc pour son département 'RT' mais intervient également en enseignement au département GEII.
+On pourra lui attribuer les rôles `AdminRT` et `EnsGEII`, ce qui lui permettra :
+
+- de gérer les utilisateurs du (seul) département RT :  
+Privilèges associés : `Gérer les utlisateurs (Sco Users Manage)`, `Changer les formations (Sco Change Formation)`, ...
+- d'accéder aux vues enseignant pour le département GEII :  
+Privilèges associés : `Voir les parties pour les enseignants (Sco View Ens)`, `Saisir des absences (Sco Change Absences)`, ...
+
+Pour une description plus fine des privilèges, voir [ConfigPermissions](ConfigPermissions.md)
+
+### Opérations et cycle de vie des utilisateurs
+
+Un compte utilisateur peut être modifié par 3 types d'utilisateurs :
+
+- L'utilisateur lui-même ;
+- un administrateur du département de rattachement de l'utilisateur ;
+- le super administrateur.
+
+Les opérations existantes sont :
+
+- La création ;
+- la demande de renouvellement de mot de passe;
+- la désactivation.
+
+Notes:
+
+- La suppression d'un utilisateur est impossible (nécessité de garder la trace des anciens historiques)
+- Le mécanisme de changement de mot de passe de scodoc 7 (par envoi d'un nouveau mot de passe par mail) a été remplacé par 
+l'ajout de la mention suivante dans le formulaire de connexion :
+
+`    En cas d'oubli de votre mot de passe cliquez ici pour le réinitialiser. `
+
+#### Création d'un utilisateur (par formulaire)
+
+La création d'un utilisateur peut être faite par un administrateur ou super administrateur. Le lien 
+`Ajouter un utlisateur`permettant cela se trouve dans la page de gestion des utilisateurs
+(accessible par le menu latéral)
+
+**Le mot de passe** peut être
+
+- saisie par le créateur de l'utilisateur (il appartient alors au créateur de communiquer ce mot de passe à l'utilisateur final)
+- initialisé à une valeur non communiquée, à charge pour l'utilisateur final de finaliser la création 
+du mot de passe avant d'utiliser son accès (il y est invité par un email qui lui est envoyé)
+
+**Les options de création (mail)** permettent également de choisir parmi les 3 scenarii suivants :
+
+- Un message d'accueil l'invitant à initialiser son mot de passe ;
+- un message de bienvenue simple ;
+- aucun message.
+
+Une case à cocher `envoyer un mail d'accueil à l'utlisateur` permete de choisir la troisième option (si décochée), 
+sinon la case suivante `indiquer par mail de changer le mot de passe initial` permet de choisir entre l'option 1 et l'option 2.
+
+Dans tous les cas les mails seront envoyés avec l'adresse de réponse précidée par la valeur de la variable d'environnement
+`SCODOC_MAIL_FROM` (par défaut `no-reply@{serveur_mail}`)
+
+**Le département d'appartenance** peut être choisi si le créateur est administrateur pour plusieurs départements. Il aura alors le loisir 
+de sélectionner l'un des départements qu'il administre (liste déroulante).
+
+#### Création en masse (fichier xlsx)
+
+Le super-administrateur (et lui seulement) peut également créer des comptes en masse par téléversement d'un fichier au format .xlsx
+par le biais du lien `importer des utilisateurs` de la même page de gestion des utilisateurs.
+
+La page affichée lui permet d'importer un modèle qu'il doit compléter et re-soumettre à scodoc 
+selon le même schéma que la saisie de note par fichier excel.
+
+Les colonnes à remplir sont les suivantes :
+
+- user_name: le nom de connexion de l'utilisateur; (obligatoire, unique dans scodoc)
+- nom: le nom de l'utilisateur ; (obligatoire)
+- prenom: le prénom de l'utilisateur ; (obligatoire)
+- email: l'email de l'utilisateur ; (obligatoire, unique dans scodoc)
+- roles: le ou les rôles attribués à l'utilisateur séparés par des virgules (exemple `Admin_RT, Ens_GEII`)
+- dept: le département de rattachement de l'utilisateur (acronyme, en lettres capitales).
+
+_Note_:
+
+- Tous les utilisateurs sont créés ou aucun
+- Un mail est envoyé à chaque utilisateur nouvellement créé.
+
+#### Changement du mot de passe
+
+Deux circonstances sont envisagées
+
+##### Oubli de mot de passe
+
+Lorsqu'un utilisateur a perdu son mot de passe, il a maintenant la possibilité de retrouver son accès 
+sans intervention d'un administrateur. Il lui suffit de demander la réinitialisation par le lien situé 
+sur la page de connexion. Après renseignement de son email (qui est maintenant identifiant dans scodoc), 
+un mail lui est envoyé. ce mail contient un lien comportant un jeton à durée limitée. Ce lien renvoie
+vers la page permettant de redéfinir le mot de passe de l'utilisateur.
+
+##### Edition du profil
+
+Si l'utilisateur peut se connecter, il peut éditer son profil (et par là, modifier son email et/ou son mot de passe).
+La barre latérale de l'écran principal de scodoc affiche dans le coin supérieur gauche la version courante de scodoc 
+ainsi que l'identification de l'utlisateur actuel. Un clic sur le nom permet à l'utilsateur
+d'éditer son profil.
+
+#### Activation/désactivation
+
+Une fois créé, le compte utilisateur conserve son existence. Il peut cependant être rendu inactif:
+
+- soit à l'expiration de la date de validité spécifiée à la création ou lors d'un modification
+- soit directement par un administrateur.
+
+Quelquesoit la procédure, le compte existe encore et conserve son email (il n'est donc pas possible de créer
+un nouveau compte associé au même email). Il est simplement impossible de se connecter ou de modifier 
+le profil de ce compte par l'utlisateur lui-même. 
+
+### Implémentation (pour les développeurs)
+
+Le graphe d'état ci-dessous explilcite les différents états que peux prendre un compte utilisateur
+en fonction des opérations qu'il subit.
+
+On notera:
+
+1. Que la création (1) peut le placer initialement dans deux états différents selon le mode de création choisi.
+2. Que l'on peut demander le renouvellement du mot de passe plusieurs fois même sans avoir complété la procédure
+3. Que les états `créé`et `créé + ticket`permettent la connexion (sous réserve de la connaisssance du mot de passe).
+
+
+<img src="/fig/GrapheUser.png" />
+
+**SCODOC**.
+
+La table **user** contient:
+
+|  **Colonne**      | **Type**                    |   Contenu                                                    | Modifié par    |
+|-------------------|-----------------------------|--------------------------------------------------------------|----------------|
+| id                | integer                     | identifiant interne unique                                   |  1             |
+| user_name         | character varying(64)       | nom de login                                                 |  1             |
+| email             | character varying(120)      | adresse mail (unique dans la base)                           |  1, 6          |
+|nom                | character varying(64)       |                                                              |  1, 6          |
+|prenom             | character varying(64)       |                                                              |  1, 6          |
+|dept               | character varying(32)       | département de rattachement (identifiant numérique)          |  1, 6          |   
+|active             | boolean                     |                                                              |  1, 7, 9       |
+|password_hash      | character varying(128)      | hash password                                                |  1, 6          |
+|password_scodoc7   | character varying(42)       | deprecated (utilisé lors de la migration scodoc7 > scodoc9)  |  1, 2, 4, 5, 6 |
+|last_seen          | timestamp without time zone | date de dernière connexion                                   |  1, A         |
+|date_modif_passwd  | timestamp without time zone |                                                              |  1, 2, 4, 5, 6 |
+|date_created       | timestamp without time zone |                                                              |  1             |
+|date_expiration    | timestamp without time zone |                                                              |  1             |
+|passwd_temp        | boolean                     | deprecated                                                   |                |
+|token              | text                        | dernier token émis (changement de mot de passe)              |  1a, 3         |                 
+|token_expiration   | timestamp without time zone | date d'expiration du dernier token émis                      |  1a, 3         |
 
-      **Colonne**      | **Type** ||                Contenu   
-      ----------   | ----- | -----             
- user_id           | text | identifiant interne unique 
- user_name         | text | nom de login 
- passwd            | text | hash password 
- roles             | text | liste des noms de rôles, séparés par des virgules
-date_modif_passwd | date  | 
- nom               | text | 
- prenom            | text | 
- email             | text | adresse mail 
- dept              | text | département de rattachement (exemple "RT") 
 
 
 <img src="/img/alert.png" style="vertical-align: bottom; margin:0 0 0 0;" alt="/!\" /> encodage `utf-8`, sauf si vous avez modifié l'installation.