From a61a4667b99cb3d3383b4b8117567f899567a7f4 Mon Sep 17 00:00:00 2001 From: quark Date: Mon, 10 Nov 2025 18:07:32 +0100 Subject: [PATCH] docs --- docs/apps/wrapped.rst | 2 +- docs/external_services/index.rst | 18 +++++++++++++---- docs/external_services/oauth2.rst | 33 ++++++++++++++++++++++++++++--- 3 files changed, 45 insertions(+), 8 deletions(-) diff --git a/docs/apps/wrapped.rst b/docs/apps/wrapped.rst index 199572dc..6669c1f9 100644 --- a/docs/apps/wrapped.rst +++ b/docs/apps/wrapped.rst @@ -84,7 +84,7 @@ Le script *generate_wrapped* fonctionne de la manière suivante : wrapped·s va/vont être généré·s ou regénéré·s. * ``global_data`` : le script génére ensuite des statistiques globales qui concernent pas qu'une seule - note (nombre de soirée, classement, etc). + note (nombre de soirée, classement, etc). * ``unique_data`` : le script génére les statitiques uniques à chaque note, et rajoute des données globales si nécessaire, pour chaque note on souhaite avoir un json avec toutes les données qui seront dans le wrapped. diff --git a/docs/external_services/index.rst b/docs/external_services/index.rst index 05524844..08cf8ab2 100644 --- a/docs/external_services/index.rst +++ b/docs/external_services/index.rst @@ -18,11 +18,21 @@ note. De cette façon, chaque application peut authentifier ses utilisateur⋅ri et récupérer leurs adhésions, leur nom de note afin d'éventuellement faire des transferts via l'API. -Deux protocoles d'authentification sont implémentées : +Trois protocoles d'authentification sont implémentées : * `CAS `_ * `OAuth2 `_ + * Open ID Connect -À 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érent⋅es. +À ce jour, ce mécanisme est notamment utilisé par : + * Le `serveur photo `_ + * L'`imprimante `_ du `Cr@ns `_ + * Le serveur `Matrix `_ du `Cr@ns `_ + * La `base de donnée de la Mediatek `_ + * Le site du `K-WEI `_ + +Et dans un futur plus ou moins proche : + * Le site pour loger les admissibles pendant les oraux (cf. `ici `_) + * L'application mobile de la note + * Le site pour les commandes Terre à Terre (cf. `là `_) + * Le futur wiki... diff --git a/docs/external_services/oauth2.rst b/docs/external_services/oauth2.rst index 252789aa..990651bf 100644 --- a/docs/external_services/oauth2.rst +++ b/docs/external_services/oauth2.rst @@ -47,7 +47,6 @@ On a ensuite besoin de définir nos propres scopes afin d'avoir des permissions 'OIDC_ENABLED': True, 'OIDC_RSA_PRIVATE_KEY': os.getenv('OIDC_RSA_PRIVATE_KEY', '/var/secrets/oidc.key'), - 'SCOPES': { 'openid': "OpenID Connect scope" }, } Cela a pour effet d'avoir des scopes sous la forme ``PERMISSION_CLUB``, @@ -99,7 +98,7 @@ du format renvoyé. .. warning:: - Un petit mot sur les scopes : tel qu'implémenté, une scope est une permission unitaire + Un petit mot sur les scopes : tel qu'implémenté, un scope est une permission unitaire (telle que décrite dans le modèle ``Permission``) associée à un club. Ainsi, un jeton a accès à une scope si et seulement si læ propriétaire du jeton dispose d'une adhésion courante dans le club lié à la scope qui lui octroie cette permission. @@ -113,6 +112,9 @@ du format renvoyé. Vous pouvez donc contrôler le plus finement possible les permissions octroyées à vos jetons. + Deux scopes sont un peu particulier, le scope "0_0" qui ne donne aucune permission + et le scope "openid" pour l'OIDC. + .. danger:: Demander des scopes n'implique pas de les avoir. @@ -134,6 +136,11 @@ du format renvoyé. uniquement dans le cas où l'utilisateur⋅rice connecté⋅e possède la permission problématique. + Dans le cas extrême ou aucun scope demandé n'est obtenus, vous + obtiendriez le scope "0_0" qui ne permet l'accès à rien. + Cela permet de générer un token pour toute les requêtes valides. + + Avec Django-allauth ################### @@ -142,6 +149,10 @@ le module pré-configuré disponible ici : ``_. Pour l'installer, vous pouvez simplement faire : +.. warning:: + À cette heure (11/2025), ce paquet est déprécié et il est plutôt conseillé de créer + sa propre application. + .. code:: bash $ pip3 install git+https://gitlab.crans.org/bde/allauth-note-kfet.git @@ -195,6 +206,20 @@ récupérés. Les autres données sont stockées mais inutilisées. Application personnalisée ######################### +.. note:: + + Tout les flow (c'est-à-dire les différentes suites de requête possible pour obtenir + un token d'accès) de l'OAuth2 sont reproduits dans les + `tests `_ + de l'application permission de la Note. L'OIDC n'étant qu'une extension du protocole + OAuth2 vous pouvez facilement reproduire les requêtes en vous inspirant de + l'Authorization Code de OAuth2. + +.. danger:: + + Pour des raisons de rétrocompatibilité, PKCE (Proof Key for Code Exchange) n'est pas requis, + son utilisation est néanmoins très vivement conseillé. + Ce modèle vous permet de créer vos propres applications à interfacer avec la Note Kfet. Commencez par créer une application : ``_. @@ -223,6 +248,8 @@ c'est sur cette page qu'il faut rediriger les utilisateur⋅rices. Il faut mettr autorisée par l'application. À des fins de test, peut être ``_. * ``state`` : optionnel, peut être utilisé pour permettre au client de détecter des requêtes provenant d'autres sites. +* ``code_challenge``: PKCE, le hash d'une chaine d'entre 43 et 128 caractères. +* ``code_challenge_method``: PKCE, ``S256`` si le hasher est sha256. Sur cette page, les permissions demandées seront listées, et l'utilisateur⋅rice aura le choix d'accepter ou non. Dans les deux cas, l'utilisateur⋅rice sera redirigée vers @@ -283,4 +310,4 @@ de rafraichissement à usage unique. Il suffit pour cela de refaire une requête Le serveur vous fournira alors une nouvelle paire de jetons, comme précédemment. À noter qu'un jeton de rafraîchissement est à usage unique. -N'hésitez pas à vous renseigner sur OAuth2 pour plus d'informations. +N'hésitez pas à vous renseigner sur `OAuth2 `_ ou sur le protocole `OIDC `_ pour plus d'informations.