diff -r 000000000000 -r f04e1d0a0723 docs/README.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/README.txt	Thu Feb 19 10:53:29 2015 +0100
@@ -0,0 +1,85 @@
+======================
+PyAMS security package
+======================
+
+Roles et permissions
+--------------------
+ - déclaration des permissions
+ - déclaration des rôles
+ - association rôles => permissions
+ - gestion des rôles locaux (Cf pyramid_localroles)
+ - fonctions "config.register_permission()" et "config.register_role()"
+
+
+Rôles locaux
+------------
+ - interface ILocalRoles(Interface)
+   __roles__: {'role.id1': {'principal.id1', 'principal.id1'...},
+               'role.id2': {'principal.id1', 'principal.id3'...}}
+ - catalogage des rôles attribués pour recherche rapide
+ * les rôles attribués à un utilisateur font partie de ses "groupes"
+
+
+Modules d'extraction de credentials
+-----------------------------------
+ * extract_credentials
+     -> request
+     <- Credentials
+
+ - HTTP basic
+ - Form -> mémoriser login/password en session
+
+
+Modules d'authentification
+--------------------------
+ * authenticate
+     -> Credentials, request
+     <- principal_id
+
+ - Users locaux avec mot de passe
+ - LDAP
+ - SQLAlchemy
+ - (OAuth (authomatic))
+ * chaque plug-in peut-être présent en plusieurs exemplaires, chacun avec un préfixe propre
+ * exemple pour LDAP avec plusieurs branches autorisées
+
+
+Modules de stockage des utilisateurs
+------------------------------------
+ * find_principal
+     -> principal_id
+     <- PrincipalInfo
+
+ - LDAP  => préfixe = ldap:  => ldap:uid (ou ldap:dn ?)
+ - SQLAlchemy => préfixe = sa.session_name:  => sa.AGENTS:12345, sa.CLIENTS:45678
+ - Users OAuth  => préfixe = oauth:  => oauth:twitter.123456
+ - Users locaux  => préfixe = local:  => local:uid (ou ldap:email ?)
+ - Groupes  => stockage d'une liste d'ID d'utilisateurs
+               préfixe = group:  => group:managers
+
+ - recherche des utilisateurs
+
+
+Module d'encodage des mots de passe
+-----------------------------------
+ - encodage et vérification des mots de passe
+
+
+Utilitaire d'authentification
+-----------------------------
+ - prise en charge des modules
+ - application des fonctions d'authentification
+
+
+Annotations des utilisateurs
+----------------------------
+ - interface générique pour associer des métadonnées à un ID utilisateur
+
+
+Événements
+----------
+ - AuthenticatedPrincipal
+     -> notifié lorsqu'un utilisateur s'authentifie avec succès (HTTP, Form, OAuth)
+     -> enregistrement des credentials en session (si besoin du mot de passe)
+     -> permet d'enregistrer les propriétés de l'utilisateur dans un plug-in de stockage
+        si l'inscription "libre" est autorisée