nk20/docs/external_services/oauth2.rst

OAuth2
======

L'authentification `OAuth2 <https://fr.wikipedia.org/wiki/OAuth>`_ est supportée par la
Note Kfet. Elle offre l'avantage non seulement d'identifier les utilisateur⋅rices, mais
aussi de transmettre des informations à un service tiers tels que des informations
personnelles, le solde de la note ou encore les adhésions de l'utilisateur⋅rice, en
l'avertissant sur quelles données sont effectivement collectées. Ainsi, il est possible
de développer des appplications tierces qui peuvent se baser sur les données de la Note
Kfet ou encore faire des transactions.


Configuration du serveur
------------------------

On utilise ``django-oauth-toolkit``, qui peut être installé grâce à PIP ou bien via APT,
via le paquet ``python3-django-oauth-toolkit``.

On commence par ajouter ``oauth2_provider`` 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 souhaite que l'API gérée par ``django-rest-framework`` puisse être accessible via
l'authentification OAuth2. On adapte alors la configuration pour permettre cela :

.. code:: python

   REST_FRAMEWORK = {
       'DEFAULT_AUTHENTICATION_CLASSES': [
           'rest_framework.authentication.SessionAuthentication',
           'rest_framework.authentication.TokenAuthentication',
           'oauth2_provider.contrib.rest_framework.OAuth2Authentication',
           ...
       ],
       ...
   }

On a ensuite besoin de définir nos propres scopes afin d'avoir des permissions fines :

.. code:: python

   OAUTH2_PROVIDER = {
       'SCOPES_BACKEND_CLASS': 'permission.scopes.PermissionScopes',
       'OAUTH2_VALIDATOR_CLASS': "permission.scopes.PermissionOAuth2Validator",
       'REFRESH_TOKEN_EXPIRE_SECONDS': timedelta(days=14),
   }

Cela a pour effet d'avoir des scopes sous la forme ``PERMISSION_CLUB``,
et de demander des scopes facultatives (voir plus bas).
Un jeton de rafraîchissement expire de plus au bout de 14 jours, si non-renouvelé.

On ajoute enfin les routes dans ``urls.py`` :

.. code:: python

   urlpatterns.append(
        path('o/', include('oauth2_provider.urls', namespace='oauth2_provider'))
    )

L'OAuth2 est désormais prêt à être utilisé.


Configuration client
--------------------

Contrairement au `CAS <cas>`_, n'importe qui peut créer une application OAuth2.

Pour créer une application, il faut se rendre à la page
`/o/applications/ <https://note.crans.org/o/applications/>`_. Dans ``client type``,
rentrez ``public`` (ou ``confidential`` selon vos choix), et vous rentrerez
généralement ``authorization-code`` dans ``Authorization Grant Type``.
Le champ ``Redirect Uris`` contient une liste d'adresses URL autorisées pour des
redirections post-connexion.

Il vous suffit de donner à votre application :

* L'identifiant client (client-ID)
* La clé secrète
* Les scopes, qui peuvent être récupérées sur cette page : `<https://note.crans.org/permission/scopes/>`_
* L'URL d'autorisation : `<https://note.crans.org/o/authorize/>`_
* L'URL d'obtention de jeton : `<https://note.crans.org/o/token/>`_
* Si besoin, l'URL de récupération des informations de l'utilisateur⋅rice : `<https://note.crans.org/api/me/>`_

N'hésitez pas à consulter la page `<https://note.crans.org/api/me/>`_ pour s'imprégner
du format renvoyé.

.. warning::

   Un petit mot sur les scopes : tel qu'implémenté, une 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.

   Par exemple, un jeton pourra avoir accès à la permission de créer des transactions en lien
   avec un club si et seulement si læ propriétaire du jeton est trésorièr⋅e du club.

   La vérification des droits de læ propriétaire est faite systématiquement, afin de ne pas
   faire confiance au jeton en cas de droits révoqués à saon propriétaire.

   Vous pouvez donc contrôler le plus finement possible les permissions octroyées à vos
   jetons.

.. danger::

   Demander des scopes n'implique pas de les avoir.

   Lorsque des scopes sont demandées par un client, la Note
   va considérer l'ensemble des permissions accessibles parmi
   ce qui est demandé. Dans vos programmes, vous devrez donc
   vérifier les permissions acquises (communiquées lors de la
   récupération du jeton d'accès à partir du grant code),
   et prévoir un comportement dans le cas où des permissions
   sont manquantes.

   Cela offre un intérêt supérieur par rapport au protocole
   OAuth2 classique, consistant à demander trop de permissions
   et agir en conséquence.

   Par exemple, vous pourriez demander la permission d'accéder
   aux membres d'un club ou de faire des transactions, et agir
   uniquement dans le cas où l'utilisateur⋅rice connecté⋅e
   possède la permission problématique.

Avec Django-allauth
###################

Si vous utilisez Django-allauth pour votre propre application, vous pouvez utiliser
le module pré-configuré disponible ici :
`<https://gitlab.crans.org/bde/allauth-note-kfet>`_. Pour l'installer, vous
pouvez simplement faire :

.. code:: bash

   $ pip3 install git+https://gitlab.crans.org/bde/allauth-note-kfet.git

L'installation du module se fera automatiquement.

Il vous suffit ensuite d'inclure l'application ``allauth_note_kfet`` à vos applications
installées (sur votre propre client), puis de bien ajouter l'application sociale :

.. code:: python

   SOCIALACCOUNT_PROVIDERS = {
       'notekfet': {
           # 'DOMAIN': 'note.crans.org',
           'SCOPE': ['1_1', '2_1'],
       },
       ...
   }

Le paramètre ``DOMAIN`` permet de changer d'instance de Note Kfet. Par défaut, il
se connectera à ``note.crans.org`` si vous ne renseignez rien.

Le paramètre ``SCOPE`` permet de définir les scopes à demander.
Dans l'exemple ci-dessous, les permissions d'accéder à l'utilisateur⋅rice
et au profil sont demandées.

En créant l'application sur la note, vous pouvez renseigner
``https://monsite.example.com/accounts/notekfet/login/callback/`` en URL de redirection,
à adapter selon votre configuration.

Vous devrez ensuite enregistrer l'application sociale dans la base de données.
Vous pouvez passer par Django-admin, mais cela peut nécessiter d'avoir déjà un compte,
alors autant le faire via un shell python :

.. code:: python

   from allauth.socialaccount.models import SocialApp
   SocialApp.objects.create(
           name="Note Kfet",
           provider="notekfet",
           client_id="VOTRECLIENTID",
           secret="VOTRESECRET",
           key="",
   )

Si vous avez bien configuré ``django-allauth``, vous êtes désormais prêts par à vous
connecter via la note :) Par défaut, nom, prénom, pseudo et adresse e-mail sont
récupérés. Les autres données sont stockées mais inutilisées.


Application personnalisée
#########################

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>`_.
Dans ``Client type``, choisissez ``Confidential`` si des informations confidentielles sont
amenées à transiter, sinon ``public``. Choisissez ``Authorization code`` dans
``Authorization grant type``.

Dans ``Redirect uris``, vous devez insérer l'ensemble des URL autorisées à être redirigées
à la suite d'une autorisation OAuth2. La première URL entrée sera l'URL par défaut dans le
cas où elle n'est pas explicitement indiquée lors de l'autorisation.

.. note::

   À des fins de tests, il est possible de laisser `<http://localhost/>`_ pour faire des
   appels à la main en récupérant le jeton d'autorisation.

Lorsqu'un client veut s'authentifier via la Note Kfet, il va devoir accéder à une page
d'authentification. La page d'autorisation est `<https://note.crans.org/o/authorize/>`_,
c'est sur cette page qu'il faut rediriger les utilisateur⋅rices. Il faut mettre en paramètre GET :

* ``client_id`` : l'identifiant client de l'application (public) ;
* ``response_type`` : mettre ``code`` ;
* ``scope`` : l'ensemble des scopes demandés, séparés par des espaces. Ces scopes peuvent
  être récupérés sur la page `<https://note.crans.org/permission/scopes/>`_.
* ``redirect_uri`` : l'URL sur laquelle rediriger qui récupérera le code d'accès. Doit être
  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.

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
``redirect_uri``, avec pour paramètre GET soit le message d'erreur, soit un paramètre
``code`` correspondant au code d'autorisation.

Une fois ce code d'autorisation récupéré, il faut désormais récupérer le jeton d'accès.
Il faut pour cela aller sur l'URL `<https://note.crans.org/o/token/>`_, effectuer une
requête POST avec pour arguments :

* ``client_id`` ;
* ``client_secret`` ;
* ``grant_type`` : mettre ``authorization_code`` ;
* ``code`` : le code généré.

À noter que le code fourni n'est disponible que pendant quelques secondes.

À des fins de tests, on peut envoyer la requête avec ``curl`` :

.. code:: bash

   curl -X POST https://note.crans.org/o/token/ -d "client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&client_secret=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&grant_type=authorization_code&code=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Le serveur renverra si tout se passe bien une réponse JSON :

.. code:: json

   {
       "access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
       "expires_in": 36000,
       "token_type": "Bearer",
       "scope": "1_1 1_2",
       "refresh_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
   }

On note donc 2 jetons différents : un d'accès et un de rafraîchissement. Le jeton d'accès
est celui qui sera donné à l'API pour s'authentifier, et qui expire au bout de quelques
heures.

Il suffit désormais d'ajouter l'en-tête ``Authorization: Bearer ACCESS_TOKEN`` pour se
connecter à la note grâce à ce jeton d'accès.

Pour tester :

.. code:: bash

   curl https://note.crans.org/api/me -H "Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

En cas d'expiration de ce jeton d'accès, il est possible de le renouveler grâce au jeton
de rafraichissement à usage unique. Il suffit pour cela de refaire une requête sur la page
`<https://note.crans.org/o/token/>`_ avec pour paramètres :

* ``client_id`` ;
* ``client_secret`` ;
* ``grant_type`` : mettre ``refresh_token`` ;
* ``refresh_token`` : le jeton de rafraîchissement.

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.