From c825dee95a30dfaa64066601843c77b2716adc6d Mon Sep 17 00:00:00 2001 From: Yohann D'ANELLO Date: Tue, 9 Mar 2021 15:42:36 +0100 Subject: [PATCH] CAS documentation Signed-off-by: Yohann D'ANELLO --- docs/external_services/cas.rst | 80 +++++++++++++++++++++++++++++++ docs/external_services/index.rst | 28 +++++++++++ docs/external_services/oauth2.rst | 4 ++ docs/index.rst | 1 + 4 files changed, 113 insertions(+) create mode 100644 docs/external_services/cas.rst create mode 100644 docs/external_services/index.rst create mode 100644 docs/external_services/oauth2.rst diff --git a/docs/external_services/cas.rst b/docs/external_services/cas.rst new file mode 100644 index 00000000..efaf6ae8 --- /dev/null +++ b/docs/external_services/cas.rst @@ -0,0 +1,80 @@ +Service d'Authentification Centralisé (CAS) +=========================================== + +Un `CAS `_ est +déployé sur la Note Kfet. Il est accessible à l'adresse ``_. +Il a pour but uniquement d'authentifier les utilisateurs via la note et ne communique +que peu d'informations. + +Configuration +------------- + +Le serveur CAS utilisé est implémenté grâce au paquet ``django-cas-server``. Il peut être +installé soit par PIP soit sur une machine Debian via +``apt install python3-django-cas-server``. + +On ajoute ensuite ``cas_server`` aux applications Django installées. On n'oublie pas ni +d'appliquer les migrations (``./manage.py migrate``) ni de collecter les fichiers statiques +(``./manage.py collectstatic``). + +On enregistre les routes dans ``note_kfet/urls.py`` : + +.. code:: python + + urlpatterns.append( + path('cas/', include('cas_server.urls', namespace='cas_server')) + ) + +Le CAS est désormais déjà prêt à être utilisé. Toutefois, puisque l'on utilise un site +Django-admin personnalisé, on n'oublie pas d'enregistrer les pages d'administration : + +.. code:: python + + if "cas_server" in settings.INSTALLED_APPS: + from cas_server.admin import * + from cas_server.models import * + admin_site.register(ServicePattern, ServicePatternAdmin) + admin_site.register(FederatedIendityProvider, FederatedIendityProviderAdmin) + +Enfin, on souhaite pouvoir fournir au besoin le pseudo normalisé. Pour cela, on crée une +classe dans ``member.auth`` : + +.. code:: python + + class CustomAuthUser(DjangoAuthUser): + def attributs(self): + d = super().attributs() + if self.user: + d["normalized_name"] = Alias.normalize(self.user.username) + return d + + +Puis on source ce fichier dans les paramètres : + +.. code:: python + + CAS_AUTH_CLASS = 'member.auth.CustomAuthUser' + +Utilisation +----------- +Le service est accessible sur ``_. C'est ce lien qu'il faut +donner à votre application. + +L'application doit néanmoins être autorisée à accéder au CAS. Pour cela, rendez-vous +dans Django-admin (``_), dans +``Service Central d'Authentification/Motifs de services``, ajoutez une nouvelle entrée. +Choisissez votre position favorite puis le nom de l'application. + +Les champs importants sont les deux suivants : + +* **Motif :** il s'agit d'une expression régulière qui doit reconnaitre le site voulu. + Par exemple, pour autoriser Belenios (``_), on rentrera + le motif ``^https?://belenios\.crans\.org/.*$``. +* **Champ d'utilisateur :** C'est le pseudo que renverra le CAS. Par défaut, il s'agira + du nom de note principal, mais il arrive parfois que certains sites supportent mal + d'avoir des caractères UTF-8 dans le pseudo. C'est par exemple le cas de Belenios. + On rentrera alors ``normalized_name`` dans ce champ, qui correspond à la version + normalisée (sans accent ni espace ni aucun caractère non-ASCII) du pseudo, et qui + suffit à identifier une personne. + +On peut également utiliser le ``Single log out`` si besoin. diff --git a/docs/external_services/index.rst b/docs/external_services/index.rst new file mode 100644 index 00000000..ab1539aa --- /dev/null +++ b/docs/external_services/index.rst @@ -0,0 +1,28 @@ +Applications externes +===================== + +.. toctree:: + :maxdepth: 2 + :caption: Applications externes + + cas + oauth2 + +.. warning:: + L'utilisation de la note par des services externes est actuellement en beta. Il est + fort à parier que cette utilisation sera revue et améliorée à l'avenir. + +Puisque la Note Kfet recense tous les comptes des adhérents BDE, les clubs ont alors +la possibilité de développer leurs propres applications et de les interfacer avec la +note. De cette façon, chaque application peut authentifier ses utilisateurs via la note, +et récupérer leurs adhésion, leur nom de note afin d'éventuellement faire des transferts +via l'API. + +Deux protocoles d'authentification sont implémentées : + + * `CAS `_ + * `OAuth2 `_ + +À ce jour, il n'y a pas encore d'exemple d'utilisation d'application qui utilise ce +mécanisme, mais on peut imaginer par exemple que la Mediatek ou l'AMAP implémentent +ces protocoles pour récupérer leurs adhérents. diff --git a/docs/external_services/oauth2.rst b/docs/external_services/oauth2.rst new file mode 100644 index 00000000..5df4b70b --- /dev/null +++ b/docs/external_services/oauth2.rst @@ -0,0 +1,4 @@ +OAuth2 +====== + +TODO diff --git a/docs/index.rst b/docs/index.rst index 766053aa..ac17e171 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,3 +12,4 @@ Des informations complémentaires sont également disponibles sur le `Wiki Crans :caption: Développement de la NK20 apps/index + external_services/index