docs

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 <cas>`_
  * `OAuth2 <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 <https://photos.crans.org>`_
+ * L'`imprimante <https://helloworld.crans.org>`_ du `Cr@ns <https://crans.org>`_
+ * Le serveur `Matrix <https://element.crans.org>`_ du `Cr@ns <https://crans.org>`_
+ * La `base de donnée de la Mediatek <https://med.crans.org>`_
+ * Le site du `K-WEI <https://kwei.crans.org>`_ 
+
+Et dans un futur plus ou moins proche :
+ * Le site pour loger les admissibles pendant les oraux (cf. `ici <https://gitlab.crans.org/bde/la25>`_)
+ * L'application mobile de la note
+ * Le site pour les commandes Terre à Terre (cf. `là <https://gitlab.crans.org/tat/blog>`_)
+ * Le futur wiki...

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 :
 `<https://gitlab.crans.org/bde/allauth-note-kfet>`_. 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 <https://gitlab.crans.org/bde/nk20/-/tree/main/apps/permission/tests/test_oauth2_flow.py>`_
+   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 : `<https://note.crans.org/o/applications/register>`_.
@@ -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 `<http://localhost/>`_.
 * ``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 <https://www.rfc-editor.org/rfc/rfc6749.html>`_ ou sur le protocole `OIDC <https://openid.net/specs/openid-connect-core-1_0.html>`_ pour plus d'informations.