H· Hawiyati Documentation
Documentation Hawiyati

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.

Documentation Hawiyati

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é.

Principe de conception

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énarioUtilisateur principalChemin d'entréeKYC requis
Grand public greenfieldUtilisateur finalLibre-service /idp/registerPiloté par politique ; L1 par défaut pour la plupart des SP
Entreprise / personnelEmployé ou prestataireProvisionnement SCIM, JIT LDAP, invitation ou import CSVTransfert d'assurance source ou période de grâce
Initié par le SPUtilisateur arrivant d'un serviceAuthnRequest SAML ou autorisation OIDC → inscriptionAssurance minimale SP déclenche la porte KYC après connexion

Niveaux d'assurance L0–L4

NiveauNomPreuves requisesStatut
L0Non vérifiéConfirmation e-mail ou téléphone uniquement. Niveau par défaut à l'inscription.Actif
L1Auto-déclaréNom, date de naissance, adresse fournis et cohérents.Actif
L2Vérification documentaireDocument d'identité émis par l'État. Champs OCR validés. Empreinte stockée.Actif
L3Vérification biométriqueDocument + détection de présence + correspondance faciale.Gelé — pas en production
L4Supervision en personneToutes les preuves L3 collectées par un agent habilité.Gelé — pas en production
Gel L3/L4 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 :

1
Assurance de preuve d'identité (IAL)
kyc_profiles.current_level via KycGateService.effectiveLevelFor(username)
2
Assurance d'authentification (AAL)
Facteur utilisé dans la session courante — mot de passe seul = AAL1, TOTP/FIDO2/passkey = AAL2
3
Minimum de politique SP
Lu depuis AuthenticationPolicy pour le SP et l'action courants
✓
Décision
Si effectif ≥ requis → émettre l'assertion. Sinon → jeton de complétion et porte KYC.

Modè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.

activependingApprovalÉtat de présentationOpérations autorisées
truefalseACTIVEAccès complet ; pas de porte KYC si assurance ≥ minimum SP
truefalseACTIVE_LIMITED (calculé)Connexion réussie ; émission SAML/OIDC bloquée derrière le flux de jeton de complétion KYC
falsetrueMIGRATED_UNCLAIMEDLe compte existe mais ne peut pas s'authentifier ; l'activation nécessite le flux de réclamation d'identité
falsefalseSUSPENDEDAucune opération ; déverrouillage administrateur requis
falsetruePENDING_APPROVALAuto-inscrit mais en attente d'activation admin ; bloqué à la connexion
ACTIVE_LIMITED n'est pas stocké

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é

Arbre de décision pour le choix du parcours d'intégration principal
Choisir un seul parcours d'intégration de référence par population afin d'éviter les identités dupliquées ou conflictuelles.

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.

Cycle de vie identitaire depuis la création jusqu'à la suppression
L'inscription est le début d'un cycle de vie gouverné, pas simplement un formulaire de création de compte.

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.

Faille de sécurité P0 — ACT-P0-01

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.

1
Soumission du formulaire
L'utilisateur soumet nom d'utilisateur, mot de passe, e-mail, OTP (si requis), version de consentement
2
Évaluation de la politique
La politique d'inscription vérifie : domaines autorisés, approbation requise, KYC requis, obligation MFA
3
Création du compte
Insertion utilisateur : active=true, pendingApproval=false (ou en attente si approbation requise). L'enregistrement de consentement capture la version, l'IP, le user-agent.
4
Vérification e-mail / OTP
Si la vérification e-mail est configurée, envoyer le lien. Le compte est active=false jusqu'à confirmation.
5
Continuation SP (si initié par SP)
Si l'inscription est arrivée via un flux SAML/OIDC, créer un enregistrement onboarding_continuation stockant uniquement sp_entity_id. Jamais l'URL brute.
✓
Activation terminée
L'utilisateur arrive au portail de compte ou est redirigé vers le SP (si jeton de continuation présent)

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.

1
L'admin crée le compte
active=false, pendingApproval=true. E-mail ou ID externe défini ; pas encore de mot de passe.
2
Jeton de réclamation généré
AccountClaimTokenService.generate(userId, "CLAIM_LINK", 72) — 256 bits aléatoires, TTL 72h, stocké en hachage SHA-256
3
Notification mise en file d'attente
NotificationOutboxService.enqueueIfAbsent() avec clé de modèle claim-link-v1. Le jeton brut n'est PAS dans la charge utile.
4
L'utilisateur clique sur le lien e-mail
Le navigateur accède à /account/claim?token=<brut> — jeton vérifié et consommé atomiquement en une mise à jour conditionnelle
✓
Compte activé
active=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.

Risque de redirection ouverte — ACT-P0-05

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ùTTLBut
État de protocole SAML/OIDC en direct (AuthnRequest, state, nonce, PKCE)WebSession / Redis10–15 minAu niveau protocole ; l'état expiré est ignoré, jamais rejoué
Intention commerciale SP (de quel SP l'utilisateur vient)Table DB onboarding_continuation7 joursSurvit 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 :

CanalDéclencheurLiaison d'identitéÉtape suivante
SCIM 2.0POST /scim/v2/Users depuis l'annuaireexternal_id + source_instance_id depuis HawiyatiExtensionJeton de réclamation ou JIT LDAP à la première connexion
JIT LDAPLiaison LDAP réussie à la connexionDN ou samAccountName mappé sur external_idActivation immédiate ; période de grâce KYC appliquée
Import CSV groupéL'admin télécharge le fichier, approuve et valideexternal_id depuis la colonne CSVE-mail d'invitation avec jeton de réclamation envoyé à toutes les lignes
Extension SCIM — champs autorisés uniquement

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.

Flux KYC : capture, validation, biométrie, risque, révision et décision
La politique d'assurance détermine quelles étapes biométriques et de révision manuelle sont requises.

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.

ÉtatSignificationTransitions autorisées
PENDINGSession créée ; en attente du téléchargement du document→ DOCUMENT_UPLOADED
DOCUMENT_UPLOADEDFichier reçu ; traitement OCR en file d'attente→ PROCESSING
PROCESSINGExtraction OCR/MRZ en cours→ DOCUMENT_VALIDATED, → PROCESSING_FAILED
DOCUMENT_VALIDATEDChamps extraits ; moteur de décision en évaluation→ MANUAL_REVIEW_REQUIRED, → APPROVED (automatique)
MANUAL_REVIEW_REQUIREDScore faible ou alerte doublon ; en attente d'un agent→ APPROVED, → REJECTED
APPROVEDTerminal — identité prouvée ; kyc_profiles.current_level mis à jour— (terminal)
REJECTEDTerminal — preuves insuffisantes ; nouvelle session autorisée— (terminal)
PROCESSING_FAILEDErreur 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.

Pourquoi pas un hachage de fichier ?

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.

Faille P0 — ACT-P0-03 — porte KYC en deadlock

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
Entropie256 bits (32 octets, SecureRandom), base64 URL-safe ≥43 caractères
Forme stockéeHachage SHA-256 uniquement — jeton brut jamais persisté
TTL15 minutes (expiresAt = MAINTENANT() + 900s)
CardinalitéUsage unique ; consommé atomiquement lors de la validation
LiaisonsuserId, spEntityId, purpose = KYC_COMPLETION
Tablehawiyati_identity.identity_completion_session (V54)

Liste blanche des routes — ce qu'un jeton de complétion autorise

  • /account/status AUTORISÉ
  • /account/kyc/** AUTORISÉ
  • /account/consent/** AUTORISÉ
  • /logout AUTORISÉ
  • /saml/idp/sso REFUSÉ — pas d'émission d'assertion
  • /oidc/token REFUSÉ — 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.

Prévention de redirection ouverte

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.

Flux sécurisé d'invitation et de réclamation de compte
Les jetons de réclamation sont des points d'entrée à usage unique ; la correspondance d'identité et la liaison d'authentificateur complètent la réclamation.

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.

MenaceAtténuation
Rediffusion de jetonMise à jour conditionnelle atomique à usage unique
Force bruteEspace de jeton 256 bits = 2256 — infaisable ; point de terminaison limité en débit
Mauvais canalLiaison 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éeLiaison userId — jeton remboursable uniquement pour l'utilisateur pour lequel il a été créé
Double remboursement concurrentUPDATE conditionnel vérifiant consumed=FALSE ; exactement un thread concurrent gagne
Séquence de provisionnement et réconciliation SCIM
La source d'entreprise reste autoritaire tandis que Hawiyati applique les contrôles locaux de sécurité et d'audit.

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é.

Explicitement interdit

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

1
UPLOADED
L'admin soumet le fichier CSV via POST /api/v1/import/batches. En-tête validé.
2
DRY_RUN_COMPLETE
Toutes les lignes analysées et mises en attente dans import_batch_row. Doublons signalés. Aucun compte créé encore.
3
APPROVED
SUPER_ADMIN examine le résumé et approuve. Horodatage et ID approbateur enregistrés.
4
COMMITTING
Comptes créés ligne par ligne. Les lignes avec external_id en doublon sont IGNORÉES avec raison. Idempotent.
✓
DONE
Toutes les lignes validées : 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œudsSELECT … FOR UPDATE SKIP LOCKED — deux nœuds distribuant simultanément revendiquent des lignes disjointes
IdempotenceColonne unique idempotency_key ; enqueueIfAbsent() est sans effet si la clé existe
Contenu de la charge utileClé de modèle + paramètres uniquement — pas de jetons bruts, pas d'URL brutes
Calendrier de relanceReprise exponentielle : 30s → 2min → 8min → 32min → 128min (après 5 tentatives : DEAD)
Taille de lot50 lignes par cycle de distribution

Phases de livraison A–F

PhasePortéeCondition préalable
APré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
BCorrections P0/P1 — correctif d'énumération, enum d'assurance, jeton de complétion (V54), continuation (V55), empreinte (V56), test consentementDocs Phase A approuvés
CRéclamation de compte (V57), nettoyage SCIM (V58), outbox (V59), API cycle de vie adminPhase B terminée
DImport CSV groupé gouverné (V60)Phase C terminée
EDIFFÉ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
FDIFFÉRÉ — opérations, flux de revérification, outils de support clientPhase D stable en production
Phase E — continuité des justificatifs est différée

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.

Flux de migration gouvernée et réconciliation des comptes
Exécutions à blanc, pilotes, portes d'acceptation, réclamation de compte et réconciliation post-bascule réduisent le risque migratoire.

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.

V54identity_completion_sessionJeton de complétion KYC de première partie ; haché, TTL 15 min, usage uniqueB3
V55onboarding_continuationPersistance d'intention SP ; stocke uniquement l'entity ID SP, jamais l'URL bruteB4
V56document_fingerprintHMAC-SHA256 du pays|type|numéro normalisé dans le schéma hawiyati_identityB5
V57account_claim_tokenJetons d'invitation et de réclamation liés à un but et un utilisateur, à usage uniqueC1
V58ALTER usersAjoute les colonnes external_id et source_instance_id ; index unique (source, externe)C2
V59notification_outboxBoîte d'envoi transactionnelle avec distribution SKIP LOCKED et reprise exponentielleC3
V60import_batch + import_batch_rowTables d'import groupé gouverné avec flux par étapes (UPLOADED→DRY_RUN→APPROVED→DONE)D1

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 la pré-vérification d'énumération de noms d'utilisateurACT-P0-01
Une vérification préalable d'existence avant l'insertion en base révèle si un nom d'utilisateur est pris. Supprimer entièrement la pré-vérification et s'appuyer uniquement sur l'exception de contrainte.
  • Supprimer le bloc if (userService.existsByUsername(username)) dans RegistrationController.java:311
  • Vérifier que le catch DataIntegrityViolationException retourne unique_attribute_taken
Remplacer la porte KYC en deadlock par un jeton de complétionACT-P0-03
Le chemin 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 CompletionSessionService avec issue(), validate(), isAllowedRoute()
  • Ajouter WebFilter refusant les points de terminaison d'émission SAML/OIDC quand seul un jeton de complétion est présent
Enum IdentityAssuranceLevel typé + mise à jour du profil KYCACT-P0-04
Remplacer les comparaisons de chaînes brutes par un enum typé. KycDecisionService.approve() doit mettre à jour uniquement kyc_profiles.current_level. Plafonner à L2 jusqu'à approbation biométrique.
Continuation d'inscription sécurisée — entity ID SP uniquementACT-P0-05
Stocker uniquement l'entity ID SP enregistré, jamais une URL d'initiation brute. Correction de la redirection ouverte.