Skip to main content
View as Markdown

Gestion des utilisateurs

Sovrium provisionne et gère les utilisateurs sans jamais exiger que vous touchiez directement à la base de données. Le premier administrateur est créé au démarrage (à partir de variables d'environnement, d'un jeton à usage unique ou de la CLI) ; les utilisateurs suivants sont créés, listés, dotés de rôles et invités via l'API d'administration authentifiée. Chaque opération est protégée par RBAC et consignée dans le journal d'audit.

La gestion des utilisateurs n'est disponible que lorsque l'authentification est configurée. Le plugin d'administration est activé automatiquement dès qu'un bloc auth existe — il n'y a pas d'indicateur distinct à définir.

Amorçage de l'administrateur

Le tout premier administrateur ne peut pas être créé par un autre administrateur (il n'en existe aucun encore) ni par auto-inscription (vous ne voulez pas que n'importe qui s'approprie le siège d'administrateur). Sovrium propose trois chemins d'amorçage complémentaires pour provisionner ce premier compte sur une base de données vierge.

Chemin Quand l'utiliser Mécanisme
Amorçage par variable env Déploiements automatisés / IaC Définissez AUTH_ADMIN_EMAIL + AUTH_ADMIN_PASSWORD (+ AUTH_ADMIN_NAME optionnel) ; l'administrateur est créé au premier démarrage.
Jeton à usage unique Vous ne voulez pas d'identifiants en variables env Démarrez sans AUTH_ADMIN_EMAIL et sans utilisateur ; un jeton hexadécimal de 64 caractères est affiché dans la bannière de démarrage et réclamé une fois via POST /api/admin/bootstrap/claim.
CLI Provisionnement interactif sovrium admin create <email> fonctionne sur la base de données configurée (ou le fichier SQLite par défaut) sans app.yaml requis.

Amorçage par variable d'environnement (sans configuration)

AUTH_ADMIN_EMAIL=admin@example.com
AUTH_ADMIN_PASSWORD=SecureP@ssw0rd!
AUTH_ADMIN_NAME=System Administrator   # optional, defaults to "Administrator"

Au premier démarrage sur une base de données vierge, le serveur provisionne l'administrateur avec une adresse e-mail vérifiée et lui accorde l'accès à chaque point de terminaison réservé aux administrateurs. Lors des démarrages suivants, ce chemin ne fait rien — il ne crée jamais de doublon et ne modifie jamais un utilisateur existant, même si l'adresse e-mail correspond déjà à un rôle différent. Le succès est consigné sans exposer le mot de passe.

Variable env Description
AUTH_ADMIN_EMAIL E-mail de l'administrateur d'amorçage. Requis pour le chemin par variable env. Doit être un format d'e-mail valide.
AUTH_ADMIN_PASSWORD Mot de passe initial. Requis pour le chemin par variable env. Doit respecter la longueur minimale (8 caractères).
AUTH_ADMIN_NAME Nom affiché. Optionnel — par défaut Administrator.

Amorçage par jeton à usage unique

Lorsque le serveur démarre sans AUTH_ADMIN_EMAIL défini et sans utilisateur dans la base de données, il génère un jeton aléatoire cryptographique de 256 bits, l'affiche une fois dans la bannière de démarrage et accepte une seule réclamation :

# Token appears in the banner as:
#   → First-admin token (POST /api/admin/bootstrap/claim): <64-hex-token>

curl -X POST http://localhost:3000/api/admin/bootstrap/claim \
  -H 'Content-Type: application/json' \
  -d '{ "token": "<64-hex-token>", "email": "admin@example.com", "password": "SecureP@ssw0rd!", "name": "Admin" }'

Propriétés de sécurité :

  • Seul le hachage SHA-256 du jeton est conservé ; le texte en clair est affiché sur stdout exactement une fois et n'est jamais consigné.
  • Le jeton expire après 1 heure et peut être réclamé une seule fois — les rejeux renvoient 401.
  • Dès qu'un administrateur existe, la route renvoie 404 : la fenêtre d'amorçage est fermée, et même un jeton valide divulgué ne peut pas la rouvrir.

C'est le chemin qui rend possible « lancer le binaire sur un serveur vierge avec seulement DATABASE_URL défini, ouvrir l'URL, construire l'application en direct ». Voir Infrastructure de base de données pour la base de données sans configuration qui l'accompagne.

Création et gestion des utilisateurs

Une fois qu'un administrateur existe, toutes les opérations de cycle de vie des utilisateurs suivantes passent par l'API d'administration. Chaque point de terminaison exige une session d'administrateur authentifiée — les requêtes non authentifiées renvoient 401, les sessions non administrateur renvoient 403.

Opération Point de terminaison Notes
Créer un utilisateur POST /api/auth/admin/create-user L'ingénieur choisit le mot de passe ; aucun e-mail n'est envoyé. Renvoie 201.
Lister les utilisateurs GET /api/auth/admin/list-users Paginé (limit/offset), renvoie des métadonnées de comptage, prend en charge la recherche par e-mail ou nom.
Obtenir un utilisateur GET /api/auth/admin/get-user/:id Détail complet incl. rôle, statut de bannissement, indicateur d'e-mail vérifié. 404 pour les identifiants inconnus.
Définir le rôle POST /api/auth/admin/set-role Attribue admin / member / viewer (ou tout rôle personnalisé).
Définir le mot de passe POST /api/auth/admin/set-user-password Réinitialise le mot de passe d'un utilisateur de manière administrative.
Lister les sessions GET /api/auth/admin/list-user-sessions Sessions actives pour un utilisateur.
Révoquer une session POST /api/auth/admin/revoke-user-session Force la déconnexion d'une session spécifique.
Usurper l'identité POST /api/auth/admin/impersonate-user Démarre/arrête l'usurpation d'identité pour les flux de support. 
auth:
  strategies:
    - type: emailAndPassword
  defaultRole: member

Attribution de rôle

Sovrium fournit trois rôles par défaut — admin, member, viewer — et prend en charge des rôles personnalisés déclarés dans le bloc auth. Les nouveaux utilisateurs reçoivent auth.defaultRole (par défaut member) sauf si un rôle explicite est fourni à la création. Le premier administrateur d'amorçage est toujours créé avec le rôle admin et une adresse e-mail vérifiée.

Les rôles pilotent chaque décision d'autorisation dans la plateforme : les permissions de table, l'accès par champ, l'accès aux pages et l'API d'administration elle-même. Voir Rôles & RBAC pour le modèle de rôle complet et la matrice de permissions par champ.

Flux d'invitation

Le point de terminaison create-user exige que l'administrateur choisisse le mot de passe du client et n'envoie aucun e-mail — ce qui ne convient pas à un véritable accueil de clients. Le flux d'invitation sans mot de passe parallèle comble cette lacune : l'administrateur émet une invitation avec { email, name, role } (sans mot de passe), Sovrium envoie par e-mail un lien à usage unique, et le client définit son propre mot de passe et atterrit authentifié.

auth:
  strategies:
    - type: emailAndPassword
  invitationTokenExpiry: '72h' # default lifetime; accepts '30s' / '15m' / '72h' / '7d' / ms
  emailTemplates:
    invitation:
      subject: 'You are invited to join, $name'
      text: |
        Hi $name,
        $inviterName invited you to join.
        Set your password: $url
        This invitation expires in 72 hours.
Point de terminaison Comportement
POST /api/auth/admin/invite-user Accepte { email, name, role } (sans mot de passe). Renvoie 200 avec { user, invitationSent: true }. 401/403 pour non authentifié/non administrateur ; 422 lorsque l'e-mail correspond déjà à un utilisateur entièrement intégré.
POST /api/auth/admin/accept-invitation Sous-tend la page publique /accept-invitation?token=.... Le client définit un mot de passe et atterrit dans une session authentifiée.

Les jetons d'invitation réutilisent la table auth.verification (la même forme que Better Auth utilise pour la réinitialisation de mot de passe), expirent après invitationTokenExpiry (par défaut 72h) et sont à usage unique — les rejeux renvoient 400/410. Variables de substitution d'e-mail : $name, $url, $email, $inviterName. auth.allowSignUp: false ne bloque pas les invitations — la création d'utilisateur pilotée par l'administrateur est toujours disponible lorsque l'authentification est configurée.

Pages connexes