H· Hawiyati Documentation
Deployment

Deployment & Infrastructure

Hawiyati is a sovereign, on-premises identity platform. No runtime component makes outbound calls to external services after installation. All fonts, UI assets, geolocation data, and cryptographic material are bundled locally, enabling air-gapped operation.

Deployment

Hawiyati is a sovereign, on-premises identity platform. No runtime component makes outbound calls to external services after installation. All fonts, UI assets, geolocation data, and cryptographic material are bundled locally, enabling air-gapped operation.

Logical Hawiyati production deployment topology
External traffic crosses the controlled edge before reaching web, identity, federation, and KYC services and their protected dependencies.

1. Architecture Overview

Hawiyati is a sovereign, on-premises identity platform. No runtime component makes outbound calls to external services after installation. All fonts, UI assets, geolocation data, and cryptographic material are bundled locally, enabling air-gapped operation.

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

Design Principles

Sovereign by design. The platform operates correctly with zero internet connectivity after initial installation. Cryptographic operations, session management, and federation all run entirely on customer infrastructure.

Defense in depth. Identity data and configuration data live in separate PostgreSQL schemas and can be placed on separate physical servers. Browser-facing services are isolated from internal gRPC services. Authentication logic is separated from protocol encoding.

Stateless federation layer. The authentication state machine runs on the IdP. Sessions are stored in Redis with an opaque token issued to the browser. The SAML/OIDC federation layer is stateless — it reads the session, builds the assertion or token, and discards it.

Pluggable auth pipeline. The authenticator pipeline is a registry of named providers. Login flow steps are determined by the authentication policy bound to the target application.

Service Map

HTTP-Facing Services

ServicePortTypeRole
hawiyati-gateway 8080 HTTP Edge router — Spring Cloud Gateway. Routes inbound requests to downstream services by path prefix. No authentication enforced at the edge.
hawiyati-http-server 8085 HTTP IdP browser entry point. Hosts login, MFA, registration, and password-reset flows. Handles SAML SSO and ACS endpoints.
hawiyati-federation 8087 HTTP Federation orchestrator. Hosts all OIDC endpoints: /oidc/authorize, /oidc/token, /oidc/userinfo, /oidc/jwks, /.well-known/openid-configuration, /oidc/logout. Drives SAML response building over gRPC.
hawiyati-admin 8095 HTTP Administrator console (WebFlux + Thymeleaf) and REST API (/api/v1/**). Manages users, applications, policies, audit logs, and system settings. Role-gated — internal access only.
hawiyati-account 8096 HTTP End-user self-service portal (BFF pattern). Users manage profile, security factors, devices, sessions, activity log, and privacy settings.
hawiyati-scim 8098 HTTP SCIM 2.0 inbound provisioning API. External systems push user records using Bearer token authentication.
hawiyati-sp-scim-test 8099 Demo SCIM relying-party test console. Validates provisioning integration during setup. Not deployed in production.
hawiyati-saml-sp-demo 8090 Demo Demo SAML 2.0 SP (saml.spdemo.org:8090). End-to-end testing only — not deployed in production.
hawiyati-oidc-sp-demo 8092 Demo Demo OIDC relying party (oidc.spdemo.org:8092). End-to-end testing only — not deployed in production.

Internal gRPC Services

ServiceTypeRole
hawiyati-infra gRPC SP registry and configuration service. Loads SP registry from sp-registry.yml on first boot, persists to database. Other services call it to look up application configurations and signing keys.
hawiyati-session gRPC Session lifecycle manager. Creates, reads, and destroys sessions in Redis. Centralises session serialisation so all services share a consistent schema.
hawiyati-cache gRPC Redis cache facade. Provides consistent caching interface for rate-limit counters, OTP state, and SP config caching with pub/sub invalidation.

Shared Libraries

LibraryTypeRole
hawiyati-utils Library PKI helpers, RSA/SHA-256 utilities, common cryptographic primitives.
hawiyati-persistence Library JPA entities, Flyway migrations (V1–V62), and EncryptionService (AES-256-GCM). All services that read/write PostgreSQL embed this library.
hawiyati-audit Library Structured audit event writer: NDJSON to disk, CEF/syslog forwarder, Prometheus counters, OpenTelemetry traces. JPA sink writes to audit_events table.
hawiyati-saml-federation Library Custom SAML 2.0 implementation: AuthnRequest/Response encoding, metadata, RSA-SHA256 signing, full SLO chain.
hawiyati-openid-federation Library Custom OIDC implementation: authorization request parsing, PKCE validation, RS256 ID token building, claims mapping, token response.
hawiyati-directory Library AD/LDAP integration: pass-through bind authentication and periodic directory sync. Embedded in http-server (login) and admin (management).
ℹ️
On-prem sovereigntyAll services run on customer infrastructure. No telemetry, no cloud callbacks, no external key management dependencies. The platform functions correctly in a fully air-gapped network after initial deployment.

2. Infrastructure Requirements

Hawiyati is a standard Spring Boot application stack. Hardware requirements scale with concurrent user load and audit log retention period.

Minimum (Development / POC)

ComponentMinimum Spec
CPU4 cores (x86-64)
RAM8 GB
Disk50 GB SSD (application + DB + logs)
JavaJava 25 (OpenJDK or Oracle JDK)
PostgreSQL16.x or later
Redis7.x or later (Valkey 7.x compatible)
OSLinux (Ubuntu 22.04 LTS / RHEL 9) or Windows Server 2022
Network100 Mbps internal

Recommended (Production)

ComponentRecommended SpecNotes
CPU8+ coresMore cores benefit concurrent SAML/OIDC request processing
RAM16 GB+Allow headroom for audit log caching and JVM heap
Disk200 GB NVMe SSDAudit logs grow ~1 GB/100k events; plan retention period
PostgreSQLPrimary + warm standby replicaStreaming replication; automated failover via Patroni or pgBouncer
RedisSentinel (3 nodes) or ClusterSessions are transient; AOF persistence recommended for OTP durability
Load balancerHAProxy, nginx, or cloud LBTLS termination at LB; forward X-Forwarded-For
OSUbuntu 22.04 LTS / RHEL 9Long-term support for multi-year deployments
Network1 Gbps internal, 10 Gbps storagegRPC service mesh is high-throughput

Java Runtime

Hawiyati requires Java 25. The Maven build target is Java 25 class files. Running on an older JVM will fail at startup. Recommended distributions: Eclipse Temurin 25, Oracle JDK 25, GraalVM 25.

⚠️
Java 25 requiredThe build and runtime both target Java 25. Attempting to run on Java 21 or earlier will produce UnsupportedClassVersionError at startup. Use java -version to confirm before deploying.

3. PostgreSQL Configuration

PostgreSQL is the source of truth for all durable identity and configuration state. Two schemas partition the data by security domain.

Database Initialisation

-- Create database
CREATE DATABASE hawiyati
  ENCODING 'UTF8'
  LC_COLLATE 'en_US.UTF-8'
  LC_CTYPE 'en_US.UTF-8';

-- Create application user
CREATE USER hawiyati_app WITH PASSWORD 'changeme';
GRANT CONNECT ON DATABASE hawiyati TO hawiyati_app;

-- Schemas are created by Flyway on first startup:
--   hawiyati_config   (IdP configuration — 24 tables)
--   hawiyati_identity (end-user directory — 13 tables)
GRANT USAGE, CREATE ON SCHEMA public TO hawiyati_app;
✅
Flyway auto-migrates on startupHawiyati runs Flyway migrations automatically at startup. The current migration head is V62. Migrations are additive and idempotent — running them twice is safe. Never modify migration files after they have been applied.

hawiyati_config Schema (24 tables)

Holds everything administrators configure: SP registrations, authentication policies, network zones, admin operator accounts, LDAP configurations, SCIM tokens, system settings, audit events, and attribute definitions.

CategoryTables
Application registry service_providers, sp_saml_config, sp_saml_allowed_attributes, sp_oidc_config, sp_oidc_redirect_uris, sp_oidc_logout_uris, sp_oidc_scopes, sp_oidc_grant_types, sp_oidc_response_types, 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, identity_db_connection, scim_tokens, attribute_definition, registration_policy, audit_events

hawiyati_identity Schema (13 tables)

Holds all end-user data: user accounts, credentials, group memberships, session history, MFA devices, consent records, and risk signals.

CategoryTables
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, user_notification_prefs, invitation_tokens, user_kyc_submissions

Connection Pool Sizing

Each Hawiyati service that connects to PostgreSQL uses HikariCP. Recommended pool sizes:

ServiceRecommended max-pool-size
hawiyati-http-server20
hawiyati-admin10
hawiyati-federation10
hawiyati-scim10
hawiyati-infra5

Total max connections required: ~55 + PostgreSQL overhead. Size max_connections in postgresql.conf accordingly (recommend 200).

Encrypted Columns

Sensitive fields are encrypted at rest using AES-256-GCM via hawiyati-persistence's EncryptionService. Encrypted fields include: TOTP secrets, recovery codes (Argon2id hashed), FIDO2 credential data, and session tokens. The encryption key is configured via hawiyati.security.encryption-key and must be at least 256 bits.

Backup Strategy

Recommended backup configuration:

  • Continuous WAL archiving using archive_command to durable storage (NFS, S3-compatible, or tape)
  • Daily full base backup using pg_basebackup or Barman
  • Point-in-time recovery (PITR) target: 15-minute RPO
  • Retention: 30 days of WAL, 7 daily base backups
  • Test restores monthly on a separate server — never assume backups work until tested

4. Redis Configuration

Redis (or Valkey 7.x) is used for transient data only. No durable identity or configuration state is stored in Redis — all of that lives in PostgreSQL. Redis loss is recoverable: active sessions expire naturally, OTP codes become invalid, and SP config caches are rebuilt on next request.

Key Namespaces

Key PatternContentTTL
session:{sessionId}Serialised IdP session (Jackson JSON)Configurable (default 30 min)
otp:{type}:{userId}OTP code hash + attempt count5 minutes (email/SMS OTP)
rl:{key}Rate limit counter (login attempts)Rolling window (1–15 min)
sp:{entityId}SP configuration cacheNo TTL — invalidated via pub/sub
device:{userId}Known device set (hashed fingerprints)400 days

SP Config Cache Invalidation

When an administrator modifies an SP's configuration via the admin console, Hawiyati publishes an invalidation message to the hawiyati:sp:invalidate Redis pub/sub channel. All running services subscribed to this channel evict the affected SP's entry from their local cache within approximately 10 seconds. This ensures configuration changes propagate without requiring service restarts.

Production Redis Configuration

# /etc/redis/redis.conf (production)
bind 127.0.0.1 ::1
requirepass YourStrongRedisPassword
maxmemory 2gb
maxmemory-policy allkeys-lru

# Persistence — RDB + AOF for durability
save 900 1
save 300 10
save 60 10000
appendonly yes
appendfsync everysec

# TLS (recommended for production)
tls-port 6380
tls-cert-file /etc/ssl/hawiyati/redis.crt
tls-key-file /etc/ssl/hawiyati/redis.key
tls-ca-cert-file /etc/ssl/hawiyati/ca.crt

High Availability — Redis Sentinel

# /etc/redis/sentinel.conf
sentinel monitor hawiyati-redis 127.0.0.1 6379 2
sentinel auth-pass hawiyati-redis YourStrongRedisPassword
sentinel down-after-milliseconds hawiyati-redis 5000
sentinel failover-timeout hawiyati-redis 60000
sentinel parallel-syncs hawiyati-redis 1
⚠️
Do not persist identity state in RedisRedis is intentionally transient. Do not configure Hawiyati to store user records, credentials, or configuration in Redis. If Redis is lost and restarted clean, the only impact is active sessions expiring — users must log in again.

5. Network Topology

Hawiyati uses a layered trust-zone model. Only two HTTP ports (8080 and 8085) need to be reachable from the internet. The admin console, SCIM API, and all gRPC services are internal-only.

External Zone — Internet / User Browsers / SP Systems
User Browser
SAML SP
OIDC Relying Party
SCIM Client (HR / IGA)
↓ HTTPS/TLS
DMZ — Reverse Proxy / Load Balancer (TLS Termination + WAF)

nginx / HAProxy / cloud LB — terminates TLS, validates certs, forwards X-Forwarded-For. WAF rules recommended for SAML POST endpoints.

↓ HTTP (internal)
Application Zone — Hawiyati HTTP Services
hawiyati-gateway:8080
hawiyati-http-server:8085
hawiyati-federation:8087
hawiyati-admin:8095 🔒
hawiyati-account:8096 🔒
hawiyati-scim:8098 🔒

🔒 = internal/VPN only — not exposed via gateway or public LB

↓ gRPC (plaintext — mTLS planned Phase 4)
Internal gRPC Zone — Service Mesh
hawiyati-infragRPC
hawiyati-sessiongRPC
hawiyati-cachegRPC
↓ JDBC / TCP
Data Zone — Persistence
PostgreSQL:5432
Redis / Valkey:6379

Firewall Rules Summary

PortServiceAccessNotes
8080hawiyati-gatewayPublic (via LB)Routes to 8085/8087
8085hawiyati-http-serverPublic (via LB) or DirectMain IdP login and SAML endpoints
8087hawiyati-federationPublic (via LB)OIDC endpoints
8095hawiyati-adminInternal / VPN onlyAdmin console — never expose publicly
8096hawiyati-accountInternal / optional publicSelf-service portal
8098hawiyati-scimInternal / SP network onlySCIM provisioning — restrict to SP source IPs
8099hawiyati-sp-scim-testDev / internal onlyNot deployed in production
5432PostgreSQLInternal onlyFirewall from all external traffic
6379RedisInternal onlyFirewall from all external traffic
🚫
Never expose port 8095 (admin) publiclyThe admin console provides full control over user accounts, policies, and SP configurations. It must only be accessible from a trusted internal network or via VPN. Exposing it to the internet is a critical security misconfiguration.

6. TLS & Certificate Management

All external-facing endpoints must be served over HTTPS. Hawiyati uses TLS for browser-to-server connections and recommends TLS for gRPC service-to-service channels (planned for Phase 4 with mutual TLS).

Production Certificate Requirements

EndpointCertificate TypeSubject / SAN
hawiyati-gateway (8080) / http-server (8085)Public CA (DigiCert, Let's Encrypt, etc.)idp.hawiyati.yourorg.com
hawiyati-federation (8087)Public CAfederation.hawiyati.yourorg.com
hawiyati-admin (8095)Internal CA or self-signedadmin.hawiyati.internal
hawiyati-scim (8098)Public CA or Internal CAscim.hawiyati.yourorg.com
gRPC channels (Phase 4)Internal CA (mTLS)Service-to-service

Development Certificates (mkcert)

For development use mkcert to generate locally-trusted certificates. The development hostname map:

HostnamePortService
dev.hawiyati.org8085IdP (http-server)
localhost8095Admin console
federation.dev.hawiyati.org8087Federation / OIDC
saml.spdemo.org8090SAML SP Demo
oidc.spdemo.org8092OIDC SP Demo
# Install mkcert, then:
mkcert -install
mkcert dev.hawiyati.org localhost federation.dev.hawiyati.org \
       saml.spdemo.org oidc.spdemo.org

SAML Signing Key Rotation

The SAML IdP signing key is used to sign all assertions. Rotating it requires coordination with all SPs:

  1. Generate a new RSA-2048 or RSA-4096 key pair
  2. Add the new certificate to the IdP metadata (alongside the old one) — SPs must re-import metadata
  3. Wait for all SPs to update their trusted certificate list (rolling window: 48–72 hours)
  4. Switch the active signing key to the new one in admin console → Settings → SAML Signing
  5. Remove the old certificate from metadata after all SPs have confirmed acceptance of new signatures
⚠️
SAML signature failure = SSO outageIf SPs have not updated their trusted certificate before the old key is removed, every SSO attempt will fail with Signature validation failed. Always maintain the old certificate in metadata for the full grace period before removing it.

JVM Truststore

When Hawiyati makes outbound HTTPS calls (email gateways, SMS providers, LDAP/LDAPS), the target certificates must be trusted by the JVM. Add custom CA certificates:

# Add custom CA to the JVM truststore
keytool -importcert \
  -alias internal-ca \
  -file /etc/ssl/hawiyati/internal-ca.crt \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit -noprompt

7. Configuration Reference

Hawiyati is configured via Spring Boot's standard application.yml file hierarchy. Environment variables override any YAML value using the standard Spring property naming convention (spring.datasource.url → SPRING_DATASOURCE_URL).

Key Configuration Properties

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/hawiyati?currentSchema=hawiyati_config
    username: hawiyati_app
    password: ${DB_PASSWORD}           # inject from env or vault
    hikari:
      maximum-pool-size: 20
      connection-timeout: 30000

  redis:
    host: localhost
    port: 6379
    password: ${REDIS_PASSWORD}
    ssl.enabled: true                  # recommended for production

hawiyati:
  security:
    encryption-key: ${ENCRYPTION_KEY}  # 32-byte hex — keep in vault
    signing-key-alias: idp-signing
    signing-key-store: /etc/hawiyati/keystore.p12
    signing-key-store-password: ${KEYSTORE_PASSWORD}

  session:
    ttl: 1800                          # seconds (30 min default)
    cookie-name: HAWIYATI_SESSION
    cookie-secure: true
    cookie-same-site: Strict

  oidc:
    issuer-uri: https://idp.hawiyati.yourorg.com

  saml:
    idp-entity-id: https://idp.hawiyati.yourorg.com/saml/metadata
    signing-key-alias: idp-signing

  password:
    min-length: 12
    require-uppercase: true
    require-digit: true
    require-special: true
    history-count: 10                  # reject last N passwords

  lockout:
    max-attempts: 5
    lockout-duration: 900              # seconds (15 min)

  risk:
    mode: MONITOR                      # OFF | MONITOR | ENFORCE
    new-device-weight: 30
    velocity-weight: 40
    geoip-weight: 20
    ip-reputation-weight: 10

logging:
  level:
    hawiyati: INFO
    org.springframework.security: WARN

Secrets Management

Never store secrets in YAML files committed to version control. Use one of:

  • Environment variables: inject at container/process startup via systemd EnvironmentFile or Docker secrets
  • HashiCorp Vault: use Spring Vault integration (spring-cloud-vault) to pull secrets at startup
  • Cloud KMS: wrap encryption keys in a cloud KMS envelope (supported via custom EncryptionService implementation)
  • Kubernetes Secrets: mount as environment variables or projected volumes in pod spec
⚠️
Critical secretsProtect these with particular care: ENCRYPTION_KEY (decrypts all sensitive DB columns), KEYSTORE_PASSWORD (grants access to the SAML/OIDC signing key), DB_PASSWORD, REDIS_PASSWORD. Loss of the encryption key means all encrypted data becomes unreadable.
SCIM provisioning and reconciliation lifecycle
Configure stable source identifiers, lifecycle operations, audit capture, and scheduled reconciliation together.

8. SCIM Provisioning Setup

Hawiyati implements SCIM 2.0 as an inbound provisioning server. External identity governance, HR systems, or Active Directory sync tools push user records to Hawiyati's SCIM endpoint.

Enabling SCIM

The SCIM module (hawiyati-scim) is deployed as a separate service on port 8098. Ensure it is started alongside the core services.

Generating a SCIM Bearer Token

  1. Log in to the admin console (https://localhost:8095)
  2. Navigate to Settings → SCIM Provisioning
  3. Click Generate Token — copy the token immediately (shown only once)
  4. Optionally set an expiry date for the token

SP SCIM Client Configuration

# SCIM client settings (SP side)
scim.base-url=https://scim.hawiyati.yourorg.com/scim/v2
scim.auth-header=Authorization: Bearer {your-token}
scim.content-type=application/scim+json

Verify Connectivity

curl -s \
  -H "Authorization: Bearer {your-token}" \
  https://scim.hawiyati.yourorg.com/scim/v2/ServiceProviderConfig \
  | python3 -m json.tool

Expected response: 200 OK with SCIM server capability document listing supported operations.

SCIM Provisioning Flow

When a SCIM client creates a user via POST /scim/v2/Users:

  1. Hawiyati creates the user account in hawiyati_identity.users
  2. Account starts in MIGRATED_UNCLAIMED state (active=false, pendingApproval=true)
  3. A claim token (256-bit random, HMAC-SHA256 stored, 15-min TTL) is generated
  4. Admin or notification system sends claim link to the user
  5. User follows the link, verifies identity, sets password/MFA → account becomes ACTIVE

SCIM Test Simulator

The hawiyati-sp-scim-test service (port 8099) provides a web UI to test SCIM operations against your Hawiyati deployment during integration. It is development-only and must not be deployed in production.

ℹ️
Supported SCIM extension fieldsOnly externalId, sourceInstanceId, and pendingApproval are supported in the SCIM extension schema. Credential fields and assurance level cannot be set via SCIM.

9. AD/LDAP Integration

Hawiyati's LDAP connector (the hawiyati-directory library) supports pass-through bind authentication and periodic directory sync. Users can be authenticated against an AD or LDAP server without storing passwords in Hawiyati's local database.

Configuration

hawiyati:
  ldap:
    enabled: true
    url: ldaps://dc.corp.example.com:636
    bind-dn: CN=hawiyati-svc,OU=ServiceAccounts,DC=corp,DC=example,DC=com
    bind-password: ${LDAP_BIND_PASSWORD}
    user-search-base: OU=Users,DC=corp,DC=example,DC=com
    user-search-filter: (sAMAccountName={0})
    group-search-base: OU=Groups,DC=corp,DC=example,DC=com
    group-search-filter: (member={0})
    sync:
      enabled: true
      cron: "0 0 2 * * *"             # daily at 02:00
      page-size: 1000

Attribute Mapping

LDAP AttributeHawiyati FieldNotes
sAMAccountNameusernameUsed as login identifier
mailemailMust be unique
telephoneNumberphoneE.164 format expected
displayNamedisplayNameOptional
memberOfGroup membershipSynced to user_group_members
userAccountControlactiveDisabled AD accounts → INACTIVE in Hawiyati

Authentication Modes

Pass-through bind: When a user authenticates, Hawiyati binds to the LDAP server using the user's credentials. No password is stored in Hawiyati. If LDAP is unreachable, authentication fails (no fallback by default).

Local fallback: Configure hawiyati.ldap.fallback-to-local: true to allow locally-stored Argon2id passwords when LDAP is unavailable. Only recommended for resilience in controlled environments.

Testing the LDAP Connection

Admin console → Settings → Directory → LDAP → Test Connection performs a bind test and shows the number of users/groups found with the configured search base and filter.

10. Build & Start

Hawiyati is a Maven monorepo. All modules are built together, then services are started in the correct dependency order.

Build

# Full build (all modules, skip integration tests)
mvn clean install -DskipITs

# Build with integration tests (requires running PostgreSQL + Redis)
mvn clean install

# Build a single module
mvn clean install -pl hawiyati-http-server -am

Run Tests for a Single Module

# Unit tests only
mvn test -pl hawiyati-http-server

# Integration tests for SAML SP Demo
mvn test -pl hawiyati-saml-sp-demo

# OIDC SP Demo
mvn test -pl hawiyati-oidc-sp-demo

Deploy & Start (Windows)

# Deploy configuration and JARs to dist/
.\deploy.bat

# Start all services
.\start.bat

Startup Order

Services must start in dependency order. The recommended sequence:

  1. PostgreSQL (Flyway migrations run on first service startup)
  2. Redis
  3. hawiyati-infra (gRPC SP registry — must be up before http-server)
  4. hawiyati-session (gRPC — must be up before http-server)
  5. hawiyati-cache (gRPC)
  6. hawiyati-persistence library — embedded, starts with each service
  7. hawiyati-http-server (depends on infra + session + cache gRPC)
  8. hawiyati-federation (depends on infra + session gRPC)
  9. hawiyati-gateway
  10. hawiyati-admin
  11. hawiyati-scim

Health Check Endpoints

ServiceHealth EndpointExpected Response
hawiyati-http-serverGET :8085/actuator/health{"status":"UP"}
hawiyati-federationGET :8087/actuator/health{"status":"UP"}
hawiyati-adminGET :8095/actuator/health{"status":"UP"}
hawiyati-scimGET :8098/actuator/health{"status":"UP"}
hawiyati-gatewayGET :8080/actuator/health{"status":"UP"}

Docker Compose (Development Stack)

version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: hawiyati
      POSTGRES_USER: hawiyati_app
      POSTGRES_PASSWORD: dev_password
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass dev_redis_pass
    ports:
      - "6379:6379"

volumes:
  pgdata:
✅
First startupOn first startup, Hawiyati runs all Flyway migrations (V1–V62) and seeds the initial admin operator account. Check the startup logs for Successfully applied N migration(s) and Admin account created. Default admin credentials are in dist/config/admin-bootstrap.yml — change them immediately.

Monitoring & Observability

Each service exposes Prometheus metrics at /actuator/prometheus and OpenTelemetry traces via the OTel Java agent. Key metrics to monitor:

  • hawiyati_auth_attempts_total — login attempt rate (label: outcome=success/failure)
  • hawiyati_saml_requests_total — SAML SSO request rate
  • hawiyati_oidc_token_requests_total — OIDC token exchange rate
  • hawiyati_session_active — active session count
  • spring_datasource_connections_active — DB connection pool utilisation
  • redis_connected_clients — Redis client count

See Operations Guide for full monitoring setup, alerting thresholds, and Grafana dashboard configuration.

HawiyatiDocumentation · v2026 · Spring Boot 3.5