« Authentification OpenID par Authelia » : différence entre les versions
mAucun résumé des modifications |
|||
| (11 versions intermédiaires par 3 utilisateurs non affichées) | |||
| Ligne 1 : | Ligne 1 : | ||
Sigma | L'annuaire des utilisateurs Sigma est disponible pour l'authentification auprès de sites binets tiers à travers le protocole [https://fr.wikipedia.org/wiki/OpenID OpenID]. | ||
Le serveur d'authentification est situé à l'adresse [https://auth.binets.fr auth.binets.fr] et est | Le serveur d'authentification est situé à l'adresse [https://auth.binets.fr auth.binets.fr] et est une instance [https://www.authelia.com/ Authelia]. | ||
Pour permettre à votre site de bénéficier de ce moyen d'authentification, faites un [https://panix.binets.fr ticket Panix] en précisant l'url complète de callback vers laquelle Authelia redirigera l'utilisateur après une connexion réussie. La demande doit être justifiée, suite à quoi un BRman ajoutera votre site à la liste des bénéficiaires autorisés. | |||
== | ==Comment ça marche ?== | ||
Lorsqu'un utilisateur souhaite s'authentifier, voici les actions qui devront être réalisées par votre site : | |||
* Un bouton de Login de votre frontend fait une requête à votre backend. | |||
* email | * Votre backend renvoie une redirection vers [https://auth.binets.fr Authelia] à l'aide d'un client OpenID (de nombreux packages sont disponibles dans tous les langages de programmation à cet effet). Il doit aussi envoyer une chaîne de caractères aléatoire (state) à Authelia, et la garder en mémoire pour cet utilisateur. Elle sera utilisée pour confirmer la validité de la redirection Authelia. | ||
* | * L'utilisateur sera alors redirigé vers [https://auth.binets.fr Authelia] pour s'authentifier. S'il l'est déjà (session Authelia valide existante), cette étape sera passée. | ||
* Après authentification, [https://auth.binets.fr Authelia] redirigera l'utilisateur vers la route de votre backend précisée en tant que <code>callback url</code> dans la configuration d'authelia, en envoyant en prime des données liées à cet utilisateur (nom, email...) ainsi que le "state". | |||
* Votre backend reçoit ces données, et crée une session propre à votre site pour cet utilisateur (session, JSON Web Token, Opaque Access Token...). Lorsque cette session propre à votre site expirera, l'utilisateur pourra à nouveau d'authentifier via Authelia pour la renouveler. | |||
'''NOTE''' : il est pratique d'envoyer le "state" à l'utilisateur via un cookie <code>HttpOnly</code> à expiration session. Il sera facile à récupérer après retour d'Authelia pour comparaison, et expirera tout seul à la fermeture de l'onglet du navigateur. | |||
Le protocole OpenID est très commun, et de nombreux packets existent qui nous simplifieront la vie. Pour tous les backend basés sur Node.js (Adonis JS, | ==Informations disponibles (scopes)== | ||
Authelia met à disposition différentes données utilisateur à travers des <code>scopes</code>. | |||
Lors de la configuration du client OpenID dans votre backend, vous devrez préciser les scopes auquels vous souhaitez accéder afin de recevoir les données correspondantes. Le scope <code>openid</code> est obligatoire. | |||
Les informations suivantes sont mises à votre disposition : | |||
* email (scope <code>email</code>); | |||
* Prénom NOM (scope <code>profile</code>); | |||
* groupes Sigma dont l'utilisateur est membre (scope <code>groups</code>). | |||
Lorsque votre backend reçoit ces informations après une authentification réussie avec Authelia, il est conseillé de créer votre propre session utilisateur en émettant un JSON Web Token (stocké dans un cookie <code>HttpOnly</code>, pour les sites avec Server-Side template Rendering), un Opaque Access Token (pour les sites avec un frontend et un backend séparés). | |||
==Exemples d'implémentation== | |||
===Backend Node.js basé sur Adonis JS=== | |||
Le protocole OpenID est très commun, et de nombreux packets existent qui nous simplifieront la vie. Pour tous les backend basés sur Node.js (Adonis JS, Nest JS, Express...), il est possible d'utiliser le packet [https://www.npmjs.com/package/openid-client openid-client]. | |||
Voici un example pour Adonis JS, qui s'adapte à tout backend basé sur Node.js, sur [https://gitlab.binets.fr/svg/example-backend/-/blob/main/app/Controllers/auth/authSigmaUser.ts Gitlab]. | Voici un example pour Adonis JS, qui s'adapte à tout backend basé sur Node.js, sur [https://gitlab.binets.fr/svg/example-backend/-/blob/main/app/Controllers/auth/authSigmaUser.ts Gitlab]. | ||
| Ligne 24 : | Ligne 40 : | ||
* Que la route <code>/auth/sigmaUser/callback/</code> pointe vers la fonction <code>callbackSigmaUser</code> | * Que la route <code>/auth/sigmaUser/callback/</code> pointe vers la fonction <code>callbackSigmaUser</code> | ||
* Une base de données avec trois colonnes: state, codeVerifier et date de création | * Une base de données avec trois colonnes: state, codeVerifier et date de création | ||
* Un cron (fonction qui s'éxécute régulièrement, par exemple une fois par jours) qui supprime les lignes de la base de donnée susnommée qui sont trop | * Un cron (fonction qui s'éxécute régulièrement, par exemple une fois par jours) qui supprime les lignes de la base de donnée susnommée qui sont trop vieilles (par exemple vieilles de plus d'une heure). Voir l'[https://gitlab.binets.fr/svg/example-backend/-/blob/main/app/Controllers/cron.ts implémentation du cron] (qui est ici exécuté lorsqu'un autre programme fait une requête à une certaine route) | ||
Le cron est nécessaire, car si un utilisateur commence à se connecter, une nouvelle ligne est crée dans la base de données. Elle est ensuite supprimée lorsqu'il a tapé ses identifiants. Si l'utilisateur ne tape jamais ses identiiants, la ligne n'est jamais supprimée, d'où la nécessité du cron. | Le cron est nécessaire, car si un utilisateur commence à se connecter, une nouvelle ligne est crée dans la base de données. Elle est ensuite supprimée lorsqu'il a tapé ses identifiants. Si l'utilisateur ne tape jamais ses identiiants, la ligne n'est jamais supprimée, d'où la nécessité du cron. | ||
'''NOTE''' : une autre possibilité est, lors de la redirection vers Authelia, d'envoyer le <code>state</code> à l'utilisateur sous la forme d'un cookie. Il sera renvoyé à votre backend lors du retour vers l'url callback, évitant la nécessité d'utiliser une base de données. | |||
===Backend Golang basé sur Echo=== | |||
Un exemple codé en Go est disponible dans [https://gitlab.binets.fr/thibaut.de-saivre/skibidi-site ce repository]. Il utilise le package [https://github.com/coreos/go-oidc OIDC] pour son client OpenID. | |||
Le flow d'authentification de ce backend est le suivant : | |||
* Le bouton de login du frontend effectue une requête POST sur la route <code>/api/openid_redirect</code>. | |||
* Cette route redirige l'utilisateur vers Authelia, et crée un <code>uuid</code> qu'elle envoie à l'utilisateur via un cookie "state", ainsi qu'à Authelia. | |||
* Authelia redirige l'utilisateur vers la route <code>/api/openid_callback</code>. Le backend compare le state envoyé au callback avec celui contenu dans le cookie "state". | |||
* Le backend crée un JSON Web Token avec les informations de l'utilisateur et le renvoie sous la forme d'un cookie <code>HttpOnly</code> avec une durée de vie de 72 heures. Tant que ce cookie est valide, le site ne demandera pas à l'utilisateur de se réauthentifier. | |||
Voir la [https://gitlab.binets.fr/thibaut.de-saivre/skibidi-site#authentication section Authentication du README] pour plus de détails ainsi que des liens vers le code source pertinent. | |||
===Inclure Authelia pour le développement de votre site=== | |||
Pour avoir accès à un serveur Authelia test pour le développement de votre site, vous pouvez utiliser [https://gitlab.binets.fr/br/docker-openid ce repository]. Les instructions d'installation sont détaillées dans le README. | |||
L'adresse du serveur d'authentification devient alors <code>http://127.0.0.1:9091</code> au lieu de <code>https://auth.binets.fr</code> (il faut donc par exemple changer la variable <code>AUTH_URL</code> de l'exemple précédent). | |||
⚠️ C'est bien <code>http://127.0.0.1:9091</code> et pas <code>http://localhost:9091</code> | |||
Version actuelle datée du 15 novembre 2024 à 19:40
L'annuaire des utilisateurs Sigma est disponible pour l'authentification auprès de sites binets tiers à travers le protocole OpenID.
Le serveur d'authentification est situé à l'adresse auth.binets.fr et est une instance Authelia.
Pour permettre à votre site de bénéficier de ce moyen d'authentification, faites un ticket Panix en précisant l'url complète de callback vers laquelle Authelia redirigera l'utilisateur après une connexion réussie. La demande doit être justifiée, suite à quoi un BRman ajoutera votre site à la liste des bénéficiaires autorisés.
Comment ça marche ?
Lorsqu'un utilisateur souhaite s'authentifier, voici les actions qui devront être réalisées par votre site :
- Un bouton de Login de votre frontend fait une requête à votre backend.
- Votre backend renvoie une redirection vers Authelia à l'aide d'un client OpenID (de nombreux packages sont disponibles dans tous les langages de programmation à cet effet). Il doit aussi envoyer une chaîne de caractères aléatoire (state) à Authelia, et la garder en mémoire pour cet utilisateur. Elle sera utilisée pour confirmer la validité de la redirection Authelia.
- L'utilisateur sera alors redirigé vers Authelia pour s'authentifier. S'il l'est déjà (session Authelia valide existante), cette étape sera passée.
- Après authentification, Authelia redirigera l'utilisateur vers la route de votre backend précisée en tant que
callback urldans la configuration d'authelia, en envoyant en prime des données liées à cet utilisateur (nom, email...) ainsi que le "state". - Votre backend reçoit ces données, et crée une session propre à votre site pour cet utilisateur (session, JSON Web Token, Opaque Access Token...). Lorsque cette session propre à votre site expirera, l'utilisateur pourra à nouveau d'authentifier via Authelia pour la renouveler.
NOTE : il est pratique d'envoyer le "state" à l'utilisateur via un cookie HttpOnly à expiration session. Il sera facile à récupérer après retour d'Authelia pour comparaison, et expirera tout seul à la fermeture de l'onglet du navigateur.
Informations disponibles (scopes)
Authelia met à disposition différentes données utilisateur à travers des scopes.
Lors de la configuration du client OpenID dans votre backend, vous devrez préciser les scopes auquels vous souhaitez accéder afin de recevoir les données correspondantes. Le scope openid est obligatoire.
Les informations suivantes sont mises à votre disposition :
- email (scope
email); - Prénom NOM (scope
profile); - groupes Sigma dont l'utilisateur est membre (scope
groups).
Lorsque votre backend reçoit ces informations après une authentification réussie avec Authelia, il est conseillé de créer votre propre session utilisateur en émettant un JSON Web Token (stocké dans un cookie HttpOnly, pour les sites avec Server-Side template Rendering), un Opaque Access Token (pour les sites avec un frontend et un backend séparés).
Exemples d'implémentation
Backend Node.js basé sur Adonis JS
Le protocole OpenID est très commun, et de nombreux packets existent qui nous simplifieront la vie. Pour tous les backend basés sur Node.js (Adonis JS, Nest JS, Express...), il est possible d'utiliser le packet openid-client.
Voici un example pour Adonis JS, qui s'adapte à tout backend basé sur Node.js, sur Gitlab.
Cette implémentation nécessite:
- Qu'une route (comme
/auth/sigmaUser/login/) pointe vers la fonctionloginSigmaUser - Que la route
/auth/sigmaUser/callback/pointe vers la fonctioncallbackSigmaUser - Une base de données avec trois colonnes: state, codeVerifier et date de création
- Un cron (fonction qui s'éxécute régulièrement, par exemple une fois par jours) qui supprime les lignes de la base de donnée susnommée qui sont trop vieilles (par exemple vieilles de plus d'une heure). Voir l'implémentation du cron (qui est ici exécuté lorsqu'un autre programme fait une requête à une certaine route)
Le cron est nécessaire, car si un utilisateur commence à se connecter, une nouvelle ligne est crée dans la base de données. Elle est ensuite supprimée lorsqu'il a tapé ses identifiants. Si l'utilisateur ne tape jamais ses identiiants, la ligne n'est jamais supprimée, d'où la nécessité du cron.
NOTE : une autre possibilité est, lors de la redirection vers Authelia, d'envoyer le state à l'utilisateur sous la forme d'un cookie. Il sera renvoyé à votre backend lors du retour vers l'url callback, évitant la nécessité d'utiliser une base de données.
Backend Golang basé sur Echo
Un exemple codé en Go est disponible dans ce repository. Il utilise le package OIDC pour son client OpenID.
Le flow d'authentification de ce backend est le suivant :
- Le bouton de login du frontend effectue une requête POST sur la route
/api/openid_redirect. - Cette route redirige l'utilisateur vers Authelia, et crée un
uuidqu'elle envoie à l'utilisateur via un cookie "state", ainsi qu'à Authelia. - Authelia redirige l'utilisateur vers la route
/api/openid_callback. Le backend compare le state envoyé au callback avec celui contenu dans le cookie "state". - Le backend crée un JSON Web Token avec les informations de l'utilisateur et le renvoie sous la forme d'un cookie
HttpOnlyavec une durée de vie de 72 heures. Tant que ce cookie est valide, le site ne demandera pas à l'utilisateur de se réauthentifier.
Voir la section Authentication du README pour plus de détails ainsi que des liens vers le code source pertinent.
Inclure Authelia pour le développement de votre site
Pour avoir accès à un serveur Authelia test pour le développement de votre site, vous pouvez utiliser ce repository. Les instructions d'installation sont détaillées dans le README.
L'adresse du serveur d'authentification devient alors http://127.0.0.1:9091 au lieu de https://auth.binets.fr (il faut donc par exemple changer la variable AUTH_URL de l'exemple précédent).
⚠️ C'est bien http://127.0.0.1:9091 et pas http://localhost:9091
