Product Overview
Hawiyati (هويتي — "My Identity") is an on-premises Identity and Access Management platform for organizations that require full sovereignty over their identity infrastructure. It delivers enterprise-grade SSO, adaptive MFA, SCIM provisioning, KYC document verification, and compliance-grade audit logging — all running inside your own network.
Hawiyati (هويتي — "My Identity") is an on-premises Identity and Access Management platform for organizations that require full sovereignty over their identity infrastructure. It delivers enterprise-grade SSO, adaptive MFA, SCIM provisioning, KYC document verification, and compliance-grade audit logging — all running inside your own network.
What is Hawiyati?
Hawiyati (هويتي — "My Identity") is an on-premises Identity and Access Management platform for organizations that require full sovereignty over their identity infrastructure. It delivers enterprise-grade SSO, adaptive MFA, SCIM provisioning, KYC document verification, and compliance-grade audit logging — all running inside your own network.
At its core, Hawiyati is a federation hub: users authenticate once, and Hawiyati issues signed SAML assertions or OIDC tokens to every connected application. Authentication policy, multi-factor enforcement, adaptive risk scoring, and session lifecycle are all centralized in the platform, so individual applications never need to implement their own authentication.
Data sovereignty by design
| Constraint | How it is enforced |
|---|---|
| No external runtime calls | Authentication flows make no outbound HTTP calls to third-party services. All resources are served locally. |
| No telemetry | The platform does not phone home, transmit usage data, or contact vendor infrastructure during operation. |
| Credentials never in plaintext at rest | Passwords: Argon2id. TOTP secrets: AES-256-GCM. FIDO2: public key only stored. Recovery codes: Argon2id hash, shown once then discarded. |
| No secrets in audit events | Passwords, OTP values, and tokens are explicitly excluded from all audit event fields. |
| Bundled UI assets | Fonts, icons, and frontend assets are served locally. No CDN or Google Fonts dependency at runtime. |
| Internet-isolated operation | After initial installation, the platform operates fully without internet access. Geolocation data is loaded locally. |
Why On-Premises?
Cloud-hosted identity platforms (Okta, Entra ID, Ping Cloud) route authentication events and user data through external infrastructure. For organizations subject to local data sovereignty laws, national security requirements, or network isolation policies, this is not acceptable.
Hawiyati runs entirely inside the customer's network. It has no phone-home behavior, no external API calls at runtime, no CDN-hosted assets, and no requirement for internet connectivity during operation. This makes it suitable for:
| Audience | Key requirement met |
|---|---|
| Government agencies | Sovereign deployment with no external data flows. Supports Arabic-locale UI. Meets local data residency requirements. |
| Financial institutions | Compliance-grade audit trail, MFA enforcement, adaptive access by network zone and risk score, LDAP/AD integration. |
| Healthcare organizations | Role-based access control, session management, consent tracking, exportable audit logs for regulatory review. |
| Enterprise IT teams | Centralized SSO for all SAML 2.0 and OIDC applications, SCIM provisioning, user lifecycle management. |
| Security operations | Real-time risk signals, login activity monitoring, device tracking, SIEM-compatible audit output. |
Current Maturity
Hawiyati has a working core suitable for proof-of-concept and pilot deployments. Some items require hardening before production use. Review the tables below before committing to a production deployment timeline.
Complete and functional
| Area | Status |
|---|---|
| SSO (SAML 2.0 and OIDC) with working SP demos for each protocol | Done |
| Full MFA stack: password, TOTP, email OTP, SMS OTP, FIDO2/passkeys | Done |
| Adaptive access engine with risk scoring and enforcement | Done |
| LDAP/AD bind and sync | Done |
| SCIM 2.0 inbound provisioning API | Done |
| Self-service account portal (profile, security, devices, sessions, activity, privacy) | Done |
| Admin console — users, groups, applications, policies, audit logs | Done |
| Structured audit log with database storage and SIEM-compatible output | Done |
| KYC document upload and admin review | Done |
Requires hardening before production
| Item | Phase |
|---|---|
| gRPC mutual TLS between internal services (currently plain gRPC in dev) | Phase 4 |
| Secrets management integration (HashiCorp Vault; currently config-file secrets) | Phase 4 |
| Automated account recovery flows | Phase 4 |
| Full automated deployment pipeline and backup automation | Phase 4 |
| Security testing and formal vulnerability assessment | Phase 4 |
| Gateway authentication (JWT / session cookie validation at the edge) | Phase 4 |
| Cryptographic library migration (OpenSAML 5 + Nimbus JOSE+JWT + BouncyCastle FIPS) | Phase 4 |
Server Requirements
| Resource | Minimum (Pilot) | Recommended |
|---|---|---|
| CPU | 4 vCPU | 8 vCPU |
| RAM | 8 GB | 16 GB |
| Disk | 50 GB SSD | 200 GB SSD |
| OS | RHEL 8+, Ubuntu 22+ | RHEL 9 |
| Java | Java 21 (OpenJDK) | Java 25 (OpenJDK) |
| Database | PostgreSQL 14+ | PostgreSQL 16 |
| Cache | Redis 7+ | Valkey 8 |
For high-availability deployments, add a PostgreSQL streaming replication standby and a Redis Sentinel cluster. See the Operations Guide for details.
Platform Architecture
Hawiyati is a microservices platform. Each service is a self-contained Spring Boot JAR deployed on customer-managed infrastructure. Services communicate internally via gRPC. External browser and API traffic enters through an HTTP gateway.
The sections below cover the platform's architecture zones and service topology. For deployment details and per-module configuration, see the Implementation Guide.
Design principles
| Principle | What it means |
|---|---|
| Sovereign by design | No runtime component makes outbound calls to external services. All assets are bundled locally. The platform operates with no internet connectivity after installation. |
| Defense in depth | Identity data and configuration data live in separate database schemas and can be on different physical servers. Browser-facing services are distinct from internal gRPC services. Authentication logic is separated from protocol encoding. |
| Stateless federation layer | Authentication state runs on the IdP. Sessions are in Redis with an opaque token issued to the browser. The federation layer is stateless — it reads the session, builds the assertion or token, and discards nothing. |
| Pluggable auth methods | The authenticator pipeline is a registry of named providers. The login flow selects which providers to invoke based on the authentication policy bound to the target application. |
Service Topology
The diagram below shows how services relate across the network — from external users through the gateway, HTTP services, internal gRPC services, and down to the data layer.
End users
Applications
Applications
HR / IGA systems
hawiyati_identity (13 tables)
SP config cache (pub/sub invalidation)
Trust Boundary View
Services are grouped into four trust zones. Network firewall rules should enforce these boundaries: only the gateway and direct-access services are externally reachable; gRPC and data services are internal-only.
Service Map
HTTP-facing services
| Service | Port | Role |
|---|---|---|
hawiyati-gateway | 8080 | Edge router — Spring Cloud Gateway. Routes inbound requests to downstream services. |
hawiyati-http-server | 8085 | IdP browser entry point. Hosts login, MFA, registration, and password-reset flows. Handles SAML SSO and ACS endpoints. |
hawiyati-federation | 8087 | Federation orchestrator. Hosts all OIDC endpoints (/oidc/authorize, /oidc/token, /oidc/userinfo, /oidc/jwks, /.well-known/openid-configuration). |
hawiyati-admin | 8095 | Administrator console. Web UI and REST API for managing users, applications, policies, audit logs, and settings. Role-gated. |
hawiyati-account | 8096 | End-user self-service portal (BFF pattern). Users manage profile, security factors, devices, sessions, activity log, and privacy settings. |
hawiyati-scim | 8098 | SCIM 2.0 inbound provisioning API. External HR systems or IGA platforms push user records here using Bearer token auth. |
Internal gRPC services
| Service | Role |
|---|---|
hawiyati-infra | SP registry and configuration service. Loads SP registry from sp-registry.yml on first boot, then persists to the database. Other services look up SP configs and signing keys here. |
hawiyati-session | Session lifecycle manager. Creates, reads, and destroys sessions in Redis. Centralizes session serialization across all services. |
hawiyati-cache | Redis cache facade. Provides a consistent caching interface for rate-limit counters, OTP state, and SP config caching. |
Shared libraries (not services)
| Library | Role |
|---|---|
hawiyati-persistence | JPA entities, Flyway migrations (current head: V62), and EncryptionService (AES-256-GCM). |
hawiyati-audit | Structured audit event writer — NDJSON to disk, CEF/syslog forwarder, Prometheus counters, OTel traces, JpaAuditEventSink for the admin console. |
hawiyati-directory | AD/LDAP integration — pass-through bind authentication and periodic directory sync. |
hawiyati-saml-federation | Custom SAML 2.0 implementation: AuthnRequest/Response encoding, metadata, RSA-SHA256 signing, SLO chain. |
hawiyati-openid-federation | Custom OIDC implementation: Authorization Code flow, PKCE, RS256 ID token, claims mapping, token response. |
Network Topology
External users / Service providers
│
▼
┌──────────────────────────────────────┐
│ hawiyati-gateway :8080 │ Edge — routing only
│ Spring Cloud Gateway │
└───────┬──────────────────────────────┘
│ routes by path prefix
├──▶ hawiyati-http-server :8085 IdP browser flows, SAML endpoints
└──▶ hawiyati-federation :8087 OIDC endpoints, discovery
┌─────────────────────────────────────────────────────────┐
│ Direct browser access (not through gateway) │
│ hawiyati-admin :8095 — admin console │
│ hawiyati-account :8096 — self-service portal │
│ hawiyati-scim :8098 — SCIM provisioning API │
└─────────────────────────────────────────────────────────┘
Internal gRPC calls (service-to-service only)
http-server ──gRPC──▶ federation (SSO build)
http-server ──gRPC──▶ session (session R/W)
http-server ──gRPC──▶ infra (SP lookup)
federation ──gRPC──▶ infra (SP lookup, keys)
federation ──gRPC──▶ session (session validation)
admin ──gRPC──▶ infra (SP registry CRUD)
Shared infrastructure
All services ──JDBC──▶ PostgreSQL :5432
All services ──TCP───▶ Redis/Valkey :6379
Mutual TLS for inter-service gRPC channels is planned for Phase 4. In the current release, internal gRPC traffic should be restricted to a trusted network segment.
Trust Zones
Zone A — Public internet / customer network ├── Browser users (employees, end users) └── Service providers (SAML SPs, OIDC relying parties, SCIM clients) Zone B — Hawiyati HTTP services (browser-accessible) ├── hawiyati-http-server (login, SAML ACS) ├── hawiyati-federation (OIDC endpoints, discovery) ├── hawiyati-admin (admin console — network-restrict this) ├── hawiyati-account (self-service portal) └── hawiyati-scim (provisioning API) Zone C — Internal gRPC services (no public exposure) ├── hawiyati-infra ├── hawiyati-session └── hawiyati-cache Zone D — Data tier (no public exposure) ├── PostgreSQL └── Redis / Valkey
Recommended network controls:
- The admin console (
:8095) must be restricted to the corporate management network or VPN — not public-facing. - The SCIM API (
:8098) should only be reachable from provisioning sources (HR system, IGA platform). - Zones C and D must not be reachable from Zone A. Firewall rules should limit PostgreSQL and Redis access to the Hawiyati service hosts only.
- All public endpoints must be served over TLS. Production deployments should use an internal CA or a trusted public CA.
Data Stores
PostgreSQL — source of truth
PostgreSQL holds all durable identity and configuration state, partitioned into two schemas:
hawiyati_config schema — IdP configuration (24 tables)
Application (SP) registrations, authentication policies, network zones, admin operator accounts, LDAP configurations, SCIM tokens, system settings, and audit event records.
| Category | Tables |
|---|---|
| Application registry | service_providers, sp_saml_config, sp_oidc_config, sp_oidc_redirect_uris, sp_oidc_scopes, sp_auth_methods |
| Authentication policies | auth_policies, policy_rules, rule_conditions, rule_actions, rule_action_methods, network_zones, network_zone_cidrs |
| Administration | admin_operators, admin_roles, admin_totp_credentials, admin_recovery_codes |
| Directory integration | ldap_directories, external_sql_stores, user_store_config |
| System | instance_settings, scim_tokens, audit_events, registration_policy |
hawiyati_identity schema — end-user directory (13+ tables)
| Category | Tables |
|---|---|
| Users and groups | users, user_groups, user_group_members |
| Credentials | user_totp_credentials, user_recovery_codes, user_fido2_credentials |
| Session and risk | login_attempts, user_known_devices, user_auth_geo |
| Self-service and governance | consent_record, user_unique_attribute_value, invitation_tokens, user_kyc_submissions, kyc_profiles |
Schema isolation: The identity schema can be placed on a physically separate PostgreSQL server. Schema evolution is managed by Flyway (embedded in hawiyati-persistence). Current head: V62.
Redis / Valkey — transient state only
| Key space | Contents |
|---|---|
| IdP sessions | Authenticated user sessions — user ID, MFA state, active SP sessions, login flow progress |
| OIDC/SAML in-flight | Authorization request parameters, stored between the authorization request and code exchange |
| OTP codes | Short-lived codes for email and SMS OTP (with TTL) |
| Rate-limit counters | Sliding-window counters for SMS OTP sends, login attempts, and API endpoints |
| SP config cache | Cached SP registry entries — invalidated via Redis pub/sub channel sp-config:invalidate |
Redis is safe to flush and restart. Sessions will be lost (users must re-authenticate), but no permanent identity data is affected. Hawiyati is compatible with both Redis 7+ and Valkey 7+.
Encryption at Rest
All sensitive fields are encrypted at rest using AES-256-GCM via EncryptionService. The encryption key is read from the HAWIYATI_ENCRYPTION_KEY environment variable at startup.
| Field | Table | Method |
|---|---|---|
| TOTP secrets | user_totp_credentials | AES-256-GCM (encrypted, recoverable in memory) |
| LDAP bind passwords | ldap_directories | AES-256-GCM |
| SMTP password | instance_settings | AES-256-GCM |
| Identity DB connection password | identity_db_connection | AES-256-GCM |
| OIDC signing keys | sp_oidc_config | AES-256-GCM |
| User passwords | users | Argon2id (one-way hash) |
| Admin operator passwords | admin_operators | Argon2id (one-way hash) |
| Recovery codes | user_recovery_codes | Argon2id (plaintext shown once at generation only) |
| SCIM tokens | scim_tokens | SHA-256 (raw token shown once at generation only) |
Identity Model
Entity types
| Entity | Schema | Notes |
|---|---|---|
| End user | hawiyati_identity.users | Identified by a stable UUID. Attributes: username, email, phone, name, active state, source type, custom attributes. Created via admin CRUD, self-service registration, LDAP JIT, SCIM push, or SQL sync. |
| Admin operator | hawiyati_config.admin_operators | Separate from end users. Authenticate to the admin console only. Governed by admin RBAC roles. |
| Group | hawiyati_identity.user_groups | Local or LDAP-sourced. Used by policy conditions and admin assignment workflows. |
| Device | hawiyati_identity.user_known_devices | Created by the adaptive risk engine when a new device fingerprint is seen. Users can rename or revoke devices in the account portal. Revocation is soft. |
| Service Provider | hawiyati_config.service_providers | A SAML SP or OIDC relying party registered in the admin console. Has its own attribute release policy and authentication policy binding. |
User Store Modes
Hawiyati operates with one active user store at a time. The active mode is set in Admin → Settings → User Stores.
| Mode | Authentication behavior |
|---|---|
| Local | Users are created and managed inside Hawiyati. Passwords are hashed with Argon2id. All MFA methods available. |
| LDAP / Active Directory | Password is a pass-through LDAP bind against the configured directory server. On first successful bind, a shadow user record is created just-in-time. Periodic sync imports attributes and group memberships. |
| SCIM | Users are provisioned into the local database via the SCIM API. Authentication then uses the local credential (provisioning tools typically set an initial password or trigger a password-reset flow). |
| External SQL | Hawiyati reads users from a customer-managed relational database. Passwords are verified against the stored hash using the customer's configured algorithm. Read-only bridge — user data is not copied. |
Authentication Methods
MFA Login Flow
Every login begins when the user's browser follows a SAML SSO request or OIDC authorization redirect to Hawiyati's IdP endpoint. The IdP drives the user through a sequence of authentication steps determined by the authentication policy bound to the target application.
How the step sequence is built
| Policy result | Step sequence |
|---|---|
ALLOW | Password only (pwd). |
MFA_REQUIRED with specific factors | Password, then each required factor in order (e.g. pwd → totp). User cannot switch methods. |
MFA_REQUIRED with no specific factors | Password, then a method picker showing all MFA methods the user has enrolled. |
DENY | A denial screen — no credentials are accepted. |
Login flow state
The login engine maintains a LoginFlowState in the user's IdP session for the duration of authentication. It holds: provider sequence, step index, username, AMR list (methods successfully completed so far), LoA reached, and per-provider scratch state (OTP hash, FIDO2 challenge). The flow is complete when the step index passes the end of the sequence.
SSO fast path
If the user's IdP session is already authenticated when a new SSO request arrives, authentication steps execute without showing the login page. The user is redirected through the SP with a new assertion, invisible to them.
Assurance Levels
Hawiyati tracks the highest authentication assurance level (AAL) reached during login. This value is available in the OIDC acr claim and SAML AuthnContextClassRef.
| Level | Name | Achieved by |
|---|---|---|
| AAL1 | Single factor | Password only (Argon2id or LDAP pass-through). Minimum for any authenticated session. |
| AAL2 | Multi-factor or phishing-resistant single factor | Password + any MFA method (TOTP, email OTP, SMS OTP), or FIDO2 alone. FIDO2 also satisfies phishing-resistance. |
The amr list in the session (and the OIDC token) records every method used, in order (e.g. ["pwd", "totp"]). Applications that need to verify the exact methods used should inspect amr rather than relying on acr alone.
For identity proofing assurance levels (L0–L4 per NIST SP 800-63A-4), see the Registration & KYC guide.
SAML 2.0 and OIDC Request Flows
SAML 2.0 SP-initiated SSO
1. User visits the application (SP) 2. SP builds a SAML AuthnRequest, redirects browser to GET /saml/sso on hawiyati-http-server (HTTP-Redirect binding) 3. http-server decodes the AuthnRequest, stores it in the IdP session, redirects to /idp/login 4. User enters credentials + completes MFA on hawiyati-http-server 5. http-server calls hawiyati-federation over gRPC to build the signed SAML Response + Assertion (RSA-SHA256, Assertion element) 6. http-server renders an auto-POST HTML form; browser POSTs SAMLResponse to the SP's Assertion Consumer Service (ACS) URL 7. SP validates the signature, audience, and conditions; establishes its own session
Single Logout: Hawiyati chains logout to every SP the user visited in that IdP session. The browser is redirected SP-to-SP, each clearing its cookie and sending a LogoutResponse back to Hawiyati.
OIDC Authorization Code flow (with PKCE)
1. User clicks "Sign in" on the application (relying party / RP) 2. RP generates state, nonce, and PKCE pair; redirects browser to GET /oidc/authorize on hawiyati-federation 3. federation validates the request (client_id, redirect_uri, scope), stores the OIDC session, redirects to /idp/login 4. User authenticates + completes MFA on hawiyati-http-server 5. http-server calls federation over gRPC; federation generates an authorization code (valid 60 seconds), redirects browser back to the RP's redirect_uri with ?code=...&state=... 6. RP's server sends a back-channel POST /oidc/token with code + code_verifier to hawiyati-federation 7. federation validates PKCE, client credentials, and code; issues a signed RS256 ID Token + access token 8. RP validates ID Token (signature, iss, aud, exp, nonce); uses sub as the stable user identifier
Feature Matrix
Authentication and MFA
| Capability | Status |
|---|---|
| Password authentication (local Argon2id) | Available |
| Password authentication (LDAP/AD pass-through) | Available |
| TOTP authenticator (RFC 6238, encrypted at rest) | Available |
| Email OTP | Available |
| SMS OTP (configurable HTTP gateway) | Available |
| FIDO2 / WebAuthn / Passkeys | Available |
| Recovery codes (hashed, one-time display) | Available |
| Password-less login | Roadmap |
Application Federation
| Capability | Status |
|---|---|
| SAML 2.0 Identity Provider (SP-initiated and IdP-initiated) | Available |
| OpenID Connect Identity Provider (Authorization Code + PKCE) | Available |
| Per-application authentication policy | Available |
| SAML attribute mapping | Available |
| OIDC scope and claims mapping | Available |
| Front-channel / back-channel logout | Partial |
| WS-Federation | Roadmap |
User Lifecycle and Provisioning
| Capability | Status |
|---|---|
| Local user directory | Available |
| LDAP / Active Directory integration (bind + sync) | Available |
| SCIM 2.0 inbound provisioning API | Available |
| Admin-managed user lifecycle (create, edit, reset, delete) | Available |
| Self-service registration | Available |
| Self-service profile, password, MFA, devices, sessions | Available |
| KYC document upload and admin review | Available |
| External SQL user store (read-only bridge) | Partial |
| SCIM outbound provisioning | Roadmap |
Adaptive Access and Policies
| Capability | Status |
|---|---|
| Per-application authentication policy with first-match rule evaluation | Available |
| Group-based policy conditions | Available |
| Time-of-day and network zone conditions | Available |
| New-device detection | Available |
| Login velocity anomaly detection | Available |
| GeoIP-based risk scoring | Available |
| IP reputation risk signals | Available |
| Enforcement modes: allow, step-up, block | Available |
Administration and Audit
| Capability | Status |
|---|---|
| Web-based admin console | Available |
| User and group management | Available |
| Application (SP) registration — SAML and OIDC | Available |
| Structured audit log (database-backed, searchable) | Available |
| Audit log export to CSV | Available |
| CEF / syslog audit output | Available |
| Prometheus metrics | Available |
| OpenTelemetry tracing | Available |
| Role-based admin access control | Available |