Merge branch 'kerl/more_docs' into 'master'

Finalise la doc avant de release la v1

See merge request klub-dev-ens/authens!20

README.md

@@ -40,9 +40,10 @@ urlpatterns = [
 ```
 
 La page de connexion principale de AuthENS est ensuite accessible via l'url
-nommée `"authens:login"`.
-Par commodité, AuthENS rend accessible la page de déconnexion par défaut de
-Django sous le nom `"authens:logout"`.
+nommée `authens:login`.
+La page de déconnexion est `authens:logout`, il est important d'utiliser cette
+vue est non la vue de déconnexion par défaut de Django pour déconnecter du CAS
+en plus du site.
 
 ### Dans le fichier `settings.py`
 
@@ -64,6 +65,14 @@ AUTHENTICATION_BACKENDS = [
 LOGIN_URL = reverse_lazy("authens:login")
 ```
 
+- (Optionnel) Par défaut AuthENS propose les 3 modes de connexion (CAS / Vieux
+  compte CAS / mot de passe). Le mode de connexion "Vieux compte CAS" peut être
+  désactivé en ajoutant :
+
+```python
+AUTHENS_USE_OLDCAS = False
+```
+
 - (Optionnel) AuthENS utilise le paramètre Django standard
   [`LOGIN_REDIRECT_URL`](https://docs.djangoproject.com/en/3.0/ref/settings/#login-redirect-url)
   par défaut pour rediriger l'utilisateurice en cas de connexion réussie.
@@ -79,7 +88,53 @@ En revanche lorsqu'un nouveau compte est créé manuellement et que ce compte
 correspond à un compte clipper, il faut enregistrer ce compte auprès d'AuthENS,
 autrement le compte Django et le compte clipper seront considérés comme deux
 comptes différents.
+Authens fournit une fonction `register_cas_account` pour cela.
 
-**TODO:** écrire le helper qui fait une requête sur le LDAP pour trouver tout
-seul la date de création de compte. Ça ressemblera à quelque chose du genre
-`register_clipper(user, login_clipper)`.
+Exemple:
+
+```python
+from authens.shortcuts import register_cas_account
+from django.http import HttpResponseRedirect
+from yourapp.forms import UserCreationForm
+
+def create_user_view(requests, cas_login: str):
+    if request.method == "POST":
+        form = UserCreationForm(request.POST)
+        if form.is_valid():
+            user = form.save()
+            register_cas_account(user, cas_login)
+            return HttpResponseRedirect("success.html")
+    else:
+        form = UserCreationForm()
+
+    return render(request, "create_user.html", {"form": form}
+```
+
+
+## Migration depuis `django_cas_ng`
+
+Pour migrer depuis `django_cas_ng`, il est recommandé de faire une
+[data migration](https://docs.djangoproject.com/en/3.1/howto/writing-migrations/#migrating-data-between-third-party-apps)
+et d'appliquer la fonction `register_cas_account` sur tou⋅tes les
+utilisateurices.
+
+Dans le cas où certain⋅es utilisateurices n'ont pas de clipper, on peut d'abord
+tester leur existence dans le LDAP du SPI de la façon suivante:
+
+```python
+from authens.models impomrt CASAccount
+from authens.shortcuts import fetch_cas_account
+
+def migrate_user(user: User):
+    # On regarde si `user` existe dans le LDAP du SPI
+    ldap_info = fetch_cas_account(user.username)
+    if ldap_info:
+        # Si oui, on enregiste `user` en tant que compte CAS.
+        # Les deux lignes suivantes sont équivalentes à appeler
+        # `register_cas_account(user, user.username)` mais nous économisent une
+        # requête au LDAP.
+        entrance_year = ldap_info["entrance_year"]
+        CASAccount.objects.create(
+            user=user, cas_login=user.username, entrance_year=entrance_year
+        )
+```