Getting Started
Everything you need to understand, evaluate, and deploy Hawiyati — from first concepts to your first working integration.
Everything you need to understand, evaluate, and deploy Hawiyati — from first concepts to your first working integration.
🏛️ What is Hawiyati?
Hawiyati (هويتي — Arabic for "My Identity") is an on-premises Identity and Access Management (IAM/CIAM) platform built for organizations that require full sovereignty over their identity infrastructure.
The sections below cover getting started with Hawiyati. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.
Hawiyati runs entirely inside the customer's network and provides enterprise-grade authentication, application federation, multi-factor authentication, user lifecycle management, adaptive access policies, and compliance-grade audit logging — with no dependency on any external cloud service, no phone-home behavior, and no external data flows.
Technical foundation
| Layer | Technology | Version |
|---|---|---|
| Application framework | Spring Boot / Spring Cloud Northfields | 3.5.5 / 2025.0.1 |
| Runtime | Java (OpenJDK or GraalVM) | 25 |
| Build system | Maven monorepo | 3.8+ |
| Primary database | PostgreSQL | 16+ recommended |
| Session / cache store | Redis or Valkey | 7+ compatible |
| Inter-service protocol | gRPC (mutual TLS in production) | — |
| Schema migration | Flyway (embedded) | — |
Architecture at a glance
Hawiyati is a microservices platform. All services are self-contained Spring Boot JARs. Browser traffic enters through a gateway and routes to specialized services. Internal communication uses gRPC.
Browser / SP Application
│
▼
hawiyati-gateway (8080) — Spring Cloud Gateway (routing only)
│
├──▶ hawiyati-http-server (8085) — IdP login flows, SAML ACS, OIDC endpoints
├──▶ hawiyati-federation (8087) — OIDC discovery, token issuance
├──▶ hawiyati-account (8096) — End-user self-service portal
├──▶ hawiyati-admin (8095) — Admin console (WebFlux + Thymeleaf)
└──▶ hawiyati-scim (8098) — SCIM 2.0 inbound provisioning
Internal gRPC services:
├── hawiyati-infra — SP registry, configuration service
├── hawiyati-cache — Redis cache facade
└── hawiyati-session — Session lifecycle manager
Shared libraries:
├── hawiyati-persistence — PostgreSQL JPA, Flyway, encryption
├── hawiyati-audit — Structured audit log (CEF/syslog + OTel)
├── hawiyati-saml-federation — Custom SAML 2.0 implementation
└── hawiyati-openid-federation — Custom OIDC implementation
⚡ Key Differentiators
What makes Hawiyati different from cloud-hosted identity platforms (Okta, Entra ID, Ping Cloud)?
-
Full on-premises sovereigntyAuthentication events never leave the customer's network. There are no outbound API calls at runtime, no cloud relay, and no requirement for internet connectivity during operation.
-
Custom SAML 2.0 and OIDC stackHawiyati implements its own federation protocols rather than depending on OpenSAML or Nimbus. This allows direct control over cryptographic operations, attribute mapping, and protocol extensions without third-party library constraints.
-
Arabic-locale support by designThe admin console, account portal, and login UI support RTL Arabic (Alexandria typeface, locale-aware date/number formatting). Built specifically for organizations in Arabic-speaking markets.
-
NIST SP 800-63 alignmentAssurance levels L0–L4 map directly to IAL/AAL requirements. KYC workflows, MFA policy enforcement, and credential storage are designed to satisfy NIST guidelines for regulated deployments.
-
Credentials never leave the server in plaintextPasswords are hashed with Argon2id. TOTP secrets are encrypted at rest. Recovery codes are shown once and stored as hashes. FIDO2 stores only the public key. Nothing sensitive is ever logged.
-
Zero external runtime dependenciesFonts, icons, and UI assets are served locally. Geolocation data is loaded from a bundled database. Bot verification fails closed — no CDN fallback that could leak authentication events.
👥 Who Is It For?
Primary target audiences
| Audience | How Hawiyati helps |
|---|---|
| Government agencies | Sovereign deployment with no external data flows. Supports Arabic-locale UIs. Meets local data residency requirements. NIST 800-63 alignment for assurance levels. |
| Financial institutions | Compliance-grade audit trail, MFA enforcement, adaptive access by network zone and risk score, LDAP/AD integration, KYC document review workflows. |
| Healthcare organizations | Role-based access control, session management, consent tracking, exportable audit logs for regulatory review, assurance-level enforcement per application. |
| Enterprise IT teams | Centralized SSO for all SAML 2.0 and OIDC applications, SCIM provisioning, full user lifecycle management, LDAP/AD directory integration. |
| Security operations teams | Real-time risk signals, login activity monitoring, device tracking, structured audit events compatible with SIEM ingestion (CEF/syslog), Prometheus metrics. |
Four primary user personas
📖 Core Terminology
Terms as used within Hawiyati specifically — not generic textbook definitions. Grouped by domain for quick reference.
Identity & Authentication
| Term | Definition |
|---|---|
| Identity Provider (IdP) | The system that authenticates users and asserts their identity to other systems. In a Hawiyati deployment, Hawiyati itself is the IdP. It owns the login page, evaluates credentials, enforces MFA, and issues federation tokens (SAML assertions or OIDC tokens). |
| Service Provider (SP) | An application that relies on the IdP for authentication. The SP never sees the user's password — it only receives a signed assertion from Hawiyati confirming who the user is and what attributes they carry. Examples: an internal ERP, a web portal, or a SaaS tool configured to use SAML or OIDC. |
| Principal | The authenticated entity making a request. In most cases this is an end user. Throughout Hawiyati, the principal is identified by a stable internal UUID — never by a mutable attribute like username or email address. |
| Credential | Any secret or possession used to prove identity. Hawiyati supports: passwords (Argon2id hash), TOTP secrets (encrypted at rest), FIDO2 public keys, OTP codes (ephemeral), and recovery codes (hashed, shown once). Credentials are never logged. |
| Session | A server-side record of an authenticated user's context stored in Redis. Tracks: authentication time, MFA methods used, risk level, IP address, device fingerprint, and expiry. A user may have multiple concurrent sessions from different devices. |
| Session Token | An opaque identifier issued to the browser as an HttpOnly, Secure, SameSite=Strict cookie that maps to a server-side session. Never embedded in URLs or API responses. |
| Step-Up Authentication | An additional authentication challenge required mid-session to access a sensitive resource. For example: re-authenticating before removing an MFA device, or confirming a password before downloading personal data. |
| Assurance Level (L0–L4) | The identity verification level assigned to a user, aligned to NIST SP 800-63A-4 IAL. L0 = no verification; L1 = basic; L2 = standard KYC; L3 = strong KYC + selfie/liveness; L4 = high KYC + human review. Source of truth is kyc_profiles.current_level. |
| KYC (Know Your Customer) | An optional registration flow where users upload identity documents for review. Completion can be required before access is granted to specific applications. Raises the user's assurance level upon approval. |
| Continuation Token | A short-lived token that stores the sp_entity_id FK for a federated login in progress. Prevents open-redirect attacks by never storing the raw SP initiation URL. |
| Completion Token | A 256-bit random token (HMAC-SHA256 stored, 15-minute TTL, single-use) issued after a migration or claim flow to narrow the route a user can access before fully completing registration. |
Multi-Factor Authentication (MFA)
| Term | Definition |
|---|---|
| MFA Preference | Each user's configured default second factor. Values: PWD_ONLY, PWD_THEN_TOTP, PWD_THEN_OTP, FIDO2. Can be overridden by policy. |
| TOTP | Time-based One-Time Password (RFC 6238). Six-digit code generated by an authenticator app (Google Authenticator, Authy), valid for 30 seconds. Secret encrypted at rest; replay protection enforced — same code cannot be accepted twice. |
| FIDO2 / WebAuthn / Passkey | Public-key authentication backed by device biometrics or hardware security keys. The user's private key never leaves their device. Hawiyati stores only the public key. "Passkey" and "FIDO2 credential" are used interchangeably. |
| Email OTP | A one-time code delivered to the user's email address. 5-minute TTL; rate-limited per address. Depends on outbound mail delivery being configured. |
| SMS OTP | A one-time code delivered via an HTTP SMS gateway (configurable). Per-MSISDN rate limiting applies. Requires a configured SMS provider integration. |
| Recovery Code | A one-time backup code generated when a user enrolls in MFA. Shown to the user exactly once, stored as Argon2id hash. Invalidated permanently after use. Allows account recovery when the primary MFA device is lost. |
Protocols
| Term | Definition |
|---|---|
| SAML 2.0 | XML-based federation standard. Hawiyati acts as a SAML IdP. SPs send an AuthnRequest; Hawiyati returns a signed Response containing an Assertion with the user's identity and attributes. Hawiyati implements its own SAML stack — not OpenSAML. |
| Assertion | A signed statement from an IdP about a user. In SAML: an XML <Assertion> element. In OIDC: an ID Token (signed JWT). Both assert who the user is, when they authenticated, what MFA methods were used, and what attributes they carry. |
| ACS URL | Assertion Consumer Service URL — the endpoint on the SP where Hawiyati posts the SAML Response after authentication. Must use HTTPS in production. |
| Entity ID | The globally unique identifier for a SAML Service Provider. Typically a URL but need not be reachable. Must match exactly between SP metadata and Hawiyati's SP registration. |
| Relay State | An opaque string the SP includes in the SAML AuthnRequest so it can restore state (e.g., the originally-requested page) after authentication completes. Hawiyati passes Relay State through the flow unchanged. |
| SLO (Single Log-Out) | A coordinated logout that ends the session at the IdP and sends logout notifications to all participating SPs. Hawiyati supports front-channel SLO; back-channel is partial — validate per relying party before relying on it. |
| OIDC (OpenID Connect) | A JSON/REST identity layer on top of OAuth 2.0. Hawiyati acts as an OIDC Provider. Applications use Authorization Code + PKCE flow to obtain ID tokens and access tokens. Discovery document at /.well-known/openid-configuration. |
| PKCE | Proof Key for Code Exchange (RFC 7636). Prevents authorization code interception. Client generates a random code_verifier, hashes it to code_challenge, sends with the auth request. Server requires the verifier at the token endpoint. Required for all public OIDC clients. |
| Nonce | A random value included in an OIDC authorization request and embedded in the ID token. The client verifies the nonce to prevent token replay. Hawiyati enforces nonce binding for all OIDC flows. |
| SCIM 2.0 | System for Cross-domain Identity Management — a REST API standard for provisioning users. Hawiyati exposes a SCIM 2.0 Users endpoint for inbound provisioning only (outbound provisioning is on the roadmap). |
Policies & Adaptive Access
| Term | Definition |
|---|---|
| Authentication Policy | An ordered rule set attached to a Service Provider that determines what authentication steps are required. Rules evaluate first-match. Conditions can combine: group membership, network zone, time-of-day, risk score, and device novelty. |
| Risk Score | A numeric value (0–100) computed per authentication attempt from signals: device novelty (NEW_DEVICE), login velocity (VELOCITY), geographic anomaly (GEOIP), and IP reputation (IP_REPUTATION). Maps to levels: LOW / MEDIUM / HIGH / CRITICAL. |
| Enforcement Mode | The action when a policy condition matches: ALLOW (proceed), MFA_REQUIRED (step-up), DENY (block). Strictness order: ALLOW < MFA_ANY < MFA_STRONG < DENY — the stricter of policy vs. risk wins. |
| Network Zone | A named IP range (CIDR block) used in policy conditions. Example: "Corporate VPN" = 10.0.0.0/8. Allows different requirements for corporate vs. external network logins. |
| Adaptive Access | Dynamic adjustment of authentication requirements based on real-time risk signals. When elevated risk is detected, the engine can require step-up authentication or block access without a policy rule change. |
Applications (Service Providers)
| Term | Definition |
|---|---|
| SP Registration | Configuring a Service Provider in Hawiyati's registry. SAML: entity ID, ACS URL, name ID format, attribute mapping, signature certificate, encryption settings. OIDC: client ID, client secret (or public mode), redirect URIs, allowed scopes, grant types. |
| Redirect URI | The URL where Hawiyati sends the authorization code after OIDC authentication. Exact matching enforced — wildcards not permitted. |
| Scope | OIDC authorization parameter controlling which claims are included in the ID token. Hawiyati supports standard scopes (openid, profile, email) and custom attribute mappings. |
Administration & Audit
| Term | Definition |
|---|---|
| Admin Console | The web-based administrative interface for platform operators (port 8095). Used to manage: users and groups, applications, authentication policies, risk settings, SCIM tokens, branding, and system settings. Access is role-gated via RBAC. |
| Account Portal | The self-service web application for end users (port 8096). Allows users to: view and edit profile, change password, manage MFA methods, review devices, list and revoke sessions, view activity log, and manage privacy consents. |
| Audit Event | A structured record of a significant platform action. Always includes: @timestamp, service, category, action, outcome, severity, actor, message. Stored in PostgreSQL; optionally forwarded to syslog/SIEM. |
| RBAC | Role-Based Access Control — the mechanism controlling what admin console users can see and do. Admin roles determine which console sections are accessible and what operations can be performed. |
| SCIM Token | An API bearer token used to authenticate SCIM provisioning clients. Issued from the admin console; plaintext shown once at generation (only hash stored). Can be revoked at any time. |
Deployment Terms
| Term | Definition |
|---|---|
Distribution (dist/) |
The runtime directory created by deploy.bat containing: compiled JARs for all services, configuration files, TLS certificates, log directories, and PID files. Services are started/stopped via dist\start.bat and dist\stop.bat. |
| gRPC | The inter-service communication protocol used between Hawiyati microservices. Services expose gRPC endpoints for internal calls (session lookup, SP registry reads, cache operations). Secured with mutual TLS in production. |
| Flyway | The database schema migration tool embedded in hawiyati-persistence. On startup, applies pending SQL migration scripts to bring the PostgreSQL schema up to date. V62 is the current head migration. |
| Redis / Valkey | The in-memory data store used for session state and rate-limiting counters only. Compatible with Redis 7+ and Valkey 7+. No persistent identity data is stored here — safe to flush and restart without data loss. |
| User Store | The source of truth for user identities. Types: LOCAL (Hawiyati database), LDAP (Active Directory bind + sync), SCIM (inbound provisioning), SQL (read-only bridge). Only one type is active at a time. |
🚀 Quick Start Guide
Get Hawiyati running locally for development, smoke testing, or evaluation in under an hour.
Prerequisites
- ✓Java 25 (OpenJDK or GraalVM) — earlier versions not supported; the stack uses Java 25 language features and virtual threads
- ✓Maven 3.8+ — for building the monorepo
- ✓PostgreSQL 16+ — create a database and user before running the stack; Flyway will apply schema migrations on first boot
- ✓Redis 7+ or Valkey 7+ — used for session state and rate limiting; no persistence required
- ✓8 GB RAM minimum — 16 GB recommended when running all services simultaneously
- ✓mkcert (optional but recommended) — for local HTTPS development certificates; the dev stack requires TLS for SAML/OIDC flows
- ✓Windows 11 or Linux (RHEL 8+ / Ubuntu 22+) — Windows is the primary development environment; Linux is the production target
quick-start.md source says Java 21+ but the production stack and all production tests target Java 25. Use Java 25 to avoid compatibility issues.
Installation Steps
Build the monorepo
Run a full Maven build to compile all modules and run unit tests. Expect 3–5 minutes on first run (dependency downloads).
mvn -B verify
For a faster compile-only check (no tests):
mvn -q -DskipTests compile
BUILD SUCCESS for all 16 modules.Set up local HTTPS (one-time)
Hawiyati requires HTTPS for SAML and OIDC flows. The TLS setup script uses mkcert to generate locally-trusted certificates for the development hostnames.
deployment\setup-tls.bat
Then add the development hostnames to your Windows hosts file (C:\Windows\System32\drivers\etc\hosts):
127.0.0.1 dev.hawiyati.org
127.0.0.1 admin.dev.hawiyati.org
127.0.0.1 account.dev.hawiyati.org
127.0.0.1 federation.dev.hawiyati.org
127.0.0.1 saml.spdemo.org
127.0.0.1 oidc.spdemo.org
dist/certs/; no browser certificate warnings for dev hostnames.Deploy and start the stack
The deploy script assembles the distribution package, then the start script launches all services.
deploy.bat
dist\start.bat
To start a single service (for development or debugging):
dist\start.bat hawiyati-admin
Check that all services are running:
dist\status.bat
Log in to the admin console
Open the admin console in your browser. Default credentials are set in the initial configuration file — change them immediately after first login.
https://admin.dev.hawiyati.org:8095
From the admin console you can: create users, register Service Providers, configure authentication policies, and view the audit log.
Register your first SP application
Navigate to Applications → Add Application. Choose SAML 2.0 or OIDC depending on your integration type. The SAML SP demo and OIDC SP demo applications are pre-registered in development mode for testing.
For SAML: provide the Entity ID and ACS URL from your SP's metadata. For OIDC: provide the redirect URI and select the scopes your application needs.
Create your first user and test a login
Navigate to Users → Add User. Enter the required fields (username, email, phone in E.164 format). A temporary password is set on save.
Then open the SAML SP demo in a separate browser tab and attempt a login:
https://saml.spdemo.org:8090
Or the OIDC SP demo:
https://oidc.spdemo.org:8092
Key Local URLs
| Component | URL | Port |
|---|---|---|
| Gateway / Entry point | https://dev.hawiyati.org:8080 | 8080 |
| IdP login / SAML ACS / OIDC | https://dev.hawiyati.org:8085 | 8085 |
| OIDC discovery / federation | https://federation.dev.hawiyati.org:8087 | 8087 |
| Admin console | https://admin.dev.hawiyati.org:8095 | 8095 |
| Account portal (self-service) | https://account.dev.hawiyati.org:8096 | 8096 |
| SAML SP demo | https://saml.spdemo.org:8090 | 8090 |
| OIDC SP demo | https://oidc.spdemo.org:8092 | 8092 |
| SCIM provisioning API | http://localhost:8098/scim/v2 | 8098 |
| SCIM test client | http://localhost:8099 | 8099 |
Common First-Run Gotchas
setup-tls.bat or don't add the dev hostnames to your hosts file, browsers will block the login redirect. mkcert must be run as administrator to install the local CA.
docs/SESSION_STATE.md for the exact checksum and repair command (flyway repair).
+213555123456). The admin console validates this — entering a local format will cause a validation error.
🗓️ Evaluation Journey
A structured timeline for organizations evaluating Hawiyati for production deployment. Each phase builds on the previous to give a realistic picture of the platform under realistic conditions.
Install and explore
- Complete the Quick Start installation
- Log in to the admin console and explore the dashboard
- Create 3–5 test users with different credential configurations
- Test a successful login via the SAML SP demo
- Test a successful login via the OIDC SP demo
- Review the audit log to see events from your test logins
Integrate a real SP application
- Register your first production SP (SAML or OIDC)
- Map attributes/claims to match your SP's requirements
- Enroll test users with TOTP MFA
- Configure a basic authentication policy (require MFA for all logins)
- Test SAML SP-initiated and IdP-initiated flows
- Test OIDC Authorization Code + PKCE flow end to end
Configure policies, test MFA, review audit
- Configure network zones (corporate IP range vs. external)
- Create a second authentication policy: require MFA outside the corporate zone
- Test FIDO2/passkey enrollment and login (requires a device with biometrics or a hardware key)
- Test the adaptive risk engine: log in from a new device and observe the MEDIUM/HIGH risk response
- Export audit logs to CSV for review by your compliance team
- Configure SCIM provisioning from a test HR system or LDAP simulator
Load test, harden, plan production
- Run load tests against the login endpoint (recommended: 100+ concurrent sessions)
- Review the security hardening guide and apply recommendations
- Test session revocation, account lock, and admin-forced password reset
- Plan the production deployment (infrastructure, HA, backup, secrets management)
- Complete the evaluation checklist below
- Contact the Hawiyati team for a production readiness review
Evaluation Checklist
- SAML 2.0 SP-initiated login succeeds with a configured real SP
- OIDC Authorization Code + PKCE flow succeeds end to end
- TOTP MFA enrollment and login tested with Google Authenticator or Authy
- FIDO2 passkey enrollment and login tested (if applicable)
- Authentication policy tested: password-only on corporate IP, MFA required on external IP
- Risk engine tested: new device triggers MEDIUM risk response
- Account lockout tested: failed login attempts trigger the lockout threshold
- Session revocation tested: admin revokes a session and the user is logged out
- SCIM provisioning tested: user created via SCIM appears in admin console
- Audit log exported to CSV and reviewed for completeness
- Load test completed: no errors under 100 concurrent login sessions
- Security hardening checklist reviewed and gaps documented
Production Readiness Gates
Before deploying Hawiyati to a production environment, verify all of the following:
- gRPC mutual TLS between internal services (currently plain gRPC in dev)
- Secrets management integration (HashiCorp Vault or equivalent; currently config-file secrets)
- Full automated deployment pipeline and backup automation
- Formal security assessment and penetration testing
- Login lockout and account recovery flows (functional, needs pen-test validation)
| Gate | Requirement | Status |
|---|---|---|
| TLS everywhere | All HTTP endpoints over HTTPS; gRPC mutual TLS between services | Partial |
| Secrets management | No secrets in config files; use Vault or equivalent | Roadmap |
| Backup automation | Automated daily PostgreSQL backup with tested restore procedure | Roadmap |
| Penetration testing | Formal vulnerability assessment by a qualified security team | Required |
| SSO federation | SAML 2.0 and OIDC tested end to end with at least one real SP | Available |
| MFA coverage | At least TOTP deployed; FIDO2 if high-assurance is required | Available |
| Audit logging | Structured audit log configured with retention policy and SIEM forwarding | Available |
| Admin RBAC | Admin operators have appropriate roles; no shared admin accounts | Available |
➡️ Continue Learning
Now that you have Hawiyati running, explore the full documentation to understand how to configure, integrate, and secure your deployment.