H· Hawiyati Documentation
Hawiyati Platform

Security

Hawiyati Platform

Security Architecture Overview

Hawiyati implements a layered security model. No single control is relied upon exclusively; controls at each layer compensate for weaknesses in adjacent layers.

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 security controls and hardening. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.

Defence-in-Depth Layers

LayerControlsWhere enforced
PerimeterTLS termination, WAF rules, IP blocklist, rate limiting at edgeReverse proxy / load balancer
AuthenticationPassword hashing (Argon2id), TOTP, FIDO2/WebAuthn, OTP, recovery codes, step-up MFA, account lockouthawiyati-http-server
Risk EngineNEW_DEVICE, GEO_VELOCITY, LOGIN_VELOCITY, IP_REPUTATION signals; adaptive MFA escalation or denyhawiyati-federation
AuthorizationAuthentication policies (first-match rules), group-based access, network zone conditions, time windowshawiyati-federation
DataAES-256-GCM encryption for sensitive fields, Argon2id for passwords, TLS for transport, encrypted backupshawiyati-persistence, hawiyati-utils
AuditStructured CEF/JSON audit events for every auth, admin, KYC, and SCIM action; immutable append-only loghawiyati-audit

Trust Boundary Zones

Hawiyati is deployed across five logical trust zones. Controls at each boundary limit the blast radius of a compromise.

External Zone — untrusted
👤 End Users 🏢 Service Provider Applications 🔗 SCIM Provisioning Clients
DMZ / Edge — TLS termination, WAF
Reverse Proxy WAF Load Balancer Rate Limiter
Application Zone — authenticated HTTP
hawiyati-gateway :8080 hawiyati-http-server :8085 hawiyati-admin :8095 hawiyati-scim :8098
gRPC Internal Zone — mTLS recommended
hawiyati-infra hawiyati-cache hawiyati-session hawiyati-federation
Data Zone — most restricted
PostgreSQL :5432 Redis :6379 Backup Storage

Shared Responsibility

ResponsibilityHawiyatiCustomer
Platform software security✓ Provides secure defaults, patchesApplies updates promptly
Infrastructure hardeningGuidance (this document)✓ Owns OS, hypervisor, network
TLS certificatesConfiguration support✓ Procures, rotates, monitors expiry
User data protection✓ Encryption at rest and in transit✓ Data governance, retention policy
KYC compliance✓ Workflow tooling✓ Lawful purpose, regulatory compliance
Audit log retention✓ Produces structured audit events✓ Retention duration, SIEM integration
Incident responseSupport escalation✓ IR plan, on-call runbook

Cryptography & Key Management

Hawiyati applies purpose-fit cryptographic primitives at every sensitivity boundary. No MD5, SHA-1, or DES is used anywhere in the platform.

Cryptographic Primitive Reference

Data / OperationAlgorithmParameters / Notes
Password hashingArgon2idmemory=64 MB, iterations=3, parallelism=1; OWASP recommended minimum
SAML assertion signingRSA-SHA256 (RS256)2048-bit key minimum; 4096-bit recommended for production
OIDC ID token signingRS256Same key infrastructure as SAML; served via /oauth2/jwks
TOTP secret storageAES-256-GCMSecret encrypted at rest in PostgreSQL; per-installation key from hawiyati-utils
FIDO2 credentialsDevice-native (P-256 / Ed25519)Public key only stored; private key never leaves the authenticator device
Session tokensCSPRNG 256-bitOpaque bearer token; stored reference in Redis with short TTL
OTP codes (email / SMS)CSPRNG6-digit numeric; 5-minute TTL; per-MSISDN / per-address rate-limited
Claim tokensCSPRNG 256-bit + HMAC-SHA256256-bit random; HMAC-SHA256 stored; 15-min TTL; single-use
Completion tokensCSPRNG 256-bit + HMAC-SHA256Same mechanics as claim tokens; narrow route allowlist enforced at redemption
Document fingerprintsHMAC-SHA256Of normalised country|docType|docNumber; duplicate = review signal, not hard block
Database column encryptionAES-256-GCMApplied to PII fields (national ID numbers, biometric scores); key managed by hawiyati-utils
gRPC transport (recommended)TLS 1.3mTLS recommended for internal gRPC zone

Key Rotation Procedures

Key and secret rotation with overlap and rollback windows
Old and new versions overlap until validation is stable, allowing controlled rollback before retirement.

SAML Signing Key Rotation

  1. Generate new RSA key pair and self-signed certificate.
  2. Add new certificate to IdP metadata (dual-certificate mode) — share updated metadata with all SPs.
  3. Wait for SP metadata propagation (typically 24–48 hours for enterprise SPs).
  4. Switch signing to new key; retain old key for assertion validation during overlap window (recommend 7 days).
  5. Remove old certificate from metadata after overlap window closes.
Rolling update required

Switching signing keys without a grace period causes SP signature validation failures for any in-flight assertions signed with the old key. Always run dual-certificate mode for at least one business day.

OIDC JWKS Key Rotation

  1. Generate new RSA key pair.
  2. Add new key to JWKS endpoint (/oauth2/jwks) — the endpoint will serve both old and new keys.
  3. Begin signing new tokens with the new key (set kid in JWT header to new key ID).
  4. Retain old key in JWKS for token validation during overlap (recommend 24 hours — cover maximum token TTL).
  5. Remove old key from JWKS after overlap window.

Encryption Key Rotation (AES-256-GCM)

For TOTP secrets and encrypted database columns, rotation requires a re-encryption pass over affected rows. Run during a maintenance window; hawiyati-persistence supports dual-key mode during the transition. Contact support for assisted key rotation procedures.

Recommendation: use an HSM in production

Storing private keys in a Hardware Security Module (HashiCorp Vault, cloud KMS, or a dedicated HSM appliance) prevents key extraction even if the application server is compromised. Configure hawiyati-utils to delegate signing operations to the HSM rather than loading keys into JVM memory.

RBAC Reference

Admin console access is governed by three built-in admin operator roles. There is no per-SP or per-group scoping at this time.

RoleUser ManagementSP / Policy ManagementRisk & AuditAdmin Management
SUPER_ADMIN Full (create, edit, delete, lock, unlock, approve) Full (create, edit, delete, assign) Full (view, export, configure) ✓ Can create / modify / delete other admins
ADMIN Full (create, edit, delete, lock, unlock, approve) Full (create, edit, delete, assign) Full (view, export, configure) ✗ Cannot modify admin operators
VIEWER Read-only (view user list and status) Read-only (view SP and policy list) Read-only (view audit log, no export) ✗ Cannot modify anything

Admin Audit Trail

Every admin console action — user creation, policy modification, SP registration, role assignment, audit log export — generates a structured audit event with the operator's identity, timestamp, action, target object, and outcome. These events cannot be deleted through the admin console and are included in audit log exports.

Principle of least privilege

Grant VIEWER to audit staff who only need to review logs. Grant ADMIN to operators who manage users and SPs. Reserve SUPER_ADMIN for the one or two individuals who need to manage admin accounts. Avoid sharing admin credentials — each operator should have an individual account.

Admin Operator Management

  • Navigate to Admin → Operators to view and manage admin accounts.
  • Create operators with a username, email, initial password, and role assignment.
  • Operators log in at the admin console URL (default: https://localhost:8095).
  • Admin sessions are separate from end-user sessions (different cookie domain and TTL).
  • Admin accounts are subject to the same lockout policy as end users (configurable).
  • SUPER_ADMIN can force-reset any operator's password or revoke their session.

Authentication Security

Hawiyati applies multiple compensating controls to prevent credential theft, session hijacking, and brute-force attacks.

Session Cookie Security

AttributeValuePurpose
HttpOnlytruePrevents JavaScript access; mitigates XSS-based session theft
SecuretrueCookie sent only over HTTPS; prevents interception on plain HTTP
SameSiteStrictPrevents CSRF by blocking cross-site cookie transmission
Host bindingExact hostname matchCookie scoped to dev.hawiyati.org, not .hawiyati.org
Path/Available across all IdP paths
HTTPS is mandatory

Session cookies with Secure flag are silently dropped by browsers over plain HTTP. Running Hawiyati without TLS renders all session management ineffective. Never deploy to production without TLS.

CSRF Protection

Hawiyati uses the Double Submit Cookie pattern combined with SameSite=Strict. All state-changing POST endpoints require a valid CSRF token in the request body that matches the value stored in the CSRF cookie. SAML and OIDC protocol endpoints are exempt (they validate cryptographic assertions instead).

Session Token Lifecycle

  • Issuance: 256-bit CSPRNG token issued on successful authentication; stored in Redis with the configured TTL (default 8 hours, configurable).
  • Rotation on step-up: When MFA is satisfied after an initial username/password step, the session token is rotated to prevent session fixation.
  • Concurrent sessions: Multiple simultaneous sessions are permitted by default. Configure a maximum-session limit per user in Admin → Settings → Session Policy.
  • Explicit logout: Token deleted from Redis immediately on logout; any subsequent request with the revoked token is rejected.
  • Expiry: TTL enforced server-side in Redis; client-side cookie expiry is advisory only.

Account Lockout

ThresholdDefaultConsequenceResolution
Failed login attempts (1st lockout)5 failuresAccount locked for 15 minutesAuto-unlocks; user can retry after TTL
Failed login attempts (2nd lockout)5 more failures after 1st unlockAccount locked for 30 minutesAuto-unlocks after TTL
Persistent failuresConfigurable escalationAccount locked indefinitelyAdmin must manually unlock via admin console

Thresholds and TTLs are configurable in Admin → Settings → Security → Lockout Policy. The risk engine's LOGIN_VELOCITY signal provides complementary IP-level rate limiting.

Brute-Force Detection

The risk engine's LOGIN_VELOCITY signal detects brute-force and credential-stuffing patterns at the IP level, independent of per-user lockout. When the signal fires, the risk action (MFA_STRONG or DENY) applies even if the individual user account has not reached its lockout threshold. This provides protection against slow-and-low attacks spread across many accounts.

Network Security

Secure network configuration is the customer's responsibility. These are the required controls and recommended configurations.

TLS Requirements

EndpointMinimumRecommended
External HTTP (8080, 8085)TLS 1.2TLS 1.3
Admin console (8095)TLS 1.2TLS 1.3
SCIM API (8098)TLS 1.2TLS 1.3
Internal gRPCTLS 1.2mTLS (mutual authentication)
PostgreSQL connectionTLS (require mode)TLS 1.3 + client cert
Redis connectionTLSTLS 1.3 + AUTH password

Cipher Suite Hardening

Disable the following weak cipher suites at the reverse proxy / TLS terminator:

# Ciphers to disable
RC4 variants (RC4-SHA, RC4-MD5)
3DES (DES-CBC3-SHA)
Export-grade ciphers (EXP-*)
NULL ciphers
Anonymous key exchange (aNULL, eNULL)
MD5-based MACs

# Recommended TLS 1.3 ciphers (preferred order)
TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256

# TLS 1.2 fallback (if 1.2 required)
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES128-GCM-SHA256

Security Headers

HeaderRecommended ValuePurpose
Strict-Transport-Securitymax-age=31536000; includeSubDomainsEnforce HTTPS for 1 year
X-Content-Type-OptionsnosniffPrevent MIME type sniffing
X-Frame-OptionsSAMEORIGINPrevent clickjacking (SAML login UI)
Referrer-Policystrict-origin-when-cross-originLimit referrer leakage from SAML redirects
Content-Security-PolicyConfigure per-endpoint (strict CSP for admin console)Mitigate XSS

Firewall Rules

Port exposure policy

Only ports 8080 (gateway) and 8085 (IdP HTTP) should be reachable from the external network. The admin console (8095) and SCIM API (8098) must be restricted to internal networks or VPN-only access.

PortServiceExternalInternalAdmin/VPN
8080Gateway✓ Open✓✓
8085IdP HTTP Server✓ Open✓✓
8087Federation (gRPC)✗ Blocked✓✓
8095Admin Console✗ Blocked✗✓ VPN only
8098SCIM API✗ Blocked✓ Allow from provisioner IPs✓
5432PostgreSQL✗ Blocked✓ App servers only✗
6379Redis✗ Blocked✓ App servers only✗

Reverse Proxy Configuration

  • Strip incoming X-Forwarded-For headers and set only trusted proxy IPs.
  • Strip internal headers (X-Internal-*, X-Admin-*) before forwarding to application services.
  • Configure connection timeouts (recommend: read 30s, write 30s, idle 60s).
  • Enable WAF rules for OWASP Top 10 — particularly SQL injection and XSS. Whitelist SAML/OIDC XML/JWT payloads to avoid false positives.

KYC Security & Assurance Policy

Identity assurance levels are safety-critical data. Incorrect assurance claims can lead to regulatory violations and security incidents.

Assurance Level Source of Truth

Critical: always read from kyc_profiles.current_level

The assurance level for any access control decision must be read from kyc_profiles.current_level in the database. The users.assurance_level column is a denormalised cache used for display only and may be stale. Any integration, policy evaluation, or report that reads assurance level from users.assurance_level is incorrect.

LevelNIST 800-63A AlignmentVerification RequiredCurrent Status
L0IAL1 — Self-assertedEmail or phone ownership onlyAvailable
L1IAL1 — Remote unattendedEmail + phone verifiedAvailable
L2IAL2 — Remote unattendedDocument capture + OCR/MRZ validationAvailable
L3IAL2 — Remote attendedL2 + selfie + liveness detectionFrozen — pending biometric approval
L4IAL3 — SupervisedL3 + human review gateFrozen — pending biometric approval

Document Fingerprinting

When a document is captured during KYC, Hawiyati computes a fingerprint using HMAC-SHA256 of the normalised string country|docType|docNumber. The normalisation step lowercases all fields and strips whitespace before hashing.

If the computed fingerprint matches an existing record, the session is flagged for manual review — it is not automatically rejected. This prevents hard blocks on legitimate shared documents (family members with the same passport number in some jurisdictions) while still surfacing potential fraud for human review.

Biometric Data Handling

  • Face match score is stored as DOUBLE PRECISION in kyc_sessions.face_match_score.
  • Raw biometric images (selfie frames, liveness challenge video) are not persisted by Hawiyati by default — vendor-specific retention depends on the configured biometric provider.
  • Define your data retention and deletion policy for biometric data before going live with L3/L4 workflows.

Reviewer Accountability

Every manual KYC review decision (APPROVE / REJECT / REQUEST_MORE_INFO) generates an audit event containing the reviewer's operator ID, the KYC session ID, the decision, and the timestamp. Reviewer decisions cannot be edited after the fact. The audit trail is available in the audit log export.

L3/L4 frozen in current release

Biometric-level workflows (L3 Strong and L4 High Assurance) are not active in the current release pending biometric provider integration approval. KYC sessions requesting L3/L4 remain in UNDER_REVIEW state until the biometric team manually approves them. Do not rely on automated L3/L4 outcomes for production workflows.

Adaptive access signal, policy, and assurance decision flow
Trusted context feeds policy decisions that allow, step up, deny, or route access for review.

Risk Controls Configuration

The adaptive risk engine evaluates contextual signals on every login and can escalate the required authentication or block access entirely, independently of static policy rules.

Operating Modes

OFF

Risk assessment skipped entirely. No signals evaluated. No performance overhead. Use only when risk engine is not applicable.

MONITOR

Signals evaluated and scored; results recorded in audit log. Risk action never overrides policy. Ideal for initial tuning without user impact.

ENFORCE

Risk action overrides policy when stricter. This is the required production mode. Run MONITOR first; switch to ENFORCE once thresholds are tuned.

Risk Action Strictness Order

The final action applied to a login is always the stricter of the policy action and the risk action. The order from least to most restrictive:

ALLOW
No additional step
→
MFA_ANY
Any enrolled factor
→
MFA_STRONG
FIDO2 only
→
DENY
Login blocked

Risk Scoring

Each enabled signal contributes 0–30 points. Points from all signals are summed and capped at 100. The total is mapped to a risk level using configurable thresholds:

LOW (0–24) → ALLOW MEDIUM (25–49) → MFA_ANY HIGH (50–74) → MFA_STRONG CRITICAL (75+) → DENY

In addition to the numeric score, signals can set a minimum-level override that forces the risk level to be at least a given value regardless of score (e.g., IMPOSSIBLE_TRAVEL forces HIGH regardless of other signals).

Signals

NEW_DEVICE Device Recognition

Checks the hwd_id cookie (UUID, 400-day TTL) against the user's known devices. A new or revoked device contributes MEDIUM or HIGH risk. First-time users are exempt (enrollment baseline).

GEO_VELOCITY Geographic Velocity

Detects physically implausible travel (Haversine distance ÷ elapsed time > 900 km/h = IMPOSSIBLE_TRAVEL with HIGH override). Requires MaxMind GeoIP database. Skipped for private IPs.

LOGIN_VELOCITY Login Rate

Counts failed logins per username and per IP within a 15-minute sliding window. Detects brute-force and credential stuffing. ≥5 user failures or ≥10 IP failures raises MEDIUM; combined ≥25 raises HIGH.

IP_REPUTATION IP Reputation

Checks client IP against admin-maintained CIDR blocklists (malicious IPs, TOR exits, anonymous proxies, datacenter ranges). Points and override levels configurable per category. Skipped if no blocklist loaded.

Signal Fail Modes

Fail ModeBehaviour on Signal ErrorUse Case
OPEN (default)Signal skipped; no points added; assessment continues with other signalsHigh-availability scenarios where a GeoIP DB outage should not block users
CLOSEDSignal contributes a HIGH minimum-level override; user must satisfy FIDO2 MFA until error resolvedHigh-security environments where unknown risk = deny

Recommended Production Configuration

  • Mode: ENFORCE
  • NEW_DEVICE: OPEN fail mode; MEDIUM risk on first new device; HIGH on revoked device
  • GEO_VELOCITY: OPEN fail mode (requires GeoIP DB); load MaxMind GeoLite2 City database
  • LOGIN_VELOCITY: CLOSED fail mode (brute-force protection is core security); default thresholds are reasonable starting points
  • IP_REPUTATION: Import known-bad CIDR lists; review and update monthly
  • Monitor MONITOR mode output for 1–2 weeks before switching to ENFORCE; adjust score thresholds to match false-positive tolerance

Open Redirect Prevention

Hawiyati applies specific design controls to prevent open redirect vulnerabilities, which are a common attack vector in SSO implementations.

Continuation Token Design

When a user initiates a SAML or OIDC flow, the SP context (which application the user is trying to reach) must be preserved across multiple redirects. A naive implementation stores the sp_initiation_url directly, which creates an open redirect: an attacker can craft a login URL that redirects the user to an arbitrary destination after authentication.

Hawiyati instead stores only the sp_entity_id foreign key in the continuation token. At redemption time, the destination URL is looked up from the registered SP record in the database — it cannot be supplied by the user or the SP's AuthnRequest for redirection purposes.

Never store raw redirect URLs in continuation tokens

If you extend the continuation token schema, do not add a raw URL field. Store the entity ID and look up the registered destination from the SP registry at redemption time. An unvalidated URL in a token is an open redirect waiting to happen.

Claim and Completion Token Route Allowlist

Claim tokens (enterprise account claim) and completion tokens (SP-initiated registration) are 256-bit random values with HMAC-SHA256 stored. They are accepted only on a narrow list of routes that have been explicitly configured to accept them. Any other endpoint that receives a claim or completion token returns a 400 error. This prevents token confusion attacks where a token is submitted to an unintended endpoint.

Relay State Validation

SAML RelayState values are validated against the registered ACS URL prefix for the SP before being used in any redirect. An AuthnRequest that includes a RelayState pointing to a different domain than the registered ACS URL is rejected.

Header Injection Prevention

All HTTP response headers set by Hawiyati are constructed from validated, registered values (SP entity IDs, registered redirect URIs). No user-supplied input is interpolated directly into Location or other redirect headers without prior validation against the SP registry.

Secure Configuration Checklist

Complete this checklist before going live. Each item maps to a specific risk; leaving any CRITICAL item incomplete significantly increases your attack surface.

  • TLS 1.3 enabled on all external endpoints Ports 8080 and 8085 must use TLS 1.3 minimum; configure at the reverse proxy layer
    Critical
  • Weak cipher suites disabled Remove RC4, 3DES, export-grade, and NULL ciphers from TLS configuration
    Critical
  • HSTS configured with minimum 1-year max-age Strict-Transport-Security: max-age=31536000; includeSubDomains
    High
  • Admin console (8095) restricted to VPN or internal network Admin console must never be reachable from the public internet
    Critical
  • Default admin password changed on first login The factory admin credential must be replaced before any SP is connected
    Critical
  • Redis AUTH password set and TLS transport enabled Redis stores active sessions and OTP codes — an unprotected Redis is a critical vulnerability
    Critical
  • PostgreSQL pg_hba.conf restricted to application server IPs Only hawiyati-persistence hosts should be permitted to connect to the database
    Critical
  • Flyway baseline migration confirmed on startup Review Flyway logs on first start to confirm V62 (or later) is the current baseline; no migration errors
    High
  • Audit log streaming to SIEM configured Configure syslog forwarding so audit events are preserved in a system the application cannot modify
    High
  • Argon2id parameters reviewed Default (memory=64MB, iterations=3, parallelism=1) meets OWASP minimums; increase for higher-assurance deployments
    Medium
  • Session TTL configured per organisational policy Recommend ≤8 hours for standard deployments; ≤4 hours for high-assurance environments
    Medium
  • Account lockout thresholds reviewed Default 5-failure threshold is suitable for most deployments; review against your brute-force risk tolerance
    Medium
  • Risk engine in ENFORCE mode MONITOR mode provides visibility only; switch to ENFORCE before go-live to activate adaptive controls
    High
  • mTLS configured for internal gRPC services Mutual TLS prevents a compromised application-zone host from calling internal gRPC services without a valid certificate
    High
  • Key rotation schedule documented and calendared SAML signing key and OIDC JWKS should be rotated at least annually; add calendar reminders 60 days before due date
    Medium
  • No default or shared service accounts enabled Each admin operator should have an individual account; shared credentials prevent attribution in audit logs
    High
  • Database backup encryption confirmed pg_dump backups and WAL archives must be encrypted at rest (AES-256) in the backup storage location
    High
  • Certificate expiry monitoring configured Alert at 60 days remaining; alert again at 14 days; automate renewal where possible
    High
  • IP blocklist loaded for IP_REPUTATION signal An empty blocklist means the signal always returns clean; import known-bad CIDR ranges before enabling the signal
    Medium
  • Penetration test scheduled post go-live Arrange a third-party pen test within 90 days of production launch; include SAML/OIDC token security in scope
    Medium
All critical items must be completed before go-live

High and Medium items should be completed before go-live where feasible, and remediated within 30 days otherwise. Document any deferred items with an accepted-risk owner and target remediation date.

HawiyatiDocumentation · v2026 · Spring Boot 3.5