H· Hawiyati Documentation
Documentation Hawiyati

Cycle de vie des identités

Inscription des utilisateurs, niveaux d'assurance (L0–L4), états des comptes, modes de politique et flux KYC.

Documentation Hawiyati

Inscription des utilisateurs, niveaux d'assurance (L0–L4), états des comptes, modes de politique et flux KYC.

Objectif & Périmètre

Périmètre Ce document décrit comment les utilisateurs sont créés, vérifiés et activés dans Hawiyati. Il couvre trois scénarios de déploiement, le cadre des Niveaux d'assurance (L0–L4) pour standardiser la confiance d'identité, le modèle d'état des comptes, et les actions d'implémentation pour toutes les lacunes identifiées.

Hawiyati prend en charge plusieurs routes d'inscription et d'intégration : libre-service, basé sur invitation, provisionnement SCIM, LDAP/AD, et création par l'administrateur. Le choix de la route détermine les états de compte pertinents et les niveaux d'assurance applicables.

Contrainte de gouvernance Les correctifs OCR/MRZ dans lab/ocr-mrz-test ne doivent PAS être synchronisés vers hawiyati-kyc avant confirmation explicite. Toutes les autres actions d'implémentation sont indépendantes de cette contrainte.
Voir également Pour l'analyse technique complète incluant la machine d'état KYC, l'empreinte documentaire, les jetons de complétion et les détails des migrations Flyway, consultez le Guide d'inscription, KYC & Migration.

Niveaux d'assurance (L0–L4)

Hawiyati adopte un modèle d'assurance d'identité à cinq niveaux aligné sur NIST SP 800-63A-4 (Niveau d'assurance d'identité) et les recommandations du GAFI. Le libellé du niveau d'assurance apparaît dans le code, la documentation, l'interface de la console d'administration et les réponses API — remplaçant le langage informel tel que « vérifié » ou « KYC de base ».

Source de vérité Le niveau d'assurance faisant autorité est stocké exclusivement dans kyc_profiles.current_level. Il n'est jamais dérivé des indicateurs de statut de compte (active, pendingApproval). Traitez le champ assuranceLevel sur l'entité de compte comme une copie mise en cache synchronisée depuis le profil KYC.
NiveauNomSignificationFlux HawiyatiUsage typique
L0 Aucun Aucun compte n'existe. Visiteur non reconnu ou état pré-inscription. Anonyme / pré-inscription Accès anonyme uniquement
L1 Basique Canal vérifié (e-mail ou SMS OTP) plus authentificateur inscrit (mot de passe ou clé d'accès). Identité non vérifiée par rapport à une source faisant autorité. Flux d'auto-inscription complété Applications grand public, services à faible risque
L2 Standard L1 plus document d'identité validé (extraction OCR + MRZ) avec vérifications de cohérence et approbation du réviseur. KYC_APPROUVÉ après examen documentaire Services financiers, applications grand public réglementées
L3 Fort L2 plus détection de vivacité et correspondance biométrique avec la photo du document. KYC_APPROUVÉ avec vivacité + correspondance faciale confirmée Transactions à haute valeur, conformité LAB
L4 Haute assurance Vérification faisant autorité ou supervisée : en présentiel, notariée ou par un tiers de confiance. L3 plus file de révision humaine. Futur — dérogation manuelle par administrateur privilégié Gouvernement, signature électronique, infrastructure critique

Niveau d'assurance dans le code

Un champ assuranceLevel (énumération L0..L4) est stocké sur l'entité de compte utilisateur et retourné dans les réponses API. Les politiques d'authentification référencent minimumAssuranceLevel à la place de l'indicateur binaire hérité kycRequired. Les politiques kycRequired = true existantes migrent vers minimumAssuranceLevel = L2.

Progression des niveaux d'assurance KYC L0 (Aucun) → L1 (Basique : inscription) → L2 (Standard : OCR/MRZ approuvé) → L3 (Fort : vivacité + correspondance faciale) → L4 (Haute assurance : révision humaine). Stocké dans kyc_profiles.current_level — jamais dérivé des indicateurs de compte.

États des comptes

Le statut du compte est déterminé par deux indicateurs booléens dans la table accounts : active et pendingApproval. Ces indicateurs, combinés avec le niveau d'assurance, définissent l'état complet du cycle de vie d'un compte.

Important : ACTIF_LIMITÉ est calculé, pas stocké ACTIF_LIMITÉ est un état calculé — il n'existe pas de colonne de base de données pour cela. Il est dérivé à l'exécution lorsqu'un compte est active=true mais n'a pas encore atteint le minimumAssuranceLevel requis par sa politique d'authentification. N'écrivez jamais de code qui stocke ou persiste cet état.
ÉtatactivependingApprovalPeut s'auth. ?Portée d'accèsComment atteint
EN_ATTENTE_ACTIVATION falsefalse NonAucune Nouvelle auto-inscription, e-mail non encore vérifié
EN_ATTENTE_APPROBATION falsetrue NonAucune E-mail vérifié, en attente d'approbation administrative (adminApprovalRequired = true)
MIGRÉ_NON_RÉCLAMÉ falsetrue Non (aucun identifiant)Aucune jusqu'à revendication Import en masse SCIM ou tâche d'import gouverné — la personne réelle n'a pas encore revendiqué le compte
ACTIF truefalse Oui — completComplet (sous réserve du contrôle d'assurance) Approuvé depuis EN_ATTENTE ; inscription ouverte auto-approuvée ; provisionnement SCIM ; création par administrateur
ACTIF_LIMITÉ (calculé) truefalse Oui — limité/account/kyc/**, /account/status uniquement ACTIF mais niveau d'assurance inférieur au minimumAssuranceLevel de la politique. Impossible d'obtenir des jetons FS.
SUSPENDU falsefalse NonAucune Action administrative — verrouillage temporaire
VERROUILLÉ falsefalse NonAucune Trop de tentatives d'authentification échouées (protection contre la force brute)
INACTIF falsefalse NonAucune Inactivité prolongée (tâche planifiée selon la politique de rétention)
ARCHIVÉ falsefalse NonAucune Archivé par l'administrateur — données préservées pour la conformité
EN_ATTENTE_SUPPRESSION variablevariable NonAucune Suppression demandée ; période de grâce de rétention en cours
SUPPRIMÉ —— NonAucune Suppression douce ; piste d'audit préservée selon la politique de rétention des données

MIGRÉ_NON_RÉCLAMÉ — Migration d'identifiants à trois niveaux

MIGRÉ_NON_RÉCLAMÉ diffère d'EN_ATTENTE_APPROBATION. EN_ATTENTE_APPROBATION signifie que la personne s'est auto-inscrite et attend l'approbation administrative. MIGRÉ_NON_RÉCLAMÉ signifie qu'un administrateur a créé l'enregistrement depuis un fichier de données de migration — la personne réelle ne s'est pas encore authentifiée contre Hawiyati.

NiveauQuand l'utiliserExpérience utilisateurCe que l'organisation fournit
Niveau 1 — Migration de hachage L'organisation peut exporter des hachages de mots de passe (bcrypt, PBKDF2, Argon2, SHA-256+sel) L'utilisateur se connecte avec son nom d'utilisateur + mot de passe existants. Totalement transparent. Mots de passe hachés dans le manifeste d'import
Niveau 2 — Migration JIT proxy Format de hachage inconnu ; l'organisation peut exposer un point de terminaison d'authentification hérité (REST ou LDAP) L'utilisateur se connecte avec ses identifiants existants. Hawiyati proxy vers le système hérité à la première connexion. Transparent ensuite. URL du point de terminaison d'auth hérité + identifiant
Niveau 3 — Lien de revendication Aucune migration d'identifiant possible (système hors ligne, HSM propriétaire, politique) L'utilisateur reçoit un lien de revendication signé par e-mail/SMS ; crée un nouveau mot de passe. Adresses e-mail/téléphone uniquement

ACTIF_LIMITÉ — Résolution du blocage KYC

Sans ACTIF_LIMITÉ, un utilisateur avec minimumAssuranceLevel = L2 est bloqué à la connexion mais n'a pas de session authentifiée pour atteindre la page de soumission KYC — une impasse. ACTIF_LIMITÉ résout cela : LoginController émet une session limitée qui accorde l'accès uniquement aux points de terminaison de complétion du portail de compte mais ne peut pas être utilisée pour obtenir des jetons FS (assertions SAML, id_token OIDC).

Modes de politique

Le comportement d'inscription et KYC est gouverné par des indicateurs de politique par locataire. Les trois modes d'inscription principaux sont :

ModeConfigurationComportementRecommandé pour
Ouvert openRegistration = true
adminApprovalRequired = false
Toute personne peut s'auto-inscrire sur /idp/register. Les comptes sont activés automatiquement dès la vérification de l'e-mail. Applications grand public, services publics, plateformes à faible risque
Approbation requise openRegistration = true
adminApprovalRequired = true
L'auto-inscription est autorisée mais les comptes entrent dans EN_ATTENTE_APPROBATION et nécessitent une révision administrative avant de devenir ACTIFS. Les jetons d'invitation contournent cette étape. Services réglementés, pilotes gouvernementaux, programmes bêta
Sur invitation uniquement openRegistration = false /idp/register public est désactivé. Seuls les jetons d'invitation, le provisionnement SCIM ou les comptes créés par l'administrateur peuvent créer des utilisateurs. Déploiements d'entreprise, IAM de main-d'œuvre, systèmes fermés
Indicateur de politiqueEffet lorsque défini
openRegistration/idp/register public accepte de nouveaux utilisateurs
adminApprovalRequiredLes comptes inscrits démarrent EN_ATTENTE_APPROBATION ; contourné par les jetons d'invitation
botProtectionEnabledCAPTCHA / défi sur l'étape d'identité
tosVersionRequiredL'utilisateur doit accepter les Conditions d'utilisation ; version suivie par utilisateur
minimumAssuranceLevelConnexion bloquée (ACTIF_LIMITÉ) jusqu'à ce que l'utilisateur atteigne ce niveau d'assurance. Remplace le binaire kycRequired. L2 = examen documentaire, L3 = vivacité + correspondance faciale.

Cas d'usage

Trois scénarios de déploiement principaux déterminent la configuration de Hawiyati et les parcours d'intégration utilisés.

Cas d'usage A — Déploiement Greenfield

Scénario Aucun utilisateur préexistant. L'organisation déploie Hawiyati pour la première fois et doit décider comment les utilisateurs entrent dans le système.

Option A1 — Auto-inscription

Activez openRegistration = true. Les utilisateurs complètent le formulaire multi-étapes sur /idp/register et sont immédiatement ACTIFS (ou EN_ATTENTE_APPROBATION si le mode d'approbation est activé). Recommandé pour les plateformes orientées grand public.

Option A2 — Intégration basée sur invitation

Définissez openRegistration = false. L'administrateur génère des jetons d'invitation via POST /api/admin/invitations et envoie aux utilisateurs un lien /idp/register?invite=<jeton>. Les jetons contournent à la fois openRegistration et adminApprovalRequired. Recommandé pour les déploiements d'entreprise et les pilotes gouvernementaux.

Option A3 — L'administrateur ou SCIM crée les comptes

Laissez openRegistration = false. L'administrateur crée les comptes individuellement via la console, ou les provisionne via SCIM 2.0 (hawiyati-scim port 8098). Les utilisateurs reçoivent leurs identifiants via un lien d'activation par e-mail de bienvenue.

Cas d'usage B — Migration d'organisation

Scénario Une organisation migre une base d'utilisateurs existante vers Hawiyati. Les utilisateurs ont des comptes dans un autre système — LDAP, un FI hérité, une application SaaS ou une base de données personnalisée.

Utilisez la tâche d'import gouverné (POST /api/admin/import/users). Le système déduplique, valide et crée des comptes avec le statut MIGRÉ_NON_RÉCLAMÉ. Des liens de revendication signés à usage unique (HMAC-SHA256, TTL 48h) sont envoyés à chaque e-mail/téléphone importé. Les comptes non réclamés après l'échéance sont suspendus selon la politique de rétention des données.

Cas d'usage C — Connexion initiée par le FS (nouvel utilisateur)

Scénario Un fournisseur de services SAML ou OIDC redirige un utilisateur non authentifié vers Hawiyati. L'utilisateur peut ou non avoir un compte.

Scénario C1 — L'utilisateur a un compte existant

Authentification normale. En cas de succès, le FI reprend le flux initié par le FS et émet une réponse SAML ou un jeton OIDC. L'utilisateur atterrit dans l'application FS.

Scénario C2 — Aucun compte ; l'inscription est ouverte

Le contexte FS est préservé dans la session. Après inscription + connexion, le FI reprend automatiquement le flux FS. L'utilisateur atterrit dans le FS sans réinitier depuis le côté FS.

Scénario C3 — Aucun compte ; l'inscription est fermée

L'utilisateur reçoit un jeton d'invitation. Après la création du compte, l'utilisateur doit réinitier le flux FS. Le contexte de transaction FS a expiré à ce moment-là.

Flux d'inscription cible

Arbre de décision du parcours d'intégration identitaire
Choisir un seul parcours d'intégration de référence par population.

Le flux d'auto-inscription cible intègre les niveaux d'assurance, l'état ACTIF_LIMITÉ et la correction de l'énumération des noms d'utilisateur. Les parcours par invitation et création par administrateur partagent les phases 2 à 5.

1
Phase 1 — Identité (nom · e-mail · téléphone)
L'utilisateur soumet ses informations d'identité. Si le nom d'utilisateur est déjà pris, une erreur générique « vérifiez vos informations » est retournée — jamais « nom d'utilisateur pris » — pour prévenir l'énumération des comptes (correction OWASP A07). Protection anti-robot et limitation de débit appliquées si configurées.
2
Phase 2 — Vérification OTP
L'OTP par e-mail ou SMS prouve la possession du canal. L'OTP est limité dans le temps et à usage unique. Après vérification, le canal est marqué comme vérifié.
3
Phase 3 — Conditions d'utilisation (si requises)
Si tosVersionRequired est défini, l'utilisateur doit accepter les Conditions d'utilisation en vigueur. L'adresse IP, l'agent utilisateur, l'horodatage et la version des CGU sont enregistrés pour la conformité.
4
Phase 4 — Définir un mot de passe / Inscrire une clé d'accès
La politique de mot de passe est appliquée. L'inscription d'une clé d'accès est proposée. Les métadonnées de consentement sont enregistrées.
5
Contrôle — Vérification d'approbation administrative
Si adminApprovalRequired = true, le compte entre dans EN_ATTENTE_APPROBATION. L'administrateur révise et approuve via la console. Si l'inscription est ouverte, passez à l'étape suivante.
6
Contrôle — Vérification du niveau d'assurance
Si le minimumAssuranceLevel est satisfait (généralement L1 après l'inscription), le compte devient ACTIF. Si L2+ est requis, le compte devient ACTIF_LIMITÉ et l'utilisateur est redirigé vers le flux KYC.
7
ACTIF — Accès complet accordé
Les flux initiés par le FS sont repris via l'enregistrement onboarding_continuation le cas échéant. L'utilisateur atterrit dans son application cible.

Flux KYC / Vérification d'identité

Parcours KYC client : capture, validation, biométrie, risque, révision et décision
Le flux KYC guide l'utilisateur de la capture documentaire à la décision d'approbation.

La vérification KYC fait passer le niveau d'assurance d'un utilisateur de L1 à L2 (examen documentaire) ou L3 (vivacité + correspondance faciale). La source de vérité du niveau actuel est toujours kyc_profiles.current_level.

1
L'utilisateur ouvre la Vérification d'identité
Disponible depuis le portail de compte (/account/kyc). L'utilisateur sélectionne le type de document : CIN, Passeport, Permis de conduire ou Passeport étranger.
2
Importation des images du document
Recto + verso (document recto-verso). Le type et la taille du fichier sont validés côté serveur (octets magiques, pas seulement Content-Type). Acceptés : image/jpeg, image/png, image/webp, max 10 Mo par image.
3
hawiyati-kyc traite la soumission
Traitement asynchrone : extraction OCR, analyse MRZ + somme de contrôle, calcul du score de confiance, vérification des doublons par hachage documentaire. L'importation retourne 202 Accepted avec processingId. Le portail de compte interroge le statut.
4
Contrôle du seuil de validation automatique
Si la confiance OCR est inférieure au seuil, la soumission est automatiquement rejetée et l'utilisateur doit soumettre à nouveau. Si au-dessus du seuil, la soumission entre dans la file de révision manuelle.
5
File de révision manuelle
Le réviseur accède à la file KYC de la console d'administration (/kyc/queue). Il examine les champs OCR, les données MRZ, les conflits et le texte brut. Pour L3 : les résultats de vivacité et de correspondance faciale sont également affichés.
6
Décision du réviseur
Le réviseur sélectionne : Approuver (définit le niveau d'assurance L2 ou L3 dans kyc_profiles.current_level), Rejeter (avec motif : DOCUMENT_EXPIRÉ, IMAGE_ILLISIBLE, MISMATCH_MRZ, MISMATCH_FACIAL), ou Demander une re-vérification.
7
KYC_APPROUVÉ — Niveau d'assurance défini
Le compte passe d'ACTIF_LIMITÉ à ACTIF si le contrôle d'assurance est satisfait. Notification envoyée à l'utilisateur via la boîte d'envoi. Si la révision humaine L4 s'applique, le dossier entre dans la file d'administration privilégiée.

Flux de migration — Parcours MIGRÉ_NON_RÉCLAMÉ

Flux sécurisé d'invitation et de réclamation de compte
Les invitations génèrent un jeton de réclamation à usage unique permettant l'activation du compte.

Lors de la migration d'une base d'utilisateurs existante, les comptes sont créés avec l'état MIGRÉ_NON_RÉCLAMÉ. Les utilisateurs revendiquent leurs comptes via un lien signé plutôt qu'en se réinscrivant.

1
Export depuis le système source
Extrayez les enregistrements utilisateurs depuis LDAP, un FI hérité, une application SaaS ou une base de données personnalisée. Incluez au minimum : nom d'utilisateur, e-mail/téléphone, et optionnellement les hachages de mots de passe.
2
Exécuter la tâche d'import gouverné
Importez CSV/JSON dans POST /api/admin/import/users. Le système déduplique, valide et crée des comptes avec le statut MIGRÉ_NON_RÉCLAMÉ. Rapport d'import disponible à la complétion.
3
Liens de revendication envoyés via la boîte d'envoi
Liens de revendication signés à usage unique (HMAC-SHA256, TTL 48h) envoyés à chaque e-mail/téléphone importé. Le tableau de bord administrateur affiche le taux de revendication par lot d'import.
4
L'utilisateur suit le lien de revendication
L'utilisateur suit le lien → vérification OTP → inscription des identifiants (mot de passe ou clé d'accès). Transition du compte : MIGRÉ_NON_RÉCLAMÉ → ACTIF_LIMITÉ.
5
Contrôle du niveau d'assurance
Si minimumAssuranceLevel = L0/L1 : le compte passe directement à ACTIF. Si L2+ requis : le compte reste ACTIF_LIMITÉ et l'utilisateur est dirigé vers le flux KYC.
6
ACTIF — Accès complet accordé
L'utilisateur est entièrement migré. Les comptes non réclamés après l'échéance sont suspendus ou programmés pour désactivation selon la politique de rétention des données.