H· Hawiyati Documentation

User Registration & Identity Lifecycle

Hawiyati IAM Platform — Component Architecture HAWIYATI IAM PLATFORM — COMPONENT ARCHITECTURE Spring Boot 3.5 · Java 25 · gRPC EXTERNAL ACTORS ENTRY LAYER & FEDERATION HTTPS · SAML 2.0 · OIDC · WebAuthn PLATFORM SERVICES HTTPS internal · gRPC DATA & INFRASTRUCTURE JDBC · Redis pub/sub · gRPC User Browser Browser · Mobile App Administrator Admin Console SAML Service Provider SAML 2.0 OIDC Relying Party OIDC · OAuth 2.0 SCIM Client HR System · Directory hawiyati-gateway Spring Cloud Gateway · :8080 Routing · TLS termination hawiyati-http-server IdP Login · MFA · FIDO2 · :8085 SAML ACS · OIDC callback · Account BFF hawiyati-federation SAML 2.0 · OIDC · :8087 Assertion & token issuance · Policy hawiyati-admin Admin Console · :8095 · WebFlux hawiyati-account Account Portal · :8096 · BFF/OIDC hawiyati-scim SCIM 2.0 API · :8098 hawiyati-session · :9004 hawiyati-cache · :9003 hawiyati-infra · :9002 PostgreSQL hawiyati · hawiyati_identity Redis / Valkey Sessions · Cache · Rate limits Audit & Logs CEF Syslog · OTel · SIEM PKI & Keystore SAML · OIDC · mkcert TLS External Actor External System Entry / Federation Platform Service gRPC Service Data Store

The sections below cover user registration, identity lifecycle management, and assurance levels. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.

Purpose & Scope

Scope This document describes how users are created, verified, and activated in Hawiyati. It covers three deployment scenarios, the Assurance Level framework (L0–L4) for standardising identity trust, account state model, and implementation actions for all identified gaps.

Hawiyati supports multiple registration and onboarding routes: self-service, invitation-based, SCIM provisioning, LDAP/AD, and admin-created. The choice of route determines which account states are relevant and which assurance levels apply.

Governing Constraint OCR/MRZ lab fixes in lab/ocr-mrz-test must NOT be synced to hawiyati-kyc until explicitly confirmed. All other implementation actions are independent of this constraint.
See also For the complete technical deep-dive including KYC state machine, document fingerprinting, completion tokens, and Flyway migration details, see the Registration, KYC & Migration Guide.

Assurance Levels (L0–L4)

Hawiyati adopts a five-level identity assurance model aligned with NIST SP 800-63A-4 (Identity Assurance Level) and FATF guidance. The assurance level label appears in code, documentation, admin console UI, and API responses — replacing informal language like "verified" or "basic KYC".

Source of truth The authoritative assurance level is stored exclusively in kyc_profiles.current_level. It is never derived from account status flags (active, pendingApproval). Treat the assuranceLevel field on the account entity as a cached copy synced from the KYC profile.
LevelNameWhat it meansHawiyati workflowTypical use
L0 None No account exists. Unrecognised visitor or pre-registration state. Anonymous / pre-registration Anonymous access only
L1 Basic Verified channel (email or phone OTP) plus enrolled authenticator (password or passkey). Identity claim not verified against an authoritative source. Completed self-registration flow Consumer apps, low-risk services
L2 Standard L1 plus validated identity document (OCR + MRZ extraction) with consistency checks and reviewer approval. KYC_APPROVED after document review Financial services, regulated consumer apps
L3 Strong L2 plus liveness detection and biometric face match against the document photo. KYC_APPROVED with liveness + face match confirmed High-value transactions, AML compliance
L4 High Assurance Authoritative or supervised proofing: in-person, notarised, or trusted third party. L3 plus human review queue. Future — manual override by privileged admin Government, e-signature, critical infrastructure

Assurance Level in code

A field assuranceLevel (enum L0..L4) is stored on the user account entity and returned in API responses. Authentication policies reference minimumAssuranceLevel instead of the legacy binary kycRequired flag. Existing kycRequired = true policies migrate to minimumAssuranceLevel = L2.

KYC Assurance Level Progression
L0
None
→
L1
Basic
→
L2
Standard
→
L3
Strong
→
L4
High Assurance

Assurance levels increase with each identity verification step. Stored in kyc_profiles.current_level — never derived from account flags.

Account States

The account status is determined by two boolean flags in the accounts table: active and pendingApproval. These flags, combined with the assurance level, define the full lifecycle state of an account.

Important: ACTIVE_LIMITED is computed, not stored ACTIVE_LIMITED is a computed state — there is no database column for it. It is derived at runtime when an account is active=true but has not yet met the minimumAssuranceLevel required by its authentication policy. Never write code that stores or persists this state.
L0 — No account PENDING_ACTIVATION PENDING_APPROVAL MIGRATED_UNCLAIMED ✦ proposed ACTIVE ACTIVE_LIMITED (computed) SUSPENDED LOCKED INACTIVE ARCHIVED DELETED
StateactivependingApprovalCan Auth?Access ScopeHow Reached
PENDING_ACTIVATION false false No None New self-registration, email not yet verified
PENDING_APPROVAL false true No None Email verified, awaiting admin approval (adminApprovalRequired = true)
MIGRATED_UNCLAIMED (proposed) false true No (no credential) None until claimed SCIM bulk import or governed import job — real person has not yet claimed account
ACTIVE true false Yes — full Full (subject to assurance gate) Approved from PENDING; open registration auto-approved; SCIM provisioning; admin create
ACTIVE_LIMITED (computed) true false Yes — limited /account/kyc/**, /account/status only ACTIVE but assurance level below policy minimumAssuranceLevel. Cannot obtain SP tokens.
SUSPENDED false false No None Admin action — temporary lock
LOCKED false false No None Too many failed authentication attempts (brute-force protection)
INACTIVE false false No None Long-term inactivity (scheduled job per retention policy)
ARCHIVED false false No None Admin archived — data preserved for compliance
PENDING_DELETION varies varies No None Deletion requested; retention grace period in progress
DELETED — — No None Soft-deleted; audit trail preserved per data-retention policy

Account State Machine

Account Status State Machine
PENDING_ACTIVATION
PENDING_APPROVAL
MIGRATED_UNCLAIMED
→
ACTIVE
ACTIVE_LIMITED (computed)
⇄suspend/re-enable
SUSPENDED
→
DELETED

State transitions are recorded as audit events. Only administrators can initiate most transitions. ACTIVE_LIMITED is computed — never stored.

MIGRATED_UNCLAIMED — Three-tier credential migration

MIGRATED_UNCLAIMED differs from PENDING_APPROVAL. PENDING_APPROVAL means the person self-registered and awaits admin approval. MIGRATED_UNCLAIMED means an admin created the record from a migration data file — the real person has not yet authenticated against Hawiyati.

TierWhen to useUser experienceWhat the org provides
Tier 1 — Hash migration Org can export password hashes (bcrypt, PBKDF2, Argon2, SHA-256+salt) User logs in with existing username + password. Fully transparent. Hashed passwords in import manifest
Tier 2 — JIT proxy migration Hash format unknown; org can expose a legacy auth endpoint (REST or LDAP) User logs in with existing credentials. Hawiyati proxies to legacy system on first login. Transparent after that. Legacy auth endpoint URL + credential
Tier 3 — Claim link No credential migration possible (offline system, proprietary HSM, policy) User receives a signed claim link by email/SMS; creates new password. Email/phone addresses only

ACTIVE_LIMITED — KYC deadlock fix

Without ACTIVE_LIMITED, a user with minimumAssuranceLevel = L2 is blocked at login but has no authenticated session to reach the KYC submission page — a deadlock. ACTIVE_LIMITED solves this: LoginController issues a limited session that grants access only to account-portal completion endpoints but cannot be used to obtain SP tokens (SAML assertions, OIDC id_token).

Policy Modes

Registration and KYC behaviour is governed by per-tenant policy flags. The three core registration modes are:

ModeConfigurationBehaviourRecommended for
Open openRegistration = true
adminApprovalRequired = false
Anyone can self-register at /idp/register. Accounts are activated automatically upon email verification. Consumer apps, public services, low-risk platforms
Approval Required openRegistration = true
adminApprovalRequired = true
Self-registration is permitted but accounts enter PENDING_APPROVAL and require admin review before becoming ACTIVE. Invitation tokens bypass this gate. Regulated services, government pilots, beta programmes
Invite Only openRegistration = false Public /idp/register is disabled. Only invitation tokens, SCIM provisioning, or admin-created accounts can create users. Enterprise deployments, workforce IAM, closed systems
Policy flagEffect when set
openRegistrationPublic /idp/register accepts new users
adminApprovalRequiredRegistered accounts start PENDING_APPROVAL; bypassed by invitation tokens
botProtectionEnabledCAPTCHA / challenge on identity step
tosVersionRequiredUser must accept Terms of Service; version tracked per user
minimumAssuranceLevelLogin blocked (ACTIVE_LIMITED) until user reaches this assurance level. Replaces binary kycRequired. L2 = document review, L3 = liveness + face match.

Use Cases

Three primary deployment scenarios determine how Hawiyati is configured and which onboarding paths are used.

Use Case A — Greenfield Deployment

Scenario No prior users. Organisation deploys Hawiyati for the first time and must decide how users enter the system.

Option A1 — Self-registration

Enable openRegistration = true. Users complete the multi-step form at /idp/register and are immediately ACTIVE (or PENDING_APPROVAL if approval mode is on). Recommended for consumer-facing platforms.

Option A2 — Invitation-based onboarding

Set openRegistration = false. Admin generates invitation tokens via POST /api/admin/invitations and sends users a link /idp/register?invite=<token>. Tokens bypass both openRegistration and adminApprovalRequired. Recommended for enterprise rollout and government pilots.

Option A3 — Admin or SCIM creates accounts

Leave openRegistration = false. Admin creates accounts individually via console, or provisions via SCIM 2.0 (hawiyati-scim port 8098). Users receive credentials through a welcome email activation link.

Greenfield Deployment — Onboarding Flow
1
Configure policy mode
Choose Open, Approval Required, or Invite Only. Set minimumAssuranceLevel for the target assurance requirement.
2
User registers or is invited
Via /idp/register (open/approval mode) or via a signed invitation link sent by the admin.
3
OTP verification + credential enrollment
Email or SMS OTP proves channel possession. User sets password or enrolls a passkey.
4
Admin approval (if required)
Account enters PENDING_APPROVAL. Admin reviews and approves via console or API.
5
ACTIVE — full access granted
Account is live. If assurance gate is enabled, user may be ACTIVE_LIMITED until KYC is complete.

Greenfield deployment: configure → register/invite → verify → (approve) → activate.

Use Case B — Organisation Migration

Scenario An organisation brings an existing user base into Hawiyati. Users have accounts in another system — LDAP, a legacy IdP, a SaaS app, or a custom database.
Organisation Migration — Recommended Path
1
Prepare governed import job
Use the governed bulk import endpoint. Provide a structured manifest (CSV or JSON). System validates, deduplicates, and creates accounts with status MIGRATED_UNCLAIMED.
2
Claim links sent automatically
Outbox notification system sends signed claim links to each imported email/phone. Delivery status tracked; admin dashboard shows claim rate.
3
Users claim accounts
Users follow claim link, verify OTP, enroll credentials. Account transitions: MIGRATED_UNCLAIMED → ACTIVE_LIMITED → ACTIVE.
4
KYC grace period (recommended)
Set minimumAssuranceLevel = L0 initially. Schedule a future date for L2 enforcement. Send automated reminders at D-30 and D-7. On the scheduled date, toggle the level.
5
Monitor and clear unclaimed accounts
After the claim deadline, admin reviews unclaimed accounts. Accounts not claimed within the configured window are suspended or scheduled for deactivation per data-retention policy.

Organisation migration using MIGRATED_UNCLAIMED state and a claim flow with a KYC grace period.

Current state gap

SCIM provisioning currently creates accounts as ACTIVE with no password and marks email as verified without user proof of possession. There is no claim flow, no bulk welcome email, and no grace-period mechanism for KYC. These are addressed in implementation actions P1.

Use Case C — SP-Initiated Login (new user)

Scenario A SAML or OIDC service provider redirects an unauthenticated user to Hawiyati. The user may or may not have an account.

Scenario C1 — User has existing account

Normal authentication. On success, IdP resumes the SP-initiated flow and issues a SAML response or OIDC token. User lands in the SP application.

Scenario C2 — No account; registration is open

SP context is preserved in the session. After registration + login, IdP resumes the SP flow automatically. User lands in SP without re-initiating from the SP side.

Scenario C3 — No account; registration is closed

User receives an invitation token. After account creation, user must re-initiate the SP flow. The SP transaction context has expired by then.

Hybrid continuation design (implemented) The SAML/OIDC protocol context stays in WebSession/Redis for 10–15 minutes (interactive window). When registration hits an approval or KYC boundary, a sanitised onboarding_continuation record is persisted in the DB (7-day TTL). After approval or activation, that record is consumed atomically and the browser is sent to the SP's registered initiation endpoint — the SP issues a fresh SAML AuthnRequest or OIDC request. Stale protocol messages are never replayed.

Target Registration Flow

Decision tree for selecting the primary onboarding route
Select one authoritative onboarding route for each population before configuring registration.

The target self-registration flow incorporates assurance levels, the ACTIVE_LIMITED state, and the username enumeration fix. Invitation and admin-create paths share phases 2–5.

Figure 7-1 — Target Registration Flow
1
Phase 1 — Identity (name · email · phone)
User submits identity details. If username is already taken, a generic "check your details" error is returned — never "username taken" — to prevent account enumeration (OWASP A07 fix). Bot protection and rate limiting applied if configured.
2
Phase 2 — OTP Verification
Email or SMS OTP proves channel possession. The OTP is time-limited and single-use. After verification, the channel is marked as verified.
3
Phase 3 — Terms of Service (if required)
If tosVersionRequired is set, user must accept the current Terms of Service. IP address, user-agent, timestamp, and ToS version are recorded for compliance.
4
Phase 4 — Set Password / Enroll Passkey
Password policy is enforced. Passkey enrollment is offered. Consent metadata is recorded.
5
Gate — Admin approval check
If adminApprovalRequired = true, account enters PENDING_APPROVAL. Admin reviews and approves via console. If open registration, skip to next step.
6
Gate — Assurance level check
If minimumAssuranceLevel is satisfied (usually L1 after registration), account becomes ACTIVE. If L2+ is required, account becomes ACTIVE_LIMITED and user is redirected to the KYC flow.
7
ACTIVE — Full access granted
SP-initiated flows are resumed via the onboarding_continuation record if applicable. User lands in their target application.

Figure 7-1. Target registration flow incorporating Assurance Level gate, ACTIVE_LIMITED state, and username enumeration fix.

KYC / Identity Verification Flow

End-to-end KYC verification and decision flow
The configured assurance workflow controls document, selfie, liveness, risk, and manual-review gates.

KYC verification upgrades a user's assurance level from L1 to L2 (document review) or L3 (liveness + face match). The source of truth for the current level is always kyc_profiles.current_level.

Figure 8-1 — KYC End-to-End Flow
1
User opens Identity Verification
Available from the account portal (/account/kyc). User selects document type: CIN, Passport, Driving Licence, or Foreign Passport.
2
Upload document images
Front + back (two-sided). File type and size are validated server-side (magic bytes, not just Content-Type). Accepted: image/jpeg, image/png, image/webp, max 10 MB per image.
3
hawiyati-kyc processes the submission
Async processing: OCR extraction, MRZ parse + checksum, confidence score calculation, duplicate document hash check. Upload returns 202 Accepted with processingId. Account portal polls for status.
4
Auto-pass threshold check
If OCR confidence is below threshold, submission is auto-rejected and user must re-submit. If above threshold, submission enters the manual review queue.
5
Manual review queue
Reviewer accesses the admin console KYC queue (/kyc/queue). They review OCR fields, MRZ data, conflicts, and raw text. For L3: liveness and face match results are also shown.
6
Reviewer decision
Reviewer selects: Approve (sets assurance level L2 or L3 in kyc_profiles.current_level), Reject (with reason: EXPIRED_DOCUMENT, ILLEGIBLE_IMAGE, MRZ_MISMATCH, FACE_MISMATCH), or Request Re-verification.
7
KYC_APPROVED — Assurance Level set
Account transitions from ACTIVE_LIMITED to ACTIVE if assurance gate is satisfied. Outbox notification sent to user. If L4 human review applies, case enters the privileged admin queue.

Figure 8-1. Target KYC flow. L2 = document review approved. L3 (future) = liveness + face match confirmed.

Assurance Upgrade Sequence
L0
No account
→
L1
Registration complete
→
L2
Doc OCR/MRZ approved
→
L3
Liveness + face match
→
L4
Human / in-person

Each level requires all lower-level checks. Levels can expire — KYC expiry job fires at D-30 and D-7 warnings before expiry.

Migration Flow — MIGRATED_UNCLAIMED Path

Invitation and account claim flow for a migrated user
Migrated accounts remain unclaimed until a single-use invitation is verified and authenticators are bound.

When migrating an existing user base, accounts are created with the MIGRATED_UNCLAIMED state. Users claim their accounts via a signed link rather than re-registering.

Figure 5-1 — Organisation Migration Flow
1
Export from source system
Extract user records from LDAP, legacy IdP, SaaS app, or custom DB. Include at minimum: username, email/phone, and optionally password hashes.
2
Run governed import job
Upload CSV/JSON to POST /api/admin/import/users. System deduplicates, validates, and creates accounts with status MIGRATED_UNCLAIMED. Import report available on completion.
3
Claim links dispatched via outbox
Signed, single-use claim links (HMAC-SHA256, 48h TTL) sent to each imported email/phone. Admin dashboard shows claim rate per import batch.
4
User follows claim link
User follows link → OTP verification → credential enrollment (password or passkey). Account transitions: MIGRATED_UNCLAIMED → ACTIVE_LIMITED.
5
Assurance gate check
If minimumAssuranceLevel = L0/L1: account transitions directly to ACTIVE. If L2+ required: account stays ACTIVE_LIMITED and user is directed to KYC flow.
6
ACTIVE — Full access granted
User is fully migrated. Unclaimed accounts after the deadline are suspended or scheduled for deactivation per data-retention policy.

Figure 5-1. Target migration flow using MIGRATED_UNCLAIMED state and claim flow.

Tier 1 — Hash Migration (Transparent)

Tier 1 — Hash Migration Flow
1
Import creates accounts with imported hash
Accounts created with MIGRATED_UNCLAIMED + TIER_1 flag. Hash and algorithm tag stored (e.g. bcrypt:$2b$12$…). Hash encrypted at rest via EncryptionService.
2
User logs in with existing credentials
LoginController detects MIGRATED_UNCLAIMED + TIER_1 flag. Verifies supplied password against the imported hash using the tagged algorithm.
3
On success: re-hash and activate
Re-hash the verified plaintext with Hawiyati's current Argon2 scheme. Clear imported_credential_hash. Transition account → ACTIVE (or ACTIVE_LIMITED if KYC required). On N failures: escalate to Tier 3 claim link.

Tier 1 hash migration: transparent for users. Supported algorithms: bcrypt, PBKDF2, Argon2, SHA-256+salt.

Implementation Actions

Priority Tiers P0 Critical (security/correctness), P1 High (core workflow gaps), P2 Medium (operational quality), P3 Low (future hardening).
P0 — Critical Security, correctness, and KYC deadlock — must ship before production
ACT-P0-01 — ACTIVE_LIMITED session
P0-01
Fix KYC deadlock: user with minimumAssuranceLevel = L2 has no session to reach the KYC page. Issue an ACTIVE_LIMITED session scoped to completion endpoints only.
  • Add ACTIVE_LIMITED enum to AccountStatus in hawiyati-persistence
  • In LoginController: detect users needing KYC — issue limited session with scope COMPLETION_ONLY
  • Create CompletionOnlyAuthorizationFilter blocking SP-facing endpoints (/saml/**, /oidc/token)
  • Allow: /account/kyc/**, /account/status, /account/consent
  • Add minimumAssuranceLevel to AuthenticationPolicy entity; Flyway migration V54
Modules: hawiyati-persistence · hawiyati-http-server · hawiyati-session
ACT-P0-02 — Username enumeration fix
P0-02
Current username_taken error reveals account existence (OWASP A07). Return a generic "check your details" message for taken usernames.
  • In RegistrationController: return same generic error code whether username is taken or fails other validation
  • Remove username_taken error key from messages.properties
  • Add integration test: response for taken username must be identical to response for malformed email
Modules: hawiyati-http-server | RegistrationController.java · messages.properties
ACT-P0-03 — Document upload validation
P0-03
KYC upload accepts any MIME type and size. Validate by magic bytes, not Content-Type header.
  • In KycDocumentController: validate magic bytes — accept only image/jpeg, image/png, image/webp
  • Enforce max 10 MB per image; validate image can be decoded as raster
  • Return HTTP 422 with structured error on failure
  • Set spring.servlet.multipart.max-file-size and max-request-size
Modules: hawiyati-kyc | KycDocumentController.java · application.yml
ACT-P0-04 — Duplicate document hash check
P0-04
Prevent the same physical document being used to verify multiple accounts (identity fraud).
  • After MRZ parsing: compute SHA-256 of (documentType + documentNumber + dateOfBirth + nationality)
  • Store fingerprint in kyc_document.document_fingerprint; unique partial index on approved submissions
  • On duplicate: auto-reject with reason DUPLICATE_DOCUMENT and flag account for admin review
  • Expose duplicate alert in admin console KYC review queue
Modules: hawiyati-kyc · hawiyati-persistence | Flyway migration V55
ACT-P0-05 — SP transaction context storage
P0-05
Hybrid two-lifetime design: SAML/OIDC context in Redis (10–15 min); sanitised continuation intent persisted in DB (7-day TTL). Stale protocol messages never replayed.
  • Create onboarding_continuation table: id, account_id, sp_client_id, sp_initiation_endpoint, expires_at, consumed_at
  • At approval/KYC boundary: create continuation row; allow Redis entry to expire
  • On account activation: look up unconsumed continuation; atomically consume and redirect to SP
  • Scheduled cleanup for expired rows; admin can revoke
Modules: hawiyati-persistence · hawiyati-http-server | Flyway migration V57
ACT-P0-06 — Consent metadata persistence
P0-06
ToS acceptance must record IP address, user-agent, timestamp, and exact ToS version — required for Algerian Law 18-07 and GDPR-equivalent audit trails.
  • Add to user_consent table: tos_version, accepted_at, ip_address, user_agent
  • Capture HttpServletRequest.getRemoteAddr(), User-Agent, and server timestamp in Phase 3 handler
  • Expose consent audit via Admin API: GET /api/admin/users/{id}/consents
Modules: hawiyati-persistence · hawiyati-http-server · hawiyati-admin
P1 — High Core workflow gaps — needed for production-grade operations
ACT-P1-01 — MIGRATED_UNCLAIMED + claim flow
P1-01
Replace SCIM creating ACTIVE accounts without passwords with MIGRATED_UNCLAIMED state and a structured claim flow.
  • Add MIGRATED_UNCLAIMED to AccountStatus enum
  • Modify SCIM POST /scim/v2/Users: when no password provided, set MIGRATED_UNCLAIMED + emailVerified = false
  • Create AccountClaimService: signed single-use claim token (HMAC-SHA256, 48h TTL)
  • Create ClaimController at /idp/claim?token=: validate → OTP → credential enrollment → ACTIVE_LIMITED
Modules: hawiyati-http-server · hawiyati-persistence · hawiyati-scim | Flyway migration V56
ACT-P1-02 — Governed bulk import job
P1-02
Batch-safe, auditable import endpoint separate from the real-time SCIM API, with deduplication and import reporting.
  • Add POST /api/admin/import/users (multipart CSV or JSON) in hawiyati-admin
  • Async Spring Batch job: parse → validate → dedup → create MIGRATED_UNCLAIMED → write report
  • Each account attributed to import job ID; rollback = deactivate all accounts from that import
  • Admin console shows job progress and report download
Modules: hawiyati-admin · hawiyati-persistence | Spring Batch dependency
ACT-P1-04 — Outbox notification system
P1-04
Transactional outbox pattern: state changes commit first, notifications dispatched asynchronously — decoupling notifications from identity state transitions.
  • Create notification_outbox table: id, event_type, recipient, payload, status, created_at, sent_at, error
  • All state-transition code inserts outbox row in same transaction instead of calling notification service directly
  • Create OutboxDispatchJob: polls outbox, dispatches via SMTP/SMS gateway, marks sent/failed with retry count
  • Admin console: outbox monitoring page with retry button
Modules: hawiyati-persistence · hawiyati-http-server · hawiyati-admin
ACT-P1-05 — Assurance Level framework
P1-05
Adopt L0–L4 model across code, database, admin UI, and API. Replace informal "KYC approved" language.
  • Add assurance_level VARCHAR(4) to user_account; default L0, L1 after registration, L2 after KYC_APPROVED
  • Add minimum_assurance_level to authentication_policy; migrate from kyc_required
  • KYC approval: reviewer sets assurance level on approval
  • API: include assuranceLevel in user response and OIDC id_token claims
Modules: hawiyati-persistence · hawiyati-admin · hawiyati-openid-federation | Flyway migration V54
ACT-P1-07 — Tier 1 hash migration
P1-07
Transparent migration for organisations that can export password hashes. Users log in with existing credentials — no claim link required.
  • Add imported_credential_hash VARCHAR(512), imported_credential_algorithm VARCHAR(32), migration_tier SMALLINT; Flyway V58
  • Import: parse algorithm tag; set migration_tier = 1
  • LoginController: on Tier 1 flag, verify against imported hash; on success re-encode with Argon2, null out imported columns, activate account
  • On N failures: escalate to Tier 3 (generate claim token)
Modules: hawiyati-persistence · hawiyati-http-server | Flyway V58 · Algorithms: bcrypt, PBKDF2, Argon2, SHA-256+salt
ACT-P1-08 — Tier 2 JIT proxy migration
P1-08
Transparent migration when hashes cannot be exported. Hawiyati proxies credential check to the legacy REST or LDAP system on first login.
  • Add migration_proxy_config table: proxy_type (REST|LDAP), endpoint_url, tls_fingerprint, credential_encrypted; Flyway V59
  • Create MigrationProxyService for REST and LDAP; plaintext credential never logged or persisted
  • On proxy success: enroll Hawiyati credential (Argon2), clear migration_tier, activate account
  • All proxy calls audited (success/failure, no plaintext) in hawiyati-audit
Modules: hawiyati-persistence · hawiyati-http-server · hawiyati-infra | Flyway V59
P2 — Medium Operational quality and compliance — important but not blocking launch
ACT-P2-01 — Policy-driven assurance selection
P2-01
Extend authentication policies to use minimumAssuranceLevel so different applications can require different identity strength.
  • Admin console: replace "Require KYC" toggle with "Minimum Assurance Level" dropdown (L0–L4)
  • LoginController checks account's assuranceLevel against policy's minimumAssuranceLevel
  • Include acr_values in OIDC token (L0–L4 → standard ACR URIs); AuthnContextClassRef in SAML
Modules: hawiyati-admin · hawiyati-http-server · hawiyati-openid-federation · hawiyati-saml-federation
ACT-P2-02 — Async OCR processing
P2-02
Move OCR from synchronous (causes HTTP timeouts) to async with polling notification.
  • Upload endpoint returns 202 Accepted with processingId immediately
  • Background worker processes OCR; updates kyc_document.processing_status; notifies via outbox
  • Account portal polls GET /account/kyc/status for progress indicator
Modules: hawiyati-kyc · hawiyati-http-server
ACT-P2-03 — KYC grace period / cohort rollout
P2-03
Add a scheduled activation date so organisations give users a grace period before KYC becomes mandatory.
  • Add minimum_assurance_level_effective_date to authentication_policy
  • LoginController checks today ≥ effective date before enforcing; before that date, behaves as L0
  • Outbox sends reminders at D-30 and D-7 to all users below required level
Modules: hawiyati-persistence · hawiyati-http-server · hawiyati-admin
ACT-P2-04 — KYC retry and appeal flow
P2-04
Add structured rejection reasons and optional appeal pathway so users understand why KYC was rejected and how to fix it.
  • Reviewer selects structured rejection reasons: EXPIRED_DOCUMENT, ILLEGIBLE_IMAGE, MRZ_MISMATCH, FACE_MISMATCH
  • Reasons surfaced to user in account portal with localised guidance text
  • After N rejections: account flagged MANUAL_REVIEW_REQUIRED; further submission requires admin intervention
Modules: hawiyati-kyc · hawiyati-admin · hawiyati-http-server
ACT-P2-05 — KYC expiry warning
P2-05
Notify users before KYC expires so they can re-verify proactively rather than discovering it at login.
  • Extend KycExpiryJob: insert outbox row with KYC_EXPIRY_WARNING at D-30 and D-7
  • On expiry: transition status and insert KYC_EXPIRED notification
Modules: hawiyati-kyc · hawiyati-persistence (outbox)
P3 — Low Future hardening — important for scale and advanced compliance
ACT-P3-01 — First-admin secure bootstrap
P3-01
Provide a secure, auditable bootstrap procedure for the first admin account in production deployments.
  • Add one-time /setup endpoint — available only when zero admin accounts exist
  • Endpoint issues time-limited setup token printed to application log on first start
  • Admin provides log token + credentials via setup form; endpoint disables itself after first use
Modules: hawiyati-admin · hawiyati-http-server
ACT-P3-02 — Identity correlation
P3-02
Detect when the same real person holds multiple Hawiyati accounts — required for fraud detection at scale.
  • After KYC_APPROVED: compute person_fingerprint from MRZ document number + DOB + nationality
  • Store person_id (UUID) on account on first L2 approval
  • If same fingerprint on different account: link via identity_link table and alert admin
Modules: hawiyati-kyc · hawiyati-persistence | New tables: person, identity_link
ACT-P3-03 — SCIM deprovisioning SLA
P3-03
Track deprovisioning latency for enterprise SCIM compliance and insider risk controls.
  • Record deprovisioning_requested_at and deprovisioning_completed_at on user_account
  • Emit structured audit event on each SCIM DELETE with both timestamps
  • Admin console: deprovisioning SLA report
Modules: hawiyati-scim · hawiyati-persistence · hawiyati-admin
ACT-P3-04 — SCIM Bulk endpoint
P3-04
Implement SCIM 2.0 Bulk endpoint to avoid sequential individual requests during large migrations.
  • Implement POST /scim/v2/Bulk per RFC 7644 §3.7
  • Support failOnErrors and partial-success semantics
  • Each bulk operation delegates to the same service layer as individual operations
Modules: hawiyati-scim

Decision Guide — Choosing a Registration Path

Use the table below to select the correct combination of registration mode, assurance level, and entry path for your deployment scenario.

ScenarioOpen reg?Approval?AssuranceEntry path
Consumer app, self-serveYesNoL1 (L2 optional later)A1 — open registration
Enterprise pilot, known usersNo—L1–L2A2 — invitation tokens
Regulated service requiring strong identityNo or YesYesL2+A1 or A2 + KYC gate
Organisation migration, existing directoryNo—L2 with grace periodB — MIGRATED_UNCLAIMED + claim flow
SP-initiated, account not yet createdYesNoL1C2 — open reg from SP redirect
SP-initiated, closed deploymentNo—L1+A2 invitation first, then SP
First deployment, zero usersNo——A3 — admin create + welcome email

Which assurance level do I need?

Risk levelUser typeCompliance requirementRecommended level
LowAnonymous / general publicNoneL0 / L1
MediumRegistered consumerBasic account verificationL1
HighFinancial service customerKYC / AML / FATFL2
Very highHigh-value transactionsStrong biometric verificationL3
CriticalGovernment / e-signatureIn-person or notarisedL4
Governing constraint

OCR/MRZ fixes in lab/ocr-mrz-test must NOT be synced to hawiyati-kyc until explicitly confirmed. All other implementation actions above are independent of this constraint and may proceed.

HawiyatiDocumentation · v2026 · Spring Boot 3.5