KYC et vérification d'identité
Gouvernance du niveau d'assurance, flux de vérification documentaire, états de session KYC, documents pris en charge et opérations d'administration.
Gouvernance du niveau d'assurance, flux de vérification documentaire, états de session KYC, documents pris en charge et opérations d'administration.
Vue d'ensemble
La vérification KYC (Connaissance du client) est le mécanisme par lequel Hawiyati élève le niveau d'assurance identitaire d'un utilisateur. Le niveau d'assurance est stocké exclusivement dans kyc_profiles.current_level — jamais dans users.assurance_level, qui est déprécié.
kyc_profiles.current_level est la seule source faisant autorité pour le niveau d'assurance. Toute lecture du niveau d'assurance doit passer par KycGateService.effectiveLevelFor(username).
Niveaux d'assurance L0–L4
Hawiyati définit cinq niveaux d'assurance alignés sur le NIST SP 800-63A-4. Le type Java correspondant est IdentityAssuranceLevel (enum avec satisfies(), fromString() et capAtFreezeLevel()). Les valeurs inconnues échouent à fermeture sur L0.
| Niveau | Nom | Preuves requises | Statut |
|---|---|---|---|
| L0 | Non vérifié | Confirmation par e-mail ou téléphone uniquement — aucun document d'identité. Niveau par défaut à l'inscription. | Actif |
| L1 | Auto-déclaré | Nom, date de naissance, adresse fournis et cohérents ; aucune preuve documentaire requise. | Actif |
| L2 | Vérification documentaire | Document d'identité émis par l'État : CIN algérienne, passeport ou permis de conduire. Champs extraits par OCR passant les contrôles de cohérence. Empreinte du document stockée. | Actif |
| L3 | Vérification biométrique | Vérification documentaire + détection de présence et correspondance faciale avec la puce ou la photo de référence. | Gelé — pas encore en production |
| L4 | Supervision en personne | Toutes les preuves L3 collectées par un agent habilité dans un environnement contrôlé avec traçabilité de la chaîne de garde. | Gelé — pas encore en production |
KycDecisionService.approve() refuse de définir kyc_profiles.current_level au-delà de L2 jusqu'à l'approbation d'une intégration biométrique de niveau production. Le plafond est appliqué par IdentityAssuranceLevel.capAtFreezeLevel(). Toute session demandant L3 ou L4 atteint au maximum L2 et est orientée vers une révision manuelle.
Source de vérité
| Donnée | Stockage faisant autorité | Ne jamais utiliser |
|---|---|---|
| Niveau d'assurance | kyc_profiles.current_level | Non users.assurance_level |
| Clé d'identité source | users.external_id + users.source_instance_id | Non une colonne nullable scim_external_id |
| Session de complétion | Table DB identity_completion_session (hash HMAC-SHA256) | Non un attribut booléen kycRequired sur WebSession |
| Déduplication de documents | document_fingerprint.fingerprint (HMAC-SHA256 des champs normalisés) | Non SHA-256 du fichier (vulnérable au recadrage) |
Aperçu du flux de vérification
Un flux KYC commence lorsqu'un utilisateur authentifié ne satisfait pas le niveau d'assurance minimum requis par le fournisseur de services (SP). Hawiyati émet un jeton de complétion et redirige l'utilisateur vers le portail KYC.
Après authentification réussie, KycGateService.effectiveLevelFor(username) compare le niveau actuel au minimum requis par le SP. Si insuffisant, un jeton de complétion (TTL 15 min, usage unique) est émis.
L'utilisateur télécharge les faces recto et/ou verso de son document d'identité. Le serveur calcule l'empreinte HMAC-SHA256 et vérifie les doublons.
Le moteur OCR extrait les champs textuels. Si une zone de lecture machine (MRZ) est présente, les champs MRZ sont validés croisés avec les champs visuels.
Le moteur de décision calcule un score de confiance. Un score élevé déclenche une approbation automatique ; un score faible ou une alerte de doublon bascule en révision manuelle.
Un agent de vérification examine le dossier et approuve ou rejette. L'approbation met à jour kyc_profiles.current_level et invalide le jeton de complétion.
KYC de base — L1 (Auto-déclaré)
L'utilisateur fournit des informations personnelles de base : nom, prénom, date de naissance et adresse. Aucune pièce justificative n'est requise. Hawiyati vérifie la cohérence interne des données.
Nom, prénom, date de naissance, adresse de résidence.
Vérification que la date de naissance est plausible, que l'adresse est complète.
kyc_profiles.current_level passe à L1. Événement d'audit KYC_LEVEL_UPDATED émis.
KYC standard — L2 (Vérification documentaire)
L'utilisateur soumet un document d'identité délivré par l'État. Le système extrait les données par OCR, valide la zone MRZ le cas échéant, et calcule une empreinte de déduplication.
CIN algérienne (recto + verso), passeport algérien ou étranger (page photo), permis de conduire algérien (recto + verso).
Maximum 10 Mo par face. Formats acceptés : JPEG, PNG, PDF. La face verso est obligatoire pour les documents à deux faces.
Les champs OCR sont croisés avec les données MRZ (TD1 pour la CIN, TD3 pour les passeports). Les incohérences abaissent le score de confiance.
HMAC-SHA256 de (pays|type|numéro) normalisés. Un doublon avec un autre utilisateur déclenche une révision manuelle — il ne constitue pas un rejet automatique.
Score élevé → approbation automatique → L2. Score faible → MANUAL_REVIEW_REQUIRED → décision d'un agent.
Niveaux L3/L4 — Gelés
Les niveaux L3 (vérification biométrique) et L4 (supervision en personne) sont définis dans le système mais ne sont pas encore en production. Toute demande d'élévation vers L3 ou L4 est plafonnée à L2 par IdentityAssuranceLevel.capAtFreezeLevel().
- Une session KYC demandant L3 obtient au maximum L2.
- L'agent déclarant L4 est redirigé vers la révision manuelle au maximum L2.
- Aucune exception n'est levée — le gel est silencieux et traçable via l'événement d'audit.
États de session KYC
Chaque tentative de vérification crée une KycVerificationSession indépendante. Les transitions illégales sont bloquées par la machine d'état.
| É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 uniquement) |
| MANUAL_REVIEW_REQUIRED | Score de confiance 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 ; l'utilisateur peut démarrer une nouvelle session | — (terminal, nouvelle session autorisée) |
| PROCESSING_FAILED | Erreur système OCR ; l'utilisateur peut réessayer | → PENDING (nouvelle tentative) |
États du profil utilisateur (visibles par l'utilisateur)
| État | Signification |
|---|---|
| NOT_STARTED | Aucune vérification initiée |
| IN_PROGRESS | Session active en cours de traitement |
| DOCUMENT_SUBMITTED | Document soumis, en attente de traitement |
| UNDER_REVIEW | En révision manuelle par un agent |
| APPROVED | Identité vérifiée au niveau d'assurance cible |
| REJECTED | Vérification échouée — nouvelle soumission possible |
| EXPIRED | Session expirée sans soumission — nouvelle session requise |
| REVERIFICATION_REQUIRED | Un administrateur a demandé une nouvelle vérification |
Documents pris en charge (production)
Conformes à la norme ICAO 9303. Seuls les documents ci-dessous sont pris en charge en production. Les autres types de documents retournent une erreur de validation.
| Document | Pays | Faces à capturer | MRZ | Taille max |
|---|---|---|---|---|
| CIN algérienne | DZA | Recto + Verso (obligatoire) | TD1 (3 lignes) | 10 Mo par face |
| Passeport algérien | DZA | Page photo/données uniquement | TD3 (2 lignes) | 10 Mo |
| Passeport étranger | Tout pays | Page photo/données uniquement | TD3 (2 lignes) | 10 Mo |
| Permis de conduire algérien | DZA | Recto + Verso (obligatoire) | Aucun | 10 Mo par face |
lab/ocr-mrz-test) n'est pas encore promu dans hawiyati-kyc. Ces fonctionnalités ne sont pas documentées comme supportées en production tant que la promotion n'est pas confirmée.
Validation OCR et MRZ
Le moteur OCR extrait les données textuelles des images de documents. Pour les documents munis d'une zone MRZ (Machine Readable Zone), les champs extraits par OCR sont croisés avec les champs MRZ décodés.
Formats MRZ pris en charge
| Format | Lignes | Largeur | Documents |
|---|---|---|---|
| TD1 | 3 | 30 caractères | CIN algérienne |
| TD3 | 2 | 44 caractères | Passeports |
Contrôles de validation
- Checksum MRZ (algorithme de pondération 7-3-1)
- Cohérence date de naissance OCR ↔ MRZ (tolérance ±1 jour pour variations OCR)
- Cohérence numéro de document OCR ↔ MRZ
- Date d'expiration : document non expiré au moment de la soumission
- Code pays ISO 3166-1 alpha-3 valide dans la MRZ
Empreinte du document (HMAC-SHA256)
Lors de la capture d'un document, Hawiyati calcule une empreinte HMAC-SHA256 de l'identité normalisée du document — pays, type de document et numéro. Cette empreinte est stockée dans document_fingerprint (schéma : hawiyati_identity).
Une correspondance de doublon est un signal de risque qui oriente la session vers la révision manuelle. Ce n'est pas un rejet automatique, car des scénarios légitimes existent (réutilisation du document après changement de nom).
Algorithme de normalisation
String normalized = (country.toUpperCase().trim()
+ "|" + docType.toUpperCase().trim()
+ "|" + docNumber.trim().toUpperCase())
.replaceAll("\\s+", "");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(hmacKey, "HmacSHA256"));
String fingerprint = HexFormat.of().formatHex(
mac.doFinal(normalized.getBytes(StandardCharsets.UTF_8)));
Comportement de détection de doublon
| Scénario | Action |
|---|---|
| Empreinte correspondant à un utilisateur différent | Positionner duplicateDocumentRisk=true, passer à MANUAL_REVIEW_REQUIRED. Ne pas rejeter automatiquement. |
| Empreinte correspondant au même utilisateur | Autoriser — même utilisateur qui réessaie ou met à jour sa soumission. |
| Aucune empreinte existante | Enregistrer la nouvelle empreinte. Continuer la validation automatique. |
Gestion des clés
La clé HMAC est injectée depuis la configuration (hawiyati.kyc.document-fingerprint-key, clé 256 bits encodée en base64). La colonne key_version dans document_fingerprint permet la rotation des clés.
Détection de présence et selfie (L3 — Gelé)
Lorsque cette fonctionnalité sera disponible, le flux L3 ajoutera :
- Capture d'un selfie vidéo court (défi de mouvement)
- Détection de présence anti-spoofing (détection d'attaque par présentation)
- Correspondance faciale entre le selfie et la photo du document ou de la puce
Porte de révision humaine
Les sessions en état MANUAL_REVIEW_REQUIRED sont placées dans la file d'attente de révision de la console d'administration. Un agent habilité examine les preuves et approuve ou rejette.
Déclencheurs de révision manuelle
- Score de confiance OCR inférieur au seuil d'approbation automatique
- Alerte de doublon de document (empreinte correspondant à un autre utilisateur)
- Niveau d'assurance demandé ≥ L3 (plafonnement au gel)
- Incohérence entre les données OCR et MRZ dépassant la tolérance
- Document expiré ou pays non pris en charge
KycDecisionService.approve() applique le plafond de gel. Un agent ne peut pas accorder L3 ou L4 tant que l'intégration biométrique de production n'est pas approuvée.
Logique d'approbation
Lorsqu'un agent ou le système automatique approuve une session :
IdentityAssuranceLevel.capAtFreezeLevel(requested) — les demandes L3/L4 deviennent L2.
Écrire dans kyc_profiles.current_level — jamais dans la table users. Uniquement une montée en niveau, jamais une rétrogradation via ce chemin.
KYC_APPROVED avec le niveau atteint, l'identifiant de l'agent et l'identifiant de session.
Tout jeton de complétion ouvert pour cet utilisateur est invalidé. La prochaine connexion se passe sans porte KYC si le niveau effectif ≥ minimum SP.
Opérations d'administration KYC
Les administrateurs peuvent effectuer des opérations de cycle de vie sur les profils KYC via les points de terminaison REST de hawiyati-admin.
| Point de terminaison | Rôle requis | Action |
|---|---|---|
POST /api/v1/users/{id}/kyc/invalidate |
ROLE_SUPER_ADMIN | Rétrograder kyc_profiles.current_level au niveau cible. Refusé si cible > actuel. Événement KYC_INVALIDATED émis. |
POST /api/v1/users/{id}/kyc/request-reverification |
ROLE_ADMIN | Marquer le profil avec reverificationRequired=true et code de raison. La prochaine connexion déclenche la porte KYC. Événement KYC_REVERIFICATION_REQUESTED émis. |
Notifications
Les notifications KYC sont écrites dans la table notification_outbox dans la même transaction que l'action déclenchante. Un service de distribution en arrière-plan les envoie avec relance exponentielle.
| Événement | Modèle de notification | Destinataire |
|---|---|---|
| Session KYC créée | kyc-session-started-v1 | Utilisateur |
| Session approuvée | kyc-approved-v1 | Utilisateur |
| Session rejetée | kyc-rejected-v1 | Utilisateur |
| Revérification demandée | kyc-reverification-required-v1 | Utilisateur |
Conservation et suppression des données
| Donnée | Conservation | Mécanisme de suppression |
|---|---|---|
| Images de documents téléchargées | 90 jours après la décision finale | Tâche planifiée de suppression |
| Résultats OCR (champs textuels) | Durée de vie du profil utilisateur | Suppression en cascade lors de la suppression du compte |
| Empreintes de documents | Durée de vie du profil utilisateur | Suppression en cascade |
| Événements d'audit KYC | 7 ans (exigence réglementaire) | Archivage uniquement — pas de suppression |
| Jetons de complétion | 15 minutes (TTL) | Expiration automatique + nettoyage planifié |
Alignement NIST SP 800-63A
| Niveau Hawiyati | IAL NIST | Correspondance |
|---|---|---|
| L0 | IAL1 | Auto-affirmé — aucune preuve d'identité |
| L1 | IAL1 | Attributs auto-déclarés, cohérence vérifiée |
| L2 | IAL2 | Preuve documentaire à distance — pièce d'identité émise par l'État |
| L3 | IAL2+ | Preuve documentaire + biométrie (gelé) |
| L4 | IAL3 | Supervision en personne par un agent habilité (gelé) |
Responsabilités du client
Hawiyati fournit la plateforme de vérification KYC. Le client (l'organisation déployant Hawiyati) est responsable de :
- Définir les politiques d'assurance minimale par SP en fonction de ses obligations réglementaires
- Former les agents de révision manuelle aux procédures de vérification documentaire
- Configurer les durées de conservation des données conformément aux exigences locales
- Obtenir le consentement éclairé des utilisateurs avant la collecte de données biométriques
- Notifier les autorités réglementaires compétentes en cas de violation de données affectant les dossiers KYC
- Archiver les journaux d'audit KYC conformément aux exigences de durée de conservation applicables