mirror of https://gitlab.crans.org/bde/nk20
OAuth2 implementation documentation
Signed-off-by: Yohann D'ANELLO <ynerant@crans.org>
This commit is contained in:
parent
fbf64db16e
commit
f75dbc4525
|
@ -5,19 +5,10 @@ L'authentification `OAuth2 <https://fr.wikipedia.org/wiki/OAuth>`_ est supporté
|
||||||
Note Kfet. Elle offre l'avantage non seulement d'identifier les utilisateurs, mais aussi
|
Note Kfet. Elle offre l'avantage non seulement d'identifier les utilisateurs, mais aussi
|
||||||
de transmettre des informations à un service tiers tels que des informations personnelles,
|
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, en l'avertissant sur
|
le solde de la note ou encore les adhésions de l'utilisateur, en l'avertissant sur
|
||||||
quelles données sont effectivement collectées.
|
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.
|
||||||
|
|
||||||
.. danger::
|
|
||||||
L'implémentation actuelle ne permet pas de choisir quels droits on offre. Se connecter
|
|
||||||
par OAuth2 offre actuellement exactement les mêmes permissions que l'on n'aurait
|
|
||||||
normalement, avec le masque le plus haut, y compris en écriture.
|
|
||||||
|
|
||||||
Faites alors très attention lorsque vous vous connectez à un service tiers via OAuth2,
|
|
||||||
et contrôlez bien exactement ce que l'application fait de vos données, à savoir si
|
|
||||||
elle ignore bien tout ce dont elle n'a pas besoin.
|
|
||||||
|
|
||||||
À l'avenir, la fenêtre d'authentification pourra vous indiquer clairement quels
|
|
||||||
paramètres sont collectés.
|
|
||||||
|
|
||||||
Configuration du serveur
|
Configuration du serveur
|
||||||
------------------------
|
------------------------
|
||||||
|
@ -44,7 +35,15 @@ l'authentification OAuth2. On adapte alors la configuration pour permettre cela
|
||||||
...
|
...
|
||||||
}
|
}
|
||||||
|
|
||||||
On ajoute les routes dans ``urls.py`` :
|
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',
|
||||||
|
}
|
||||||
|
|
||||||
|
On ajoute enfin les routes dans ``urls.py`` :
|
||||||
|
|
||||||
.. code:: python
|
.. code:: python
|
||||||
|
|
||||||
|
@ -58,8 +57,7 @@ L'OAuth2 est désormais prêt à être utilisé.
|
||||||
Configuration client
|
Configuration client
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
Contrairement au `CAS <cas>`_, n'importe qui peut en théorie créer une application OAuth2.
|
Contrairement au `CAS <cas>`_, n'importe qui peut créer une application OAuth2.
|
||||||
En théorie, car pour l'instant les permissions ne leur permettent pas.
|
|
||||||
|
|
||||||
Pour créer une application, il faut se rendre à la page
|
Pour créer une application, il faut se rendre à la page
|
||||||
`/o/applications/ <https://note.crans.org/o/applications/>`_. Dans ``client type``,
|
`/o/applications/ <https://note.crans.org/o/applications/>`_. Dans ``client type``,
|
||||||
|
@ -72,10 +70,10 @@ Il vous suffit de donner à votre application :
|
||||||
|
|
||||||
* L'identifiant client (client-ID)
|
* L'identifiant client (client-ID)
|
||||||
* La clé secrète
|
* La clé secrète
|
||||||
* Les scopes : sous-ensemble de ``[read, write]`` (ignoré pour l'instant, cf premier paragraphe)
|
* 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'autorisation : `<https://note.crans.org/o/authorize/>`_
|
||||||
* L'URL d'obtention de jeton : `<https://note.crans.org/o/token/>`_
|
* L'URL d'obtention de jeton : `<https://note.crans.org/o/token/>`_
|
||||||
* L'URL de récupération des informations de l'utilisateur : `<https://note.crans.org/api/me/>`_
|
* Si besoin, l'URL de récupération des informations de l'utilisateur : `<https://note.crans.org/api/me/>`_
|
||||||
|
|
||||||
N'hésitez pas à consulter la page `<https://note.crans.org/api/me/>`_ pour s'imprégner
|
N'hésitez pas à consulter la page `<https://note.crans.org/api/me/>`_ pour s'imprégner
|
||||||
du format renvoyé.
|
du format renvoyé.
|
||||||
|
@ -131,3 +129,97 @@ alors autant le faire via un shell python :
|
||||||
Si vous avez bien configuré ``django-allauth``, vous êtes désormais prêts par à vous
|
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
|
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.
|
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 utilisateurs. 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 aura le choix
|
||||||
|
d'accepter ou non. Dans les deux cas, l'utilisateur 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.
|
||||||
|
|
|
@ -3218,7 +3218,7 @@ msgid ""
|
||||||
"link templates and convert permissions to scope numbers with the permissions "
|
"link templates and convert permissions to scope numbers with the permissions "
|
||||||
"that you want to grant for your application."
|
"that you want to grant for your application."
|
||||||
msgstr ""
|
msgstr ""
|
||||||
"Vous pouvez aller <a href=\"%(scopes_url)s\"ici</a> pour générer des modèles "
|
"Vous pouvez aller <a href=\"%(scopes_url)s\">ici</a> pour générer des modèles "
|
||||||
"de liens d'autorisation et convertir des permissions en identifiants de "
|
"de liens d'autorisation et convertir des permissions en identifiants de "
|
||||||
"scopes avec les permissions que vous souhaitez attribuer à votre application."
|
"scopes avec les permissions que vous souhaitez attribuer à votre application."
|
||||||
|
|
||||||
|
|
|
@ -25,7 +25,7 @@
|
||||||
<div class="card-footer text-center">
|
<div class="card-footer text-center">
|
||||||
<div class="control-group">
|
<div class="control-group">
|
||||||
<div class="controls">
|
<div class="controls">
|
||||||
<input type="submit" class="btn btn-large" value="{% trans "Cancel" %}"/>
|
<input type="submit" class="btn btn-large btn-danger" value="{% trans "Cancel" %}"/>
|
||||||
<input type="submit" class="btn btn-large btn-primary" name="allow" value="{% trans "Authorize" %}"/>
|
<input type="submit" class="btn btn-large btn-primary" name="allow" value="{% trans "Authorize" %}"/>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
Loading…
Reference in New Issue