Compliance & Audit
Hawiyati is designed against the NIST SP 800-63 Digital Identity Guidelines suite. The three volumes — 800-63A (Identity Proofing), 800-63B (Authentication), and 800-63C (Federation) — map to Hawiyati's KYC workflows, authentication policies, and SAML/OIDC federation respectively.
Hawiyati is designed against the NIST SP 800-63 Digital Identity Guidelines suite. The three volumes — 800-63A (Identity Proofing), 800-63B (Authentication), and 800-63C (Federation) — map to Hawiyati's KYC workflows, authentication policies, and SAML/OIDC federation respectively.
The sections below cover compliance requirements, audit events, and regulatory alignment. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.
NIST SP 800-63 Alignment
Hawiyati is designed against the NIST SP 800-63 Digital Identity Guidelines suite. The three volumes — 800-63A (Identity Proofing), 800-63B (Authentication), and 800-63C (Federation) — map to Hawiyati's KYC workflows, authentication policies, and SAML/OIDC federation respectively.
800-63A — Identity Proofing (IAL)
Identity assurance level governs how confidently a claimed identity has been verified during enrolment or registration.
| NIST IAL | Proofing Requirement | Hawiyati Mapping | Status |
|---|---|---|---|
| IAL1 | Self-asserted attributes; no verification required | L0 / L1 — email or phone collected; L1 requires verification | Available |
| IAL2 | Remote identity proofing; document verification | L2 — document capture, OCR/MRZ validation, expiry check | Available |
| IAL3 | In-person or supervised remote proofing; biometric binding | L3 / L4 — liveness + face match (L3), human review gate (L4) | Pending biometric approval |
800-63B — Authentication (AAL)
Authenticator assurance level governs the strength of the authentication mechanism required at login.
| NIST AAL | Authentication Requirement | Hawiyati Mapping |
|---|---|---|
| AAL1 | Single-factor authentication | Password only (Argon2id); policy action ALLOW with no MFA requirement |
| AAL2 | Multi-factor authentication | Policy action MFA_REQUIRED; TOTP (RFC 6238), Email OTP, SMS OTP, or FIDO2 |
| AAL3 | Hardware-bound authenticator | Policy action MFA_STRONG; FIDO2 hardware security key (YubiKey, etc.) |
800-63C — Federation (FAL)
Federation assurance level governs the strength of assertions passed between the IdP and SP.
| NIST FAL | Assertion Requirement | Hawiyati Mapping |
|---|---|---|
| FAL1 | Bearer assertion; signed by IdP | SAML 2.0 signed assertion (RS256); OIDC ID token (RS256) |
| FAL2 | Bearer assertion; signed and encrypted | SAML assertion encryption supported; OIDC JWE (configuration-dependent) |
| FAL3 | Holder-of-key assertion; bound to authenticator | Not currently implemented; Roadmap |
kyc_profiles.current_level. The column users.assurance_level is a legacy/denormalized field — do NOT use it as the source of truth for access control decisions. Any code or SP attribute mapping must read from kyc_profiles.
Assurance Level Reference
Hawiyati uses five assurance levels (L0–L4) aligned to NIST SP 800-63A-4. Each level represents a distinct verification tier with different KYC workflow requirements and SP policy applicability.
| Level | Name | Verification Requirements | Use Cases | Status |
|---|---|---|---|---|
| L0 | Unverified | Email or phone number collected but not verified. Self-asserted identity only. | Low-risk services, trial access, pre-registration holding state | Available |
| L1 | Basic | Email AND phone number verified (OTP confirmation for both). Identity attributes self-asserted. | Standard digital services, authenticated portals, non-regulated workflows | Available |
| L2 | Standard | L1 plus document capture (passport / national ID / driver's licence), OCR/MRZ validation, document expiry check. Document fingerprint (HMAC-SHA256 of country|docType|docNumber) stored for duplicate detection. |
Regulated services, financial account opening, government digital services, healthcare access | Available |
| L3 | Strong | L2 plus selfie capture, passive or active liveness detection, and face match against document photo. Face match score stored in kyc_sessions.face_match_score. Raw images not persisted (vendor-dependent). |
High-value transactions, privileged account onboarding, sensitive data access | Frozen — pending biometric approval |
| L4 | High Assurance | L3 plus mandatory human review gate. A trained reviewer in the Hawiyati admin console must APPROVE the KYC session before the level is granted. Reviewer decision is audit-logged. | Government identity services, AML/KYC regulated onboarding, high-risk financial services | Frozen — pending biometric approval |
Level Transitions
Assurance levels can only increase through a successful KYC workflow. Downgrade is an administrative action (e.g., document revoked). The SP receives the current assurance level as a claim in SAML assertions (hawiyati:assurance_level) and OIDC ID tokens (assurance_level claim).
Document Fingerprint & Duplicate Detection
At L2 and above, Hawiyati computes a document fingerprint as HMAC-SHA256(country || "|" || docType || "|" || docNumber) using a server-side HMAC key. If the same fingerprint appears on a second user account, the KYC session is flagged for manual review — it is not automatically rejected. This allows legitimate document re-use scenarios (family documents, etc.) while surfacing potential fraud for human judgment.
Audit Event Reference
Every security-relevant action in Hawiyati produces a structured audit event. Events are immutable once written — no delete or update API is exposed on the audit store.
Always-Present Fields
| Field | Type | Description |
|---|---|---|
@timestamp | ISO-8601 string | UTC timestamp of the event, millisecond precision |
service | string | Originating Hawiyati service (e.g. hawiyati-http-server, hawiyati-admin, hawiyati-scim) |
category | enum | Event category: AUTH, ADMIN, SESSION, KYC, SCIM, FEDERATION |
action | string | Specific action in dot notation (e.g. login.success, user.created) |
outcome | enum | SUCCESS, FAILURE, or ERROR |
severity | enum | INFO, WARN, ERROR, or CRITICAL |
actor.id | string | Identifier of the actor (user UUID, admin operator username, SCIM bearer token ID, or system) |
actor.type | enum | USER, ADMIN, SYSTEM, or SP |
message | string | Human-readable description of the event |
Optional Context Fields
| Field | Present when… |
|---|---|
sp_entity_id | Authentication or federation event involving a specific SP |
session_id | Event occurs within an established session |
mfa_method | MFA verification events (TOTP, EMAIL_OTP, SMS_OTP, FIDO2, RECOVERY_CODE) |
kyc_level | KYC decision events (target or resulting assurance level) |
ip_address | Events with a network origin (login, registration) |
user_agent | Browser-originated events |
correlation_id | Cross-service trace ID for distributed log correlation |
risk_score | Events where the risk engine evaluated a request |
risk_level | LOW, MEDIUM, HIGH, or CRITICAL — when risk engine evaluated |
Event Categories & Actions
AUTH — Authentication Events
| Action | Severity | Description |
|---|---|---|
login.attempt | INFO | Authentication attempt received (before validation) |
login.success | INFO | User authenticated successfully (all factors satisfied) |
login.failure | WARN | Authentication failed — bad credentials or failed factor |
login.locked | WARN | Account locked after threshold failures |
login.denied_risk | WARN | Authentication denied by risk engine in ENFORCE mode |
mfa.enrolled | INFO | New MFA factor enrolled by user |
mfa.verified | INFO | MFA factor verified successfully |
mfa.failed | WARN | MFA factor verification failed |
step_up.triggered | INFO | Step-up authentication required by policy |
step_up.completed | INFO | Step-up authentication successfully completed |
password.changed | INFO | User changed their own password |
password.reset | WARN | Password reset triggered (admin or self-service) |
account.unlocked | INFO | Locked account unlocked by admin |
ADMIN — Administrative Events
| Action | Severity | Description |
|---|---|---|
user.created | INFO | New user account created by admin |
user.modified | INFO | User account attributes updated |
user.activated | INFO | Inactive user account activated |
user.deactivated | WARN | User account deactivated (active=false) |
user.approved | INFO | pendingApproval cleared; account no longer ACTIVE_LIMITED |
sp.registered | INFO | New service provider registered in SP registry |
sp.modified | INFO | SP configuration updated |
sp.removed | WARN | SP removed from registry |
policy.created | INFO | New authentication policy created |
policy.modified | INFO | Authentication policy rules updated |
policy.deleted | WARN | Authentication policy deleted |
admin.login | INFO | Admin operator authenticated to admin console |
admin.logout | INFO | Admin operator session terminated |
admin.operator_created | WARN | New admin operator account created |
admin.operator_role_changed | WARN | Admin operator role modified (SUPER_ADMIN / ADMIN / VIEWER) |
SESSION — Session Events
| Action | Severity | Description |
|---|---|---|
session.created | INFO | New user session established after successful authentication |
session.expired | INFO | Session reached its TTL and was removed from Redis |
session.invalidated | INFO | Session explicitly terminated (logout or admin revocation) |
session.concurrent_limit | WARN | New session refused due to concurrent session limit policy |
KYC — Identity Verification Events
| Action | Severity | Description |
|---|---|---|
kyc.started | INFO | KYC workflow session initiated for user |
kyc.document_submitted | INFO | Document captured and submitted for validation |
kyc.document_verified | INFO | OCR/MRZ validation passed; document data extracted |
kyc.document_rejected | WARN | Document failed validation (expired, MRZ mismatch, unsupported type) |
kyc.selfie_captured | INFO | Selfie image captured for face match (Standard workflow and above) |
kyc.liveness_passed | INFO | Liveness check passed (Strong workflow and above) |
kyc.liveness_failed | WARN | Liveness check failed |
kyc.face_match_scored | INFO | Face match score computed and stored |
kyc.approved | INFO | KYC session approved; assurance level updated in kyc_profiles |
kyc.rejected | WARN | KYC session rejected (automated or manual) |
kyc.reviewer_decision | INFO | Human reviewer approved or rejected L4 KYC session |
kyc.duplicate_fingerprint | WARN | Document fingerprint matched an existing user; flagged for review |
kyc.reverification_triggered | INFO | Admin or policy triggered reverification workflow for user |
SCIM — Provisioning Events
| Action | Severity | Description |
|---|---|---|
scim.user_provisioned | INFO | New user account created via SCIM POST /Users; starts MIGRATED_UNCLAIMED |
scim.user_updated | INFO | User attributes updated via SCIM PATCH /Users/{id} |
scim.user_deprovisioned | WARN | User account deactivated via SCIM DELETE /Users/{id} or active=false PATCH |
scim.group_synced | INFO | Group membership synchronized via SCIM /Groups endpoint |
FEDERATION — SSO & Token Events
| Action | Severity | Description |
|---|---|---|
saml.assertion_issued | INFO | SAML assertion signed and delivered to SP ACS URL |
saml.authn_request_received | INFO | SP-initiated AuthnRequest received and validated |
saml.slo_initiated | INFO | Single Log-Out sequence initiated (IdP-initiated or SP-initiated) |
saml.slo_completed | INFO | SLO chain completed for all registered SP sessions |
oidc.token_issued | INFO | ID token and access token issued after authorization code exchange |
oidc.token_refreshed | INFO | Access token refreshed via refresh token grant |
oidc.token_revoked | INFO | Token revoked via /oauth2/revoke endpoint |
oidc.logout | INFO | RP-initiated logout received and session terminated |
Audit Log Access & Reporting
Audit logs are accessible via the admin console UI, the admin REST API, and optionally via syslog streaming to an external SIEM.
Admin Console Search
The admin console Audit Logs page supports filtering by:
- Time range — absolute (from/to datetime picker) or relative (last 1h, 6h, 24h, 7d, 30d)
- Service — hawiyati-http-server, hawiyati-admin, hawiyati-scim, hawiyati-kyc, etc.
- Category — AUTH, ADMIN, SESSION, KYC, SCIM, FEDERATION
- Action — specific action string (prefix-match supported)
- Outcome — SUCCESS, FAILURE, ERROR
- Severity — INFO, WARN, ERROR, CRITICAL
- Actor — user UUID, admin username, or SP entity ID
Results are paginated (50 per page). Click any event to expand the full JSON payload.
Export
Filtered results can be exported in two formats:
| Format | Max Rows | Use Case |
|---|---|---|
| JSON (newline-delimited) | 50,000 | SIEM ingestion, programmatic analysis, long-term archival |
| CSV | 50,000 | Spreadsheet review, regulatory evidence packages, manual audit |
Admin API Access
GET /admin/api/audit-logs Authorization: (admin session cookie) Query parameters: from ISO-8601 datetime (e.g. 2026-09-01T00:00:00Z) to ISO-8601 datetime category AUTH | ADMIN | SESSION | KYC | SCIM | FEDERATION action string (prefix match) outcome SUCCESS | FAILURE | ERROR severity INFO | WARN | ERROR | CRITICAL actor_id string page integer (default 0) size integer (default 50, max 200) format json | csv (default json)
SIEM Integration
For real-time log streaming, configure syslog forwarding in application.yml:
hawiyati:
audit:
syslog:
enabled: true
host: siem.internal.example.com
port: 514
protocol: TCP # TCP recommended for reliability
format: CEF # Common Event Format or JSON
Hawiyati's audit library (hawiyati-audit) also exposes a Prometheus metrics endpoint and OpenTelemetry traces for integration with observability platforms.
Retention Policy
- Minimum recommended: 12 months for regulatory environments (adjust per local data protection requirements)
- High-assurance environments: 3–7 years (government, financial services)
- Hawiyati stores events in PostgreSQL (
hawiyati_identityschema,audit_eventstable). Configure a scheduled purge job for records beyond the retention window. - The customer is responsible for defining and enforcing the retention policy.
Standard Compliance Reports
| Report | Filters | Typical Use |
|---|---|---|
| Authentication Summary | category=AUTH, period=last 30d | Monthly login volume, failure rate trend, MFA adoption |
| Failed Login Report | category=AUTH, action=login.failure, outcome=FAILURE | Brute-force detection, account compromise investigation |
| Admin Activity Report | category=ADMIN, actor.type=ADMIN | Privileged action audit, change management evidence |
| KYC Decision Report | category=KYC, action=kyc.approved or kyc.rejected | KYC throughput, rejection rates, reviewer activity |
| SCIM Provisioning Report | category=SCIM | User provisioning/deprovisioning audit for access reviews |
| High-Severity Events | severity=CRITICAL or ERROR | Security incident triage, anomaly investigation |
Compliance Responsibility Matrix
Hawiyati provides the technical controls and tooling. The customer organisation is responsible for the compliance, legal, and operational obligations that surround those controls.
| Domain | Hawiyati Provides | Customer Responsible For |
|---|---|---|
| Identity Proofing | KYC workflow orchestration (capture, OCR/MRZ, liveness, face match, human review gate), assurance level management | Lawful purpose determination, applicant notice, acceptable documents policy, threshold configuration, reviewer authority, appeal and escalation policy |
| Credential Security | Argon2id password hashing (server-side), FIDO2/passkey support, TOTP secret encryption (AES-256-GCM), recovery code hashing | Password policy enforcement (minimum length, complexity, history), MFA policy configuration per SP, MFA enrolment requirement enforcement |
| Data Residency | On-premises deployment architecture; no cloud data transfer; all data stays on customer infrastructure | Infrastructure location selection, data classification, network security boundary definition, physical access controls |
| Audit Trail | Immutable structured audit log; no delete/update API; CEF/syslog + Prometheus + OTel output; admin console search and export | Audit log retention schedule, SIEM integration and configuration, access controls on audit data, log integrity monitoring |
| KYC Compliance | Document capture, OCR/MRZ validation, liveness, face match, reviewer queue UI, duplicate fingerprint detection | Regulatory determination of acceptable KYC levels, reviewer training and authority, document acceptance policy, rejection appeal process |
| Data Retention | Configurable retention settings; user deletion API (cascades to related records) | Retention schedule definition, automated purge job operation, right-to-erasure process management |
| Access Control | RBAC for admin operators (SUPER_ADMIN / ADMIN / VIEWER); role assignment UI; audit of all admin actions | Admin account lifecycle (creation, leaver process), role assignment decisions, periodic access review, emergency access procedures |
| Incident Reporting | Audit events and Prometheus alerts for anomaly detection; structured log output for SIEM correlation | Breach notification obligations to regulators and affected individuals, incident response procedures, regulator reporting timelines |
| Penetration Testing | Architecture documentation and security control descriptions for test scoping | Commissioning and scheduling penetration tests, remediation of findings, test result retention |
| Business Continuity | Backup-friendly architecture (PostgreSQL + Redis); documented restore procedures | Backup schedule operation, DR test execution, RTO/RPO target definition, continuity plan documentation |
Privacy & Data Protection
As an on-premises platform, Hawiyati processes personal data entirely within the customer's infrastructure. The customer organisation is the data controller; Hawiyati acts as a technical processor.
Personal Data Handled by Hawiyati
| Data Element | Where Stored | Retention | Notes |
|---|---|---|---|
| Username | users.username | Until user deleted | Unique identifier; may be an email address |
| Email address | users.email | Until user deleted | Used for OTP delivery and notifications |
| Phone number (E.164) | users.phone_number | Until user deleted | Used for SMS OTP delivery |
| Name fields | users table | Until user deleted | Given name, family name (optional) |
| Document metadata | kyc_profiles / kyc_sessions | Per retention policy | Country, document type, document number (fingerprinted); NOT raw images by default |
| Face match score | kyc_sessions.face_match_score | Per retention policy | DOUBLE PRECISION score only; raw biometric images not persisted (vendor-dependent) |
| Session metadata | Redis (transient) | Session TTL (configurable) | Device fingerprint, IP address, MFA state; evicted on expiry |
| Audit events | audit_events table | Per retention policy | Contains IP address and user agent; no credentials or tokens |
| TOTP secrets | user_credentials | Until credential deleted | AES-256-GCM encrypted at rest |
| FIDO2 public keys | webauthn_credentials | Until credential deleted | Public key only; private key never reaches server |
Data Minimisation
- Raw KYC document images are not persisted by Hawiyati's core platform — retention depends on the biometric vendor integration configuration. Confirm vendor behaviour before go-live.
- Raw selfie images are not persisted — only the face match score is stored.
- Session tokens are stored as opaque 256-bit random values — the token value itself is never logged.
- OTP codes are not stored after verification — only delivery status is recorded.
Right to Erasure
Deleting a user account via the admin API or admin console triggers a cascade delete across:
users— primary user recorduser_credentials— all credential records (password hash, TOTP secrets, FIDO2 keys, recovery codes)user_sessions— database session recordskyc_profilesandkyc_sessions— KYC dataconsent_records— SP consent grants- Redis — active sessions evicted immediately on delete
Audit events referencing the deleted user are retained — audit log immutability takes precedence. The actor.id in those events becomes an orphaned UUID. Define your policy on audit event retention for deleted users before go-live.
Controller / Processor Relationship
Cross-Border Data Transfer
Not applicable by design. Hawiyati is deployed on-premises within the customer's infrastructure. No personal data is transferred to Hawiyati's vendor systems, cloud services, or any third party as part of normal operation. The customer controls all data flows.
Regulatory Context
Hawiyati is designed for deployment in regulated environments. It is not a certified product — the customer organisation uses Hawiyati as a component within their broader compliance programme.
Target Environments
| Sector | Typical Requirements | Hawiyati Controls |
|---|---|---|
| Government Digital Services | Strong identity proofing, audit trails, MFA for high-risk actions, data sovereignty | L2–L4 KYC workflows, immutable audit log, MFA policy engine, on-prem deployment (no cloud transfer) |
| Financial Services | AML/KYC customer onboarding, MFA for transaction authorisation, audit retention (5–7 years) | Document verification workflows, face match, risk engine, configurable audit retention |
| Healthcare | Patient identity verification, audit of data access, strong authentication for clinicians | Identity proofing workflows, audit events on all data access, FIDO2/AAL3 policy support |
| Algeria eGovernment | National ID document verification, Arabic locale support, data residency within Algeria | MRZ validation for Algerian national ID, Arabic UI (Alexandria font), on-prem deployment |
Relevant Frameworks
- NIST SP 800-63 — Digital identity guidelines (see alignment section above)
- ISO/IEC 27001 — Information security management system; Hawiyati's security controls support ISO 27001 Annex A control objectives
- NIST Cybersecurity Framework (CSF) — Identify, Protect, Detect, Respond, Recover mapping available on request
- SOC 2 Type II — Applicable if the customer operates Hawiyati as a cloud or shared service; on-prem deployments require customer-side SOC 2 scope definition
- GDPR / Local Data Protection Law — Customer is data controller; DPIA required; Hawiyati provides technical control evidence
- eIDAS (EU) — If used as a component in an EU trust service; formal eIDAS compliance requires accreditation by a conformity assessment body
Engagement Model
Hawiyati's vendor team can provide the following to support customer compliance programmes on request:
- Architecture and security control descriptions
- Cryptographic algorithm specifications and key management documentation
- Audit log schema and event catalogue (this document)
- Flyway migration history (database schema change record)
- Penetration test executive summary (subject to NDA)
- DPIA technical annex (controls description for data protection impact assessments)
Contact your Hawiyati account team to request compliance documentation packages.
Evidence & Audit Support
When your organisation undergoes a compliance audit, penetration test, or regulatory review, this section describes what evidence Hawiyati can provide and what the customer must supply independently.
What Hawiyati Provides
| Evidence Item | Format | Notes |
|---|---|---|
| Architecture documentation | HTML / PDF | This documentation set; deployment topology; service map |
| Security control descriptions | Documentation / technical annex | Cryptography, key management, session security, network controls |
| Encryption algorithm specifications | Documentation | Argon2id parameters, AES-256-GCM fields, RS256 key sizes, HMAC-SHA256 usage |
| Audit log schema | This document | Complete event catalogue with field definitions and example payloads |
| Flyway migration history | Database table flyway_schema_history |
Full database schema change record with timestamps and checksums |
| Penetration test summary | PDF (on request, under NDA) | Most recent vendor-commissioned penetration test executive summary |
| DPIA technical annex | Document (on request) | Technical controls description for data protection impact assessments |
What the Customer Must Provide
| Evidence Item | Owner |
|---|---|
| Operational procedures (change management, access review, incident response) | Customer IT / CISO |
| Risk assessment covering the Hawiyati deployment | Customer Risk Team |
| Data Protection Impact Assessment (DPIA) | Customer Data Protection Officer |
| Data inventory and processing register | Customer DPO |
| Incident response records (if incidents occurred) | Customer Security Operations |
| Access review records (admin operator accounts, SCIM tokens) | Customer IT Admin |
| Penetration test commissioning and remediation records | Customer Security Team |
| Business continuity and DR test records | Customer IT / Operations |
| Staff training records (admin operators, KYC reviewers) | Customer HR / Compliance |
Audit Log Evidence Package
For audits requiring evidence of specific events (e.g., "show all admin changes in the past 6 months"), use the admin console or admin API to export filtered audit logs:
- Navigate to Admin Console → Audit Logs
- Set the time range to the audit period
- Filter by category (e.g., ADMIN for privileged action review)
- Export as JSON for machine-readable evidence or CSV for spreadsheet review
- Include the export alongside your audit evidence package
For large audit periods, export in monthly batches (50,000-row limit per export).
Requesting Compliance Documentation
To request a compliance documentation package (architecture documentation, security control descriptions, penetration test summary, DPIA technical annex), contact your Hawiyati account team with:
- The compliance framework or regulation you are addressing
- The specific controls or evidence items required
- The submission deadline
- Any NDA or confidentiality requirements
Allow a minimum of 10 business days for documentation packages. Penetration test summaries require a signed NDA before release.