Inscription, KYC et migration
Inscriptions en libre-service, provisionnement d'entreprise, vérification KYC, cycle de vie des comptes et flux de migration sécurisés.
Inscriptions en libre-service, provisionnement d'entreprise, vérification KYC, cycle de vie des comptes et flux de migration sécurisés.
Vue d'ensemble et portée
Ce document décrit comment Hawiyati crée, vérifie et gère les comptes utilisateurs dans trois scénarios de déploiement : inscription grand public en mode greenfield, provisionnement d'entreprise et accès initié par un SP. Il définit le modèle de niveau d'assurance, les transitions d'état des comptes, le jeton de complétion à session limitée et le pipeline d'import groupé gouverné.
Le niveau d'assurance est sourcé exclusivement depuis kyc_profiles.current_level. Aucune colonne users.assurance_level n'est ajoutée — ce serait une deuxième source de vérité créant des incohérences.
Trois scénarios de déploiement
| Scénario | Utilisateur principal | Chemin d'entrée | KYC requis |
|---|---|---|---|
| Grand public greenfield | Utilisateur final | Libre-service /idp/register | Piloté par politique ; L1 par défaut pour la plupart des SP |
| Entreprise / personnel | Employé ou prestataire | Provisionnement SCIM, JIT LDAP, invitation ou import CSV | Transfert d'assurance source ou période de grâce |
| Initié par le SP | Utilisateur arrivant d'un service | AuthnRequest SAML ou autorisation OIDC → inscription | Assurance minimale SP déclenche la porte KYC après connexion |
Niveaux d'assurance L0–L4
| Niveau | Nom | Preuves requises | Statut |
|---|---|---|---|
| L0 | Non vérifié | Confirmation e-mail ou téléphone uniquement. Niveau par défaut à l'inscription. | Actif |
| L1 | Auto-déclaré | Nom, date de naissance, adresse fournis et cohérents. | Actif |
| L2 | Vérification documentaire | Document d'identité émis par l'État. Champs OCR validés. Empreinte stockée. | Actif |
| L3 | Vérification biométrique | Document + détection de présence + correspondance faciale. | Gelé — pas en production |
| L4 | Supervision en personne | Toutes les preuves L3 collectées par un agent habilité. | Gelé — pas en production |
KycDecisionService.approve() refuse d'élever kyc_profiles.current_level au-delà de L2 jusqu'à l'approbation d'une intégration biométrique de production. Le plafond est appliqué par IdentityAssuranceLevel.capAtFreezeLevel().
Contrat d'autorisation
L'assurance minimale pour une requête est lue depuis AuthenticationPolicy associée à l'entity ID du SP courant. L'assurance effective pour une décision d'autorisation combine :
kyc_profiles.current_level via KycGateService.effectiveLevelFor(username)AuthenticationPolicy pour le SP et l'action courantsModèle d'état du compte
L'état utilisateur est représenté par deux indicateurs booléens indépendants sur la table users. Les états de présentation comme ACTIVE_LIMITED sont calculés à la demande depuis kyc_profiles.current_level et le minimum de politique SP/action.
| active | pendingApproval | État de présentation | Opérations autorisées |
|---|---|---|---|
true | false | ACTIVE | Accès complet ; pas de porte KYC si assurance ≥ minimum SP |
true | false | ACTIVE_LIMITED (calculé) | Connexion réussie ; émission SAML/OIDC bloquée derrière le flux de jeton de complétion KYC |
false | true | MIGRATED_UNCLAIMED | Le compte existe mais ne peut pas s'authentifier ; l'activation nécessite le flux de réclamation d'identité |
false | false | SUSPENDED | Aucune opération ; déverrouillage administrateur requis |
false | true | PENDING_APPROVAL | Auto-inscrit mais en attente d'activation admin ; bloqué à la connexion |
ACTIVE_LIMITED n'est jamais écrit en base de données. C'est le résultat à l'exécution de : l'utilisateur est actif ET effectiveLevelFor(user) ne satisfait pas policyMinimumFor(spEntityId).
Décisions de source de vérité
Chaque enregistrement d'identité doit porter source_instance_id (système d'origine) et external_id (clé source immuable). La combinaison (source_instance_id, external_id) est indexée de manière unique, empêchant les doublons de comptes provenant de la même source.
Flux d'inscription en libre-service
L'inscription directe via /idp/register crée un compte natif Hawiyati. Le serveur collecte un nom d'utilisateur, un mot de passe, un e-mail et un consentement. La disponibilité du nom d'utilisateur n'est pas vérifiée avant la soumission — la contrainte unique lève une DataIntegrityViolationException que le serveur mappe vers l'erreur générique unique_attribute_taken sans révéler quel champ est pris.
Le RegistrationController.java:311 actuel effectue une pré-vérification if (userService.existsByUsername(username)) avant l'insertion en base. Cela révèle si un nom d'utilisateur est enregistré, permettant l'énumération des comptes. La correction consiste à supprimer entièrement la pré-vérification.
active=true, pendingApproval=false (ou en attente si approbation requise). L'enregistrement de consentement capture la version, l'IP, le user-agent.active=false jusqu'à confirmation.onboarding_continuation stockant uniquement sp_entity_id. Jamais l'URL brute.Inscription par invitation et administration
Lorsque l'inscription est fermée ou restreinte par politique, les administrateurs créent des comptes et invitent les utilisateurs à les réclamer. L'invitation envoie un jeton de réclamation de compte. Le jeton est aléatoire sur 256 bits, stocké en HMAC-SHA256, et à usage unique.
active=false, pendingApproval=true. E-mail ou ID externe défini ; pas encore de mot de passe.AccountClaimTokenService.generate(userId, "CLAIM_LINK", 72) — 256 bits aléatoires, TTL 72h, stocké en hachage SHA-256NotificationOutboxService.enqueueIfAbsent() avec clé de modèle claim-link-v1. Le jeton brut n'est PAS dans la charge utile./account/claim?token=<brut> — jeton vérifié et consommé atomiquement en une mise à jour conditionnelleactive=true, pendingApproval=false. L'utilisateur définit son mot de passe et procède au KYC si requis.Inscription initiée par un SP
Lorsqu'un utilisateur arrive sur Hawiyati depuis un SP (AuthnRequest SAML ou requête d'autorisation OIDC) et n'a pas de compte, le FI doit préserver l'intention commerciale du SP pendant jusqu'à 7 jours. L'état de protocole en direct (AuthnRequest, vérificateur PKCE, nonce) ne vit que 10–15 minutes dans Redis/WebSession.
Stocker une URL brute d'initiation SP et la suivre après l'inscription est une vulnérabilité de redirection ouverte. La correction : stocker uniquement le sp_entity_id enregistré comme clé étrangère vers le registre SP.
Conception de la persistance d'intention
| Ce qui est stocké | Où | TTL | But |
|---|---|---|---|
| État de protocole SAML/OIDC en direct (AuthnRequest, state, nonce, PKCE) | WebSession / Redis | 10–15 min | Au niveau protocole ; l'état expiré est ignoré, jamais rejoué |
| Intention commerciale SP (de quel SP l'utilisateur vient) | Table DB onboarding_continuation | 7 jours | Survit au flux KYC ; consommé par une nouvelle initiation SP à la complétion |
Provisionnement d'entreprise
Les comptes d'entreprise peuvent entrer dans Hawiyati via trois canaux, tous produisant des comptes MIGRATED_UNCLAIMED :
| Canal | Déclencheur | Liaison d'identité | Étape suivante |
|---|---|---|---|
| SCIM 2.0 | POST /scim/v2/Users depuis l'annuaire | external_id + source_instance_id depuis HawiyatiExtension | Jeton de réclamation ou JIT LDAP à la première connexion |
| JIT LDAP | Liaison LDAP réussie à la connexion | DN ou samAccountName mappé sur external_id | Activation immédiate ; période de grâce KYC appliquée |
| Import CSV groupé | L'admin télécharge le fichier, approuve et valide | external_id depuis la colonne CSV | E-mail d'invitation avec jeton de réclamation envoyé à toutes les lignes |
L'extension Hawiyati SCIM (urn:hawiyati:params:scim:schemas:extension:2.0:User) transporte uniquement : externalId, sourceInstanceId, pendingApproval. Les hachages de mots de passe, niveaux d'assurance et champs de migration sont explicitement interdits.
Machine d'état KYC
La vérification KYC est modélisée comme une machine d'état sur KycVerificationSession. Chaque session est limitée à un utilisateur et une tentative.
| État | Signification | Transitions autorisées |
|---|---|---|
| PENDING | Session créée ; en attente du téléchargement du document | → DOCUMENT_UPLOADED |
| DOCUMENT_UPLOADED | Fichier reçu ; traitement OCR en file d'attente | → PROCESSING |
| PROCESSING | Extraction OCR/MRZ en cours | → DOCUMENT_VALIDATED, → PROCESSING_FAILED |
| DOCUMENT_VALIDATED | Champs extraits ; moteur de décision en évaluation | → MANUAL_REVIEW_REQUIRED, → APPROVED (automatique) |
| MANUAL_REVIEW_REQUIRED | Score faible ou alerte doublon ; en attente d'un agent | → APPROVED, → REJECTED |
| APPROVED | Terminal — identité prouvée ; kyc_profiles.current_level mis à jour | — (terminal) |
| REJECTED | Terminal — preuves insuffisantes ; nouvelle session autorisée | — (terminal) |
| PROCESSING_FAILED | Erreur système OCR ; nouvelle tentative possible | → PENDING (nouvelle tentative) |
Preuves et empreinte du document
Lors de la capture d'un document, Hawiyati calcule une empreinte HMAC-SHA256 de l'identité normalisée — pays, type de document et numéro. Un doublon est un signal de risque qui oriente vers la révision manuelle, pas un rejet automatique.
Un hachage SHA-256 du fichier image est contournable par tout recadrage, rotation, ré-encodage ou changement de qualité. L'empreinte HMAC hache uniquement les champs sémantiquement significatifs (pays, type de document, numéro), qui sont stables à travers les variations de capture.
Session de complétion limitée (Porte KYC)
Lorsqu'un utilisateur s'authentifie avec succès mais que son kyc_profiles.current_level ne satisfait pas l'assurance minimale du SP, Hawiyati émet un jeton de complétion de première partie au lieu de lever une exception. Le jeton est stocké côté serveur en HMAC-SHA256, a un TTL de 15 minutes et est à usage unique.
Le LoginController.java:876–901 actuel lève KycRequiredException qui cause un deadlock dans la chaîne réactive. Il utilise un attribut booléen kycRequired sur WebSession qui ne peut pas être validé. Les deux problèmes sont corrigés par cette conception.
Conception du jeton
| Propriété | Valeur |
|---|---|
| Entropie | 256 bits (32 octets, SecureRandom), base64 URL-safe ≥43 caractères |
| Forme stockée | Hachage SHA-256 uniquement — jeton brut jamais persisté |
| TTL | 15 minutes (expiresAt = MAINTENANT() + 900s) |
| Cardinalité | Usage unique ; consommé atomiquement lors de la validation |
| Liaisons | userId, spEntityId, purpose = KYC_COMPLETION |
| Table | hawiyati_identity.identity_completion_session (V54) |
Liste blanche des routes — ce qu'un jeton de complétion autorise
/account/statusAUTORISÉ/account/kyc/**AUTORISÉ/account/consent/**AUTORISÉ/logoutAUTORISÉ/saml/idp/ssoREFUSÉ — pas d'émission d'assertion/oidc/tokenREFUSÉ — pas d'émission de jeton/api/**REFUSÉ — pas d'accès API général
Continuation de transaction SP
Lorsqu'un utilisateur arrive d'un SP et doit s'inscrire ou compléter KYC avant que l'assertion SP puisse être émise, le FI doit mémoriser de quel SP il vient pendant jusqu'à 7 jours. C'est la table onboarding_continuation introduite en V55.
Comme seul un entity ID de SP enregistré est stocké (pas l'URL fournie par l'appelant), un attaquant qui obtient un jeton de continuation ne peut pas rediriger l'utilisateur vers un domaine arbitraire.
Jetons de réclamation de compte
Les jetons de réclamation sont liés à un but et un utilisateur, à usage unique, utilisés pour les flux d'invitation, les liens de réinitialisation de mot de passe et l'activation de migration.
| Menace | Atténuation |
|---|---|
| Rediffusion de jeton | Mise à jour conditionnelle atomique à usage unique |
| Force brute | Espace de jeton 256 bits = 2256 — infaisable ; point de terminaison limité en débit |
| Mauvais canal | Liaison de colonne purpose — un jeton de réinitialisation de mot de passe ne peut pas être utilisé pour une réclamation de compte |
| Réclamation croisée | Liaison userId — jeton remboursable uniquement pour l'utilisateur pour lequel il a été créé |
| Double remboursement concurrent | UPDATE conditionnel vérifiant consumed=FALSE ; exactement un thread concurrent gagne |
Modèle de provisionnement SCIM
Hawiyati implémente le provisionnement entrant SCIM 2.0 sur hawiyati-scim (port 8098). L'extension Hawiyati transporte uniquement les champs nécessaires à la corrélation d'identité.
L'extension SCIM ne doit jamais accepter : importedPasswordHash, assuranceLevel, migrationTier ou tout champ de justificatif. Ces champs sont exclus du mapping de champs — pas seulement ignorés.
Chaque compte créé via SCIM entre en état active=false, pendingApproval=true (MIGRATED_UNCLAIMED). Le compte ne peut pas s'authentifier tant que l'utilisateur ne l'a pas réclamé via l'e-mail d'invitation.
Import CSV groupé gouverné
Le pipeline d'import groupé permet aux administrateurs de créer de nombreux comptes à partir d'un fichier CSV. Il utilise un flux d'approbation par étapes pour prévenir la création massive accidentelle de comptes. Maximum 50 000 lignes, 50 Mo.
Étapes du pipeline
POST /api/v1/import/batches. En-tête validé.import_batch_row. Doublons signalés. Aucun compte créé encore.external_id en doublon sont IGNORÉES avec raison. Idempotent.active=false, pendingApproval=true. Jetons de réclamation générés. Notifications mises en file d'attente via outbox.Colonnes CSV requises
external_id,username,email,first_name,last_name
Boîte d'envoi de notifications
Toutes les notifications sortantes (liens de réclamation, e-mails d'activation, mises à jour de statut KYC) sont écrites dans la table notification_outbox (V59) dans la même transaction que l'action déclenchante. Un service de distribution en arrière-plan les lit et les envoie.
| Propriété | Valeur |
|---|---|
| Sécurité multi-nœuds | SELECT … FOR UPDATE SKIP LOCKED — deux nœuds distribuant simultanément revendiquent des lignes disjointes |
| Idempotence | Colonne unique idempotency_key ; enqueueIfAbsent() est sans effet si la clé existe |
| Contenu de la charge utile | Clé de modèle + paramètres uniquement — pas de jetons bruts, pas d'URL brutes |
| Calendrier de relance | Reprise exponentielle : 30s → 2min → 8min → 32min → 128min (après 5 tentatives : DEAD) |
| Taille de lot | 50 lignes par cycle de distribution |
Phases de livraison A–F
| Phase | Portée | Condition préalable |
|---|---|---|
| A | Prérequis d'architecture — trois documents de conception (modèle d'assurance, modèle de menace, pattern API admin) | Les trois docs approuvés avant toute migration de schéma |
| B | Corrections P0/P1 — correctif d'énumération, enum d'assurance, jeton de complétion (V54), continuation (V55), empreinte (V56), test consentement | Docs Phase A approuvés |
| C | Réclamation de compte (V57), nettoyage SCIM (V58), outbox (V59), API cycle de vie admin | Phase B terminée |
| D | Import CSV groupé gouverné (V60) | Phase C terminée |
| E | DIFFÉRÉ — continuité des justificatifs (migration de hachage, proxy JIT). Nécessite une conception de sécurité séparée et une acceptation des risques. | Conception de sécurité séparée approuvée |
| F | DIFFÉRÉ — opérations, flux de revérification, outils de support client | Phase D stable en production |
Le plan original incluait les tâches 8 et 9 : importation de hachages de mots de passe et proxy d'authentification JIT. Les deux nécessitent un modèle de menace séparé : (1) les chaînes d'algorithme provenant des appelants ne sont pas fiables, (2) PBKDF2/Argon2 nécessitent des profils de paramètres exacts, (3) SHA-256 seul affaiblit matériellement l'authentification, (4) un point de terminaison proxy configurable est une surface SSRF. Alternatives préférées : continuité fédération/LDAP, jeton de réclamation + réinitialisation de mot de passe, ou service connecteur durci.
Séquence de migrations (V54–V60)
Ce guide a été rédigé lorsque la tête Flyway était V53. La tête actuelle au 2026-10-17 est V62. Renumérotez les migrations à partir de V63 avant d'implémenter, et vérifiez la tête en production avec SELECT version FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 1.
P0 — Corrections critiques
Ces problèmes sont des vulnérabilités de sécurité ou des bloqueurs fonctionnels qui empêchent le flux d'inscription de fonctionner correctement. Ils doivent tous être corrigés avant tout trafic de production.
- Supprimer le bloc
if (userService.existsByUsername(username))dansRegistrationController.java:311 - Vérifier que le catch
DataIntegrityViolationExceptionretourneunique_attribute_taken
KycRequiredException actuel cause un deadlock dans la chaîne réactive. Remplacer par un jeton de complétion de première partie (V54).- Créer la migration V54 : table
identity_completion_session - Créer
CompletionSessionServiceavecissue(),validate(),isAllowedRoute() - Ajouter WebFilter refusant les points de terminaison d'émission SAML/OIDC quand seul un jeton de complétion est présent
KycDecisionService.approve() doit mettre à jour uniquement kyc_profiles.current_level. Plafonner à L2 jusqu'à approbation biométrique.