Authentification
Le framework prend en charge deux façons pour un utilisateur de se connecter : un identifiant + mot de passe locaux (avec le magasin d'utilisateurs sur disque ou en base de données) et OpenID Connect (tout IdP conforme aux standards). Les deux produisent le même artefact — un jeton d'accès JWT à courte durée + un jeton de rafraîchissement à plus longue durée — que le frontend conserve en mémoire et que le backend vérifie à chaque appel API.
Le choix entre local et OIDC, plus les durées de vie des JWT et le mapping des claims OIDC, sont définis dans Paramètres → Framework → Authentification. Les deux peuvent coexister : OIDC activé pour les utilisateurs SSO, le backend local conservé pour une administration de secours.
Vue d'ensemble
Deux variantes de stockage :
• Fichier TOML sur l'hôte
• Tables de base de données (ly2_users)
Empreintes de mot de passe argon2id.
Configuré sous Authentification → OIDC.
Mappe le claim des groupes de l'IdP vers les rôles Liberty 1:1.
Jeton de rafraîchissement renouvelé à l'usage (7 jours par défaut).
Durées modifiables par installation.
Choisir un backend local
Dans Paramètres → Framework → Authentification, la liste déroulante Backend propose deux valeurs :
| Backend | Stockage | Avantage | Inconvénient |
|---|---|---|---|
| Local — TOML (défaut) | config/auth.toml sur l'hôte. | Zéro infrastructure — fonctionne sans base externe. | Ne survit pas à une reconstruction de conteneur quand le fichier n'est pas monté ; ne partage pas l'état entre les répliques. Inadapté au-delà d'environ 100 utilisateurs. |
| Local — Base de données | Tables ly2_users / ly2_roles / ly2_permissions sur le pool par défaut. | Survit aux reconstructions de conteneur quand la base est externe. Partagé entre les répliques — la connexion sur un nœud fonctionne sur tous les nœuds. Passe à l'échelle de milliers d'utilisateurs. | Demande que le pool par défaut soit joignable au démarrage. Un élément de plus à sauvegarder. |
Au premier lancement du framework sur une installation neuve, ./start.sh init-db initialise le backend configuré et amorce un utilisateur admin (le mot de passe est imprimé une seule fois sur stdout).
Changer de backend est une modification qui demande un redémarrage — le formulaire signale le champ par un badge Redémarrage requis.
Gérer les utilisateurs locaux — Paramètres → Utilisateurs
L'onglet Utilisateurs est l'éditeur de référence pour le backend local (les deux variantes). La page liste chaque utilisateur avec ses rôles, son indicateur actif et sa dernière connexion :
| Action | Comment |
|---|---|
| Créer un utilisateur | + Nouvel utilisateur — identifiant, nom affiché, rôles (sélection multiple parmi les rôles configurés), mot de passe. |
| Réinitialiser le mot de passe | Cliquer un utilisateur, Réinitialiser le mot de passe — demande le nouveau mot de passe (deux fois). |
| Ajouter / retirer des rôles | Cliquer un utilisateur, modifier la sélection multiple Rôles. |
| Désactiver | Cliquer un utilisateur, basculer Actif sur off. Désactive l'utilisateur en douceur (préserve l'historique). |
| Révoquer les sessions | Cliquer un utilisateur, Révoquer toutes les sessions — invalide tous les jetons d'accès + de rafraîchissement actifs. |
Les mêmes opérations sont disponibles via la CLI pour le scripting shell.
Politique de mot de passe
Les mots de passe sont hachés avec argon2id. Le réglage Argon2 est modifiable dans Paramètres → Framework → Authentification — les valeurs par défaut sont Time cost = 2, Memory cost = 64 MiB, Parallelism = 1, calibrées pour un coût serveur d'environ 50 ms sur un CPU moderne. Augmenter Memory cost sur les installations avec des modèles de menace plus stricts.
Un validateur enfichable rejette les mots de passe faibles. Le validateur livré impose :
- 10 caractères ou plus.
- Au moins un chiffre, une majuscule, une minuscule.
- Différent de l'identifiant.
Pour le remplacer, définir Validateur de mot de passe dans Paramètres → Framework → Authentification sur un callable de votre dépôt d'apps (par ex. myapp.security:validate). Voir Apps et Plugins → Plugins pour la signature de la fonction.
SSO OIDC
Dans Paramètres → Framework → Authentification, activer la bascule OIDC activé. Le sous-formulaire OIDC apparaît :
| Champ | Description |
|---|---|
| URL de l'émetteur | URL du fournisseur OIDC. Le framework va chercher ${issuer}/.well-known/openid-configuration au démarrage pour découvrir les endpoints. |
| Client ID / Secret du client | Identifiants OAuth2 du client enregistrés auprès de l'IdP. Le secret est toujours chiffré en stockage — l'icône 🔒 est verrouillée. |
| URI de redirection | URL de rappel du framework. Doit être enregistrée côté IdP. |
| Claim email | Claim JWT utilisé comme identifiant local. Par défaut email. |
| Claim groupes | Claim JWT mappé vers les rôles Liberty 1:1. Par défaut groups. Un groupe nommé editor côté IdP attribue le rôle Liberty editor. |
| Auto-provisionnement | Quand actif, un utilisateur Liberty est créé à la première connexion. Quand inactif, l'utilisateur doit déjà exister — pratique quand l'appartenance aux groupes est plus large que la liste d'autorisation Liberty. |
Un bouton Tester la connexion en bas du sous-formulaire OIDC ouvre la redirection IdP dans un nouvel onglet et rapporte le résultat. À utiliser avant d'enregistrer — une mauvaise URL d'émetteur se repère bien plus vite ici que depuis la page de connexion.
Formats d'émetteur par IdP
| IdP | Modèle d'URL d'émetteur |
|---|---|
| Authentik | https://auth.example.com/application/o/liberty/ (la barre oblique finale est obligatoire) |
| Keycloak | https://kc.example.com/realms/<realm> (et activer le mapper groups sur le client Liberty) |
| Azure AD / Entra | https://login.microsoftonline.com/<tenant>/v2.0 (configurer Groups claims dans la config du jeton) |
| Okta | https://<your-domain>.okta.com/oauth2/default |
| Google Workspace | https://accounts.google.com (pas de claim de groupe — utiliser le claim HD pour la restriction de domaine, gérer les rôles dans l'onglet Utilisateurs de Liberty) |
La page de connexion
Avec OIDC actif, le bouton Se connecter avec SSO apparaît à côté du formulaire identifiant / mot de passe sur la page de connexion. Le formulaire local reste disponible pour les administrateurs de secours.
Cycle de vie des jetons
Les durées sont modifiables dans Paramètres → Framework → Authentification :
| Jeton | Défaut | Champ de l'éditeur | Stockage | Usage |
|---|---|---|---|---|
| Jeton d'accès | 15 min | Durée du jeton d'accès | localStorage du frontend (clé liberty_access) | Envoyé en Authorization: Bearer … à chaque appel API. |
| Jeton de rafraîchissement | 7 jours | Durée du jeton de rafraîchissement | Cookie httpOnly (liberty_refresh), SameSite=Strict | Échangé contre un nouveau jeton d'accès quand le précédent expire. |
Le client API du frontend rafraîchit le jeton d'accès de manière transparente quand il obtient un 401 avec WWW-Authenticate: Bearer error="invalid_token". La requête en échec est rejouée une fois avec le nouveau jeton.
Révocation
| Déclencheur | Effet |
|---|---|
| L'utilisateur se déconnecte | Le jeton de rafraîchissement est retiré du magasin côté serveur ; le jeton d'accès expire dans la durée TTL. |
| L'opérateur clique Révoquer toutes les sessions sur l'utilisateur | Identique à la déconnexion pour chaque session active de l'utilisateur. |
| L'opérateur marque l'utilisateur Inactif | Les rafraîchissements de jeton suivants échouent. |
| Redémarrage du framework avec une nouvelle clé de signature JWT | Chaque jeton d'accès actif devient immédiatement invalide. Les jetons de rafraîchissement échouent aussi — chaque utilisateur doit se reconnecter. |
La clé de signature JWT est référencée par nom de variable d'environnement dans le formulaire Authentification (par défaut ${LIBERTY_JWT_SECRET}). Faire tourner la clé est une action qui demande un redémarrage.
Permissions
L'onglet Utilisateurs est gouverné par users:read (consultation) / users:write (édition). L'onglet Rôles suit le même modèle — voir Rôles et permissions. Le sous-formulaire Authentification de l'onglet Framework est gouverné par settings:framework.
Conseils et bonnes pratiques
- Définir la clé de signature JWT en production. Une clé éphémère convient en développement mais invalide chaque session à chaque redémarrage.
- Utiliser le backend base de données au-delà d'une poignée d'utilisateurs. TOML se dégrade sous les éditions concurrentes ; le backend BDD gère cela proprement.
- Conserver au moins un administrateur local même sur les installations OIDC. L'accès de secours quand l'IdP est indisponible est inestimable.
- Refléter les groupes de l'IdP vers les rôles Liberty 1:1. Contrat le plus propre — nommer les rôles Liberty pour qu'ils correspondent aux noms de groupes de l'IdP.
- Faire tourner la clé de signature JWT selon un calendrier. Une cadence annuelle est raisonnable ; la perturbation est d'une reconnexion par utilisateur.
- Utiliser Tester la connexion sur le formulaire OIDC avant d'enregistrer. Permet de détecter tôt les mauvaises URL d'émetteur / URI de redirection non enregistrées.
Sous le capot
Les paramètres d'authentification sont enregistrés dans config/app.toml sous les sections [auth] et [auth.oidc]. Les entrées d'utilisateurs locaux sont enregistrées dans config/auth.toml (backend TOML) ou dans les tables ly2_users (backend Base de données). Les opérateurs ne modifient pas ces fichiers à la main — l'interface Paramètres est l'interface de référence. Les opérateurs avancés peuvent encore utiliser l'onglet Raw TOML ou la CLI pour une mise en place scriptée.
Pour aller plus loin
- Rôles et permissions — ce qu'un rôle peut faire, les codes de permission, la matrice d'attribution.
- Clé de licence — verrous de fonctionnalités signés RS256.
- Apps et Plugins → Plugins — validateur de mot de passe personnalisé et autres crochets d'authentification.