Cycle de vie des identités
Inscription des utilisateurs, niveaux d'assurance (L0–L4), états des comptes, modes de politique et flux KYC.
Inscription des utilisateurs, niveaux d'assurance (L0–L4), états des comptes, modes de politique et flux KYC.
Objectif & Périmètre
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.
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.
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 ».
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.
| Niveau | Nom | Signification | Flux Hawiyati | Usage 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.
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.
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.
| État | active | pendingApproval | Peut s'auth. ? | Portée d'accès | Comment atteint |
|---|---|---|---|---|---|
| EN_ATTENTE_ACTIVATION | false | false |
Non | Aucune | Nouvelle auto-inscription, e-mail non encore vérifié |
| EN_ATTENTE_APPROBATION | false | true |
Non | Aucune | E-mail vérifié, en attente d'approbation administrative (adminApprovalRequired = true) |
| MIGRÉ_NON_RÉCLAMÉ | false | true |
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 | true | false |
Oui — complet | Complet (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é) | true | false |
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 | false | false |
Non | Aucune | Action administrative — verrouillage temporaire |
| VERROUILLÉ | false | false |
Non | Aucune | Trop de tentatives d'authentification échouées (protection contre la force brute) |
| INACTIF | false | false |
Non | Aucune | Inactivité prolongée (tâche planifiée selon la politique de rétention) |
| ARCHIVÉ | false | false |
Non | Aucune | Archivé par l'administrateur — données préservées pour la conformité |
| EN_ATTENTE_SUPPRESSION | variable | variable | Non | Aucune | Suppression demandée ; période de grâce de rétention en cours |
| SUPPRIMÉ | — | — | Non | Aucune | 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.
| Niveau | Quand l'utiliser | Expérience utilisateur | Ce 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 :
| Mode | Configuration | Comportement | Recommandé pour |
|---|---|---|---|
| Ouvert | openRegistration = trueadminApprovalRequired = 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 = trueadminApprovalRequired = 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 politique | Effet lorsque défini |
|---|---|
openRegistration | /idp/register public accepte de nouveaux utilisateurs |
adminApprovalRequired | Les comptes inscrits démarrent EN_ATTENTE_APPROBATION ; contourné par les jetons d'invitation |
botProtectionEnabled | CAPTCHA / défi sur l'étape d'identité |
tosVersionRequired | L'utilisateur doit accepter les Conditions d'utilisation ; version suivie par utilisateur |
minimumAssuranceLevel | Connexion 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
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
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 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
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.
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é.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.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.onboarding_continuation le cas échéant. L'utilisateur atterrit dans son application cible.Flux KYC / Vérification d'identité
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.
/account/kyc). L'utilisateur sélectionne le type de document : CIN, Passeport, Permis de conduire ou Passeport étranger.image/jpeg, image/png, image/webp, max 10 Mo par image.202 Accepted avec processingId. Le portail de compte interroge le statut./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.kyc_profiles.current_level), Rejeter (avec motif : DOCUMENT_EXPIRÉ, IMAGE_ILLISIBLE, MISMATCH_MRZ, MISMATCH_FACIAL), ou Demander une re-vérification.Flux de migration — Parcours MIGRÉ_NON_RÉCLAMÉ
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.
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.MIGRÉ_NON_RÉCLAMÉ → ACTIF_LIMITÉ.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.