H· Hawiyati Documentation

Implementation Guide

This guide walks your team from initial planning through production go-live. A standard Hawiyati deployment takes 4–8 weeks depending on the number of SP integrations and the complexity of your identity infrastructure.

This guide walks your team from initial planning through production go-live. A standard Hawiyati deployment takes 4–8 weeks depending on the number of SP integrations and the complexity of your identity infrastructure.

Onboarding Overview

Organization onboarding from discovery through controlled operation
The implementation lifecycle includes explicit design, acceptance, production-readiness, and operational-review gates.

This guide walks your team from initial planning through production go-live. A standard Hawiyati deployment takes 4–8 weeks depending on the number of SP integrations and the complexity of your identity infrastructure.

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 the implementation lifecycle and configuration steps. For a conceptual walkthrough of each zone, see the Core Concepts guide.

Hawiyati is an on-premises platform — every deployment is owned and operated by the customer. Hawiyati provides the software, documentation, and support contracts. Your team owns the infrastructure, secrets, user data, and compliance obligations.

✓
Working Core

SSO (SAML 2.0 and OIDC), full MFA stack, adaptive access engine, LDAP/AD integration, SCIM 2.0, self-service account portal, and admin console are all production-capable. See the product overview for the complete maturity assessment.

⚠
Hardening Required Before Production

gRPC mutual TLS between internal services (currently plain gRPC in dev), secrets management integration (currently config-file secrets), and formal vulnerability assessment are required before processing production traffic.

Implementation Lifecycle

1
Plan — Weeks 1–2
Infrastructure sizing, network topology, TLS strategy, SP inventory, user store decision, MFA policy matrix, stakeholder alignment.
2
Install — Week 2–3
Provision infrastructure, install Java 25 / PostgreSQL 16 / Redis 7, deploy Hawiyati JARs, run Flyway migrations, configure TLS certificates and hostnames.
3
Configure — Week 3
Edit application.yml for database, Redis, email/SMS gateway, session TTL, password policy. Configure sp-registry.yml. Set up LDAP connector if required. Validate admin console login.
4
Integrate — Weeks 3–5
Register each SP application (SAML or OIDC), configure attribute mapping, set up SCIM provisioning if required, test end-to-end login flows per SP.
5
Test — Week 5–6
Execute the full acceptance checklist: SSO login, MFA enrollment, SLO, SCIM provision/deprovision, audit log capture, risk engine verification, performance baseline.
6
Go-Live — Week 7
DNS cutover, monitoring alerts active, on-call runbook published, rollback plan documented and rehearsed, SP owners notified.
7
Operate — Ongoing
Monitor dashboards, respond to alerts, manage user lifecycle, apply Hawiyati upgrades, conduct periodic security reviews, renew TLS certificates annually.

Stakeholders & Roles

A successful Hawiyati deployment requires coordination across four key roles. Identify a named owner for each before starting.

Role Primary Responsibilities Involvement Phases
IT Administrator Infrastructure provisioning, JAR deployment, system configuration, certificate management, backup, upgrades All phases
Security Officer MFA policy decisions, risk engine thresholds, audit log retention policy, vulnerability assessment sign-off Plan, Configure, Test, Go-Live
SP Developer / Application Owner SP metadata exchange, attribute mapping, integration testing, application-side session handling Integrate, Test
Compliance Officer KYC policy ownership, audit retention requirements, regulatory alignment, data residency confirmation Plan, Go-Live

Infrastructure Sizing

Resource Minimum (Pilot) Recommended (Production) Notes
CPU 4 vCPU 8 vCPU Argon2id hashing is CPU-intensive. More cores = faster parallel logins.
RAM 8 GB 16 GB Java heap + Redis + PostgreSQL shared_buffers. OS needs headroom too.
Disk 50 GB SSD 200 GB SSD Audit logs grow. Provision for 12-month retention before resizing.
OS Linux (RHEL 8+, Ubuntu 22+) RHEL 9 / Ubuntu 24 SELinux enforcing recommended on RHEL.
Java Java 25 (OpenJDK or GraalVM) Java 25 LTS Hawiyati is built and tested on Java 25. Java 21 is NOT supported.
PostgreSQL 16+ 16 HA (streaming replication) Two schemas: hawiyati_config (24 tables) and hawiyati_identity (13 tables).
Redis / Valkey Redis 7+ (single node) Valkey 8 cluster (3 nodes) Session state and rate-limiting only. Transient data — loss on restart is acceptable if TTLs are short.
⚠
Java Version

Hawiyati requires Java 25. The minimum listed in earlier documentation (Java 21) is outdated. Confirm java -version shows 25 before attempting startup.

High-Availability Architecture

For production deployments handling >1,000 active users or requiring 99.9%+ uptime:

PostgreSQL HA
Streaming replication with a hot standby. Use Patroni or pg_auto_failover for automatic promotion. Connection pooling via PgBouncer recommended for large deployments.
Redis Cluster
3-node Valkey cluster with Sentinel for automatic failover. Sessions have a configurable TTL; Redis loss causes re-authentication (graceful degradation).
Load Balancer
Place an L7 reverse proxy (nginx or HAProxy) in front of hawiyati-gateway. Sticky sessions not required — session state is in Redis and PostgreSQL.
Multiple Instances
hawiyati-http-server and hawiyati-admin can run as multiple instances behind a load balancer. Internal gRPC services (infra, cache, session) are currently single-instance.

Network Planning

Service Ports

Service Port Protocol Exposure Purpose
hawiyati-gateway 8080 HTTPS External (users + SPs) Primary entry point; routes to all internal services
hawiyati-http-server 8085 HTTPS Via gateway or direct IdP login flows, SAML ACS, OIDC endpoints
hawiyati-federation 8087 HTTPS Via gateway OIDC discovery, token issuance, SAML responses
hawiyati-admin 8095 HTTPS Internal only (admin network) Admin console — restrict to admin VLAN or VPN
hawiyati-account 8096 HTTPS Via gateway End-user self-service portal
hawiyati-scim 8098 HTTPS SP-facing (provisioning) SCIM 2.0 inbound provisioning API
Internal gRPC Various gRPC (plaintext in dev) Internal only (loopback or private network) Service-to-service communication (session, cache, infra)
⚠
Admin Console Access

Port 8095 (admin console) must never be exposed to the public internet. Restrict it to an admin VLAN or require VPN access. Compromise of the admin console = full platform compromise.

Firewall Rules (minimum required)

SourceDestinationPortReason
Internet / SP servershawiyati-gateway443 → 8080SSO login and SCIM provisioning
Admin workstationshawiyati-admin8095Admin console
Hawiyati servicesPostgreSQL5432Database access
Hawiyati servicesRedis6379Cache and session
hawiyati-http-serverEmail SMTP relay587OTP and notification email
hawiyati-http-serverSMS gateway (HTTP)443SMS OTP delivery

TLS & Hostname Planning

Development Environment

Use mkcert to create locally-trusted certificates. The dev profile ships with pre-configured hostnames — add them to your hosts file:

Required hosts file entries (development)
127.0.0.1 dev.hawiyati.org 127.0.0.1 saml.spdemo.org 127.0.0.1 oidc.spdemo.org 127.0.0.1 federation.dev.hawiyati.org
ServiceDev hostnamePort
IdP (HTTP server)dev.hawiyati.org8085
Gatewaydev.hawiyati.org8080
Admin consolelocalhost8095
SAML SP demosaml.spdemo.org8090
OIDC SP demooidc.spdemo.org8092
Federationfederation.dev.hawiyati.org8087

Production TLS Requirements

  • Use a publicly-trusted CA (Let's Encrypt, DigiCert, or your org's internal CA) for the IdP hostname.
  • The IdP certificate must be available to all SP applications — SPs embed or download the IdP's signing certificate from the SAML metadata or OIDC JWKS endpoint.
  • Certificate validity: minimum 12 months. Plan certificate rotation 30 days before expiry.
  • SAML signing key rotation requires updating the IdP metadata and coordinating re-configuration with all connected SPs.
  • Store private keys in a secrets manager (HashiCorp Vault or equivalent); never commit to version control.

SP Inventory

Before starting integration work, complete a SP inventory. Gather the following for each application that will integrate with Hawiyati:

Field SAML 2.0 OIDC Notes
Application name Required Required Friendly name shown in admin console
Entity ID / Client ID EntityID (URI, must be unique) client_id (string) Hawiyati assigns OIDC client_id; SP provides SAML EntityID
ACS URL / Redirect URI ACS URL (HTTPS required) redirect_uri list Where Hawiyati sends the authentication response
Logout URL SLO URL (optional) post_logout_redirect_uri Required for SLO chain to function
Required attributes/claims NameID + attribute statements Scopes + claims e.g., email, groups, assurance_level, employee_id
MFA requirement ALLOW / MFA_REQUIRED / MFA_STRONG / DENY Drives authentication policy assignment
Network zone Corporate / Remote / Any If different policies apply by network location
✓
Start Simple

Register SPs one at a time. Start with a low-criticality test application before touching production systems. Confirm the full login + logout cycle before moving to the next SP.

User Store Decision

Hawiyati supports three user store modes. Choose one before configuration — changing user store mode after deployment requires data migration.

Mode Description When to use Limitations
LOCAL Users managed entirely in Hawiyati's PostgreSQL database. Passwords hashed with Argon2id. Greenfield deployments with no existing directory. New user populations (e.g., citizen-facing portals). No sync with existing directory. Users managed only through Hawiyati admin console or SCIM.
LDAP / AD Hawiyati binds to your LDAP/Active Directory. Authentication is pass-through bind; user attributes synced on login. Organizations with existing AD/LDAP directory. Employees already in AD who need SSO. Password reset and lockout must be managed in AD. LDAP connectivity is a runtime dependency.
SQL (external) Hawiyati reads users from an external SQL table via a read-only bridge. Partial support. Existing applications with their own user database. Migration bridge while transitioning. Partial support only — not all features available. Verify capabilities before committing to this mode.
ℹ
SCIM and User Store

SCIM 2.0 inbound provisioning is available with the LOCAL user store. When using LDAP, provisioning is managed from AD; SCIM is not required but can co-exist for specific user populations.

MFA Policy Matrix

Before configuring authentication policies, define your MFA requirements per user population and application. Use this matrix as a starting point:

User Group Network Application Sensitivity Recommended Action
Employees Corporate network Low / Standard ALLOW (password only)
Employees Remote / VPN Low / Standard MFA_REQUIRED (TOTP or email OTP)
Employees Any High (finance, HR) MFA_STRONG (TOTP or FIDO2 required)
Administrators Any Admin console MFA_STRONG (FIDO2 recommended)
Contractors After hours Any DENY
External / Citizens Any Self-service portal MFA_REQUIRED (email OTP for low-friction)
High-assurance users (L3/L4) Any Regulated systems MFA_STRONG (FIDO2 or TOTP)
ℹ
Strictness Order

Authentication policies use first-match semantics. The risk engine may override with a stricter action. Final effective action follows strictness order: ALLOW < MFA_ANY < MFA_STRONG < DENY. The strictest wins.


application.yml Configuration Guide

Each Hawiyati service reads its configuration from application.yml (and profile-specific overlays). Key sections to configure before first startup:

Database Connection

application.yml — database section
spring: datasource: url: jdbc:postgresql://localhost:5432/hawiyati username: hawiyati_app password: ${HAWIYATI_DB_PASSWORD} # injected from environment hikari: maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 30000 jpa: hibernate: ddl-auto: validate # Flyway manages schema; never use create/update properties: hibernate.default_schema: hawiyati_identity

Redis Connection

application.yml — redis section
spring: data: redis: host: localhost port: 6379 password: ${HAWIYATI_REDIS_PASSWORD} timeout: 2000ms lettuce: pool: max-active: 16 max-idle: 8

Session Configuration

application.yml — session section
hawiyati: session: ttl: 28800 # 8 hours in seconds (default) idle-timeout: 3600 # session invalidated after 1h of inactivity max-concurrent: 5 # max simultaneous sessions per user (0 = unlimited) cookie-name: HWYT_SESSION cookie-secure: true cookie-same-site: Strict

Password Policy

application.yml — password policy
hawiyati: security: password: min-length: 12 require-uppercase: true require-lowercase: true require-digit: true require-special: false history-count: 8 # prevent reuse of last 8 passwords max-age-days: 90 # force reset after 90 days (0 = no expiry) lockout: max-attempts: 5 lockout-duration: 900 # 15 minutes in seconds reset-on-success: true

Email Gateway

application.yml — email
spring: mail: host: smtp.internal.org port: 587 username: [email protected] password: ${HAWIYATI_SMTP_PASSWORD} properties: mail.smtp.auth: true mail.smtp.starttls.enable: true hawiyati: mail: from: "Hawiyati Identity " otp-ttl: 300 # OTP valid for 5 minutes

SMS Gateway

application.yml — SMS gateway
hawiyati: sms: gateway-url: https://sms.internal.org/api/send api-key: ${HAWIYATI_SMS_API_KEY} sender-id: HAWIYATI otp-ttl: 300

Database Migrations (Flyway)

Hawiyati uses Flyway for schema management. Migrations run automatically on service startup. Never use spring.jpa.hibernate.ddl-auto=create or update — Flyway is the sole schema authority.

ℹ
Current Migration Head

As of this release, the current Flyway migration head is V62. A fresh install runs all migrations from V1 to V62. Upgrades run only the new migrations since the last installed version.

Two Database Schemas

SchemaTablesPurpose
hawiyati_config 24 tables SP registry, authentication policies, admin operators, LDAP configuration, system settings, risk engine rules, network zones
hawiyati_identity 13 tables Users, credentials, sessions, consent records, KYC profiles and sessions, FIDO2 credentials, audit events

Backup Before Migration

Always take a PostgreSQL backup before deploying a new Hawiyati version:

Pre-upgrade backup
pg_dump -U hawiyati_admin hawiyati \ --schema=hawiyati_config \ --schema=hawiyati_identity \ -F c -f hawiyati-backup-$(date +%Y%m%d).dump

SP Registry Configuration

Service Providers can be registered via the admin console (recommended) or by editing config/hawiyati-infra/sp-registry.yml for bulk registration.

SAML SP Entry

sp-registry.yml — SAML SP example
service-providers: - entityId: "https://erp.corp.org/saml" displayName: "Corporate ERP" protocol: SAML2 acsUrl: "https://erp.corp.org/saml/acs" sloUrl: "https://erp.corp.org/saml/logout" nameIdFormat: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" signingRequired: true encryptionRequired: false attributeMappings: email: "urn:oid:0.9.2342.19200300.100.1.3" groups: "hawiyati:groups" assurance_level: "hawiyati:assurance" authPolicyId: "corp-standard"

OIDC Client Entry

sp-registry.yml — OIDC client example
oidc-clients: - clientId: "mobile-app-prod" displayName: "Mobile Application" secret: "${MOBILE_APP_OIDC_SECRET}" # use env var or vault ref redirectUris: - "https://app.corp.org/auth/callback" - "hawiyati.mobile://auth" grantTypes: - authorization_code scopes: - openid - profile - email - groups pkceRequired: true tokenTtl: 3600 refreshTokenTtl: 86400 authPolicyId: "mobile-mfa"

Secrets Management

⚠
Never Commit Secrets

Passwords, API keys, signing keys, and OIDC client secrets must never be committed to version control. Use environment variables, HashiCorp Vault, or your organization's secrets manager.

Required Secrets

SecretDescriptionRotation
HAWIYATI_DB_PASSWORD PostgreSQL application user password Annually or on compromise
HAWIYATI_REDIS_PASSWORD Redis authentication password Annually
HAWIYATI_SMTP_PASSWORD Email relay authentication credential Per SMTP provider policy
HAWIYATI_SMS_API_KEY SMS gateway API key Per gateway provider policy
SAML signing key (PEM) RSA private key for signing SAML assertions Every 2 years (coordinate with SPs)
OIDC signing key (JWK) RSA private key for signing ID tokens (RS256) Annually (rolling rotation, old keys kept 24h for in-flight tokens)
Encryption key (AES-256) Symmetric key for encrypting TOTP secrets and sensitive fields at rest Planned — not yet externalized to vault

Environment Variable Injection

Startup — inject secrets via environment
export HAWIYATI_DB_PASSWORD="$(vault kv get -field=password secret/hawiyati/db)" export HAWIYATI_REDIS_PASSWORD="$(vault kv get -field=password secret/hawiyati/redis)" java -jar hawiyati-http-server.jar --spring.profiles.active=prod

Dev vs Production Profile Differences

SettingDev ProfileProduction Profile
TLS certificatesmkcert self-signedPublic CA or internal CA
gRPC transportPlaintextMutual TLS (when hardened)
SecretsConfig file (application-dev.yml)Environment variables / Vault
Logging levelDEBUGWARN / ERROR
CORSPermissiveStrict allowlist
Demo SPshawiyati-saml-sp-demo (8090), hawiyati-oidc-sp-demo (8092)Not deployed
Risk engine modeMONITOR (logs, does not block)ENFORCE
Admin consolelocalhost:8095 (HTTP)Internal hostname (HTTPS, restricted)

SP Integration Checklist

Repeat this checklist for each Service Provider being integrated:

  • ☐
    Identify protocol — confirm SAML 2.0 or OIDC based on SP capability
  • ☐
    Gather SP metadata — for SAML: EntityID, ACS URL, SLO URL, SP certificate; for OIDC: redirect URIs, required scopes
  • ☐
    Register in admin console — create application entry; supply required fields; save
  • ☐
    Exchange IdP metadata — for SAML: download IdP metadata from /saml/metadata and upload to SP; for OIDC: share discovery URL /.well-known/openid-configuration
  • ☐
    Configure attribute mapping — map Hawiyati user attributes to SP's expected attribute names or claims
  • ☐
    Assign authentication policy — select or create the correct policy (MFA level, network zone conditions)
  • ☐
    Test SP-initiated login — start login from the SP and verify end-to-end authentication
  • ☐
    Test logout — verify SLO chain invalidates both IdP and SP sessions
  • ☐
    Verify attribute values — confirm the SP receives correct attribute values (email, groups, assurance_level)
  • ☐
    Check audit log — confirm AUTH events appear in Hawiyati audit log for test logins

SCIM Provisioning Setup

Hawiyati's SCIM 2.0 inbound API allows external systems (HR platforms, enterprise directories) to provision and manage users automatically.

1
Generate SCIM Bearer Token
In the admin console → Settings → SCIM → Generate Token. Store the token securely — it is shown only once.
2
Configure the SCIM Client (SP Side)
In your HR or provisioning system, configure: SCIM base URL = https://idp.hawiyati.org/scim/v2, Authentication = Bearer token, Provisioning = Users and Groups.
3
Test User Provision
Provision a test user via SCIM POST /Users. Verify the user appears in Hawiyati admin console in MIGRATED_UNCLAIMED state (active=false, pendingApproval=true). A claim link is generated automatically.
4
Test User Deactivation
Send SCIM PATCH /Users/{id} with {"active": false}. Verify the user's Hawiyati account transitions to INACTIVE and all active sessions are terminated.
5
Verify Claim Flow (for MIGRATED_UNCLAIMED users)
Send the claim link to the provisioned test user. Verify they can complete the claim flow: verify identity → set password → enroll MFA → account becomes ACTIVE.
⚠
SCIM Extension Fields

Hawiyati's SCIM extension supports only: externalId, sourceInstanceId, pendingApproval. Credential fields, assurance level, and KYC data are explicitly excluded from the SCIM API surface by design.

LDAP / Active Directory Setup

Configure LDAP integration in application.yml under the hawiyati.ldap namespace. The bind account requires read access to the user subtree.

application.yml — LDAP section
hawiyati: ldap: enabled: true url: ldaps://dc01.corp.org:636 base-dn: "DC=corp,DC=org" bind-dn: "CN=hawiyati-svc,OU=ServiceAccounts,DC=corp,DC=org" bind-password: ${HAWIYATI_LDAP_PASSWORD} user-search-base: "OU=Users,DC=corp,DC=org" user-search-filter: "(&(objectClass=person)(sAMAccountName={0}))" group-search-base: "OU=Groups,DC=corp,DC=org" group-search-filter: "(member={0})" attribute-mapping: username: sAMAccountName email: mail display-name: displayName phone: telephoneNumber tls: trust-store: /etc/hawiyati/tls/ldap-truststore.jks trust-store-password: ${HAWIYATI_LDAP_TRUST_PASSWORD}
ℹ
LDAPS Recommended

Always use ldaps:// (port 636) in production. Plain ldap:// sends credentials over the network in clear text.


Responsibility Matrix

Hawiyati is an on-premises platform. The table below defines clear ownership boundaries between Hawiyati (the vendor) and the customer.

Area Hawiyati Provides Customer Responsible For
Platform Software JAR packages, configuration templates, Flyway migrations, release notes, upgrade guides Deploying and upgrading the software, applying patches promptly
Infrastructure Minimum requirements, sizing guidance, architecture reference Servers, VMs, containers, OS, PostgreSQL, Redis, network, load balancers
TLS Certificates Documentation, mkcert scripts for dev, certificate format requirements Obtaining, installing, monitoring, and renewing production TLS certificates
User Data Encryption at rest for sensitive fields (TOTP secrets, credentials), secure session handling Data residency compliance, backup, retention policy, GDPR/regulatory obligations
SP Integration SAML/OIDC/SCIM protocol implementation, integration documentation, SP demo environments SP metadata exchange, attribute mapping decisions, SP-side configuration, end-to-end testing
KYC Compliance KYC workflow engine, OCR/MRZ tooling, document capture UI, reviewer queue Lawful purpose, applicant notice, acceptable document policy, reviewer authority, appeal process, regulatory equivalence claims
Audit Retention Structured audit log with database storage, export to CSV/JSON, CEF/syslog output Audit retention period, archival, deletion schedule, regulatory reporting
Incident Response Support contract (tiered response times), security advisory notifications, CVE patching Incident response plan, on-call runbook, forensic investigation, breach notification obligations
Business Continuity High-availability architecture guidance, upgrade/rollback procedures DR plan, backup automation, failover testing, RTO/RPO targets

Testing & Acceptance

Acceptance Checklist

All items must pass before go-live approval. Run with a dedicated test user account and a test SP application separate from production systems.

Test CaseStepsExpected ResultPass?
SAML SSO Login Navigate to SAML SP → click login → authenticate at Hawiyati IdP User redirected back to SP, authenticated, correct attributes in assertion ☐
OIDC SSO Login Navigate to OIDC SP → click login → authenticate at Hawiyati IdP with PKCE ID token received, claims correct, SP session established ☐
TOTP Enrollment Login → security settings → enroll TOTP → scan QR with authenticator app → verify first code TOTP enrolled, subsequent logins require TOTP code ☐
FIDO2 Enrollment Login → security settings → add security key → follow browser prompts → verify FIDO2 credential stored, subsequent logins accept key tap ☐
Password Reset Click "Forgot password" → enter email → receive reset email → set new password → login Password reset completes, old password rejected, new password accepted ☐
Account Lockout Enter wrong password 5 times consecutively Account locked; lockout message shown; login blocked for configured duration (15 min default) ☐
SAML SLO Log in via SAML SP → logout from SP SLO request received by IdP, Hawiyati session terminated, user cannot reuse SAML session ☐
OIDC Logout Log in via OIDC SP → logout (RP-initiated) Hawiyati session invalidated, user redirected to post-logout URI ☐
SCIM User Provision POST /scim/v2/Users with required fields User created in MIGRATED_UNCLAIMED state; appears in admin console ☐
SCIM User Deactivate PATCH /scim/v2/Users/{id} with active=false User's account set to INACTIVE; active sessions terminated ☐
Audit Log Capture Perform test login → open admin console → Audit Logs → search for test user AUTH.LOGIN event appears with correct actor, outcome, timestamp ☐
Admin Console Access Navigate to localhost:8095 → login as admin → verify all sections accessible Admin console loads, users/groups/applications/policies/audit all visible ☐
Risk Engine (MONITOR mode) Login from unrecognized browser → check risk engine logs NEW_DEVICE signal logged; MONITOR mode does not block; risk score calculated ☐

Performance Baseline

Run a load test before go-live to establish your performance baseline. Minimum requirements:

Login Latency
p95 < 500ms for password authentication (no MFA). Argon2id hashing is the dominant cost — tune work factor to hit this target on your hardware.
Concurrent Users
100 concurrent authenticated sessions sustained without degradation. For higher concurrency, run multiple hawiyati-http-server instances behind a load balancer.
SCIM Throughput
Bulk provisioning of 10,000 users should complete within 30 minutes. SCIM has per-request rate limiting — tune hawiyati.scim.rate-limit if needed.
Database Connections
HikariCP pool of 20 connections handles up to ~200 concurrent requests. Monitor hikaricp.connections.pending in Prometheus metrics.

Go-Live Readiness

All of the following must be confirmed before cutting DNS to production:

  • ☐
    All acceptance tests pass — every item in the acceptance checklist marked as passed
  • ☐
    TLS certificates valid — production certificates from a trusted CA, validity period ≥12 months from go-live date
  • ☐
    Monitoring alerts configured — Prometheus alerts for service down, error rate spike, login failure rate spike, certificate expiry
  • ☐
    Backup verified — automated PostgreSQL backup running, last backup restored and verified on test environment
  • ☐
    Rollback plan documented — step-by-step procedure to revert DNS and restore previous identity infrastructure within RTO
  • ☐
    On-call runbook published — runbook covers: service down, user lockout, certificate expired, LDAP connectivity failure, high error rate
  • ☐
    SP owners notified — all SP application owners informed of go-live date, contact information for issues, expected maintenance windows
  • ☐
    Risk engine set to ENFORCE — switch from MONITOR to ENFORCE in production configuration
  • ☐
    Secrets rotated from dev values — confirm all production secrets are different from dev/test values
  • ☐
    Admin console access restricted — confirm port 8095 is not reachable from the public internet; VPN or admin VLAN required

DNS Cutover Sequence

1
Announce maintenance window
Notify users and SP owners of the planned cutover window. Recommend low-traffic period (e.g., Sunday 02:00–04:00).
2
Final backup
Take a final PostgreSQL backup and verify it immediately before the cutover.
3
Update DNS records
Point IdP hostname to Hawiyati gateway. Set TTL to 60s for rapid rollback if needed.
4
Verify from external network
Test login flow from outside the corporate network. Confirm TLS certificate is trusted. Check SAML metadata endpoint responds correctly.
5
Activate monitoring and go live
Enable all monitoring alerts. Announce cutover complete. Assign on-call person for the first 48 hours.

Post Go-Live Monitoring

The first 48 hours after go-live are the highest-risk period. A named on-call person should be monitoring actively.

First 48 Hours Checklist

  • ☐
    Login success rate — monitor login:success / login:failure ratio in Prometheus. Sudden spike in failures = likely misconfiguration or attack
  • ☐
    MFA fallout — watch for users unable to complete MFA. Have admin contact ready to assist with TOTP reset or backup code
  • ☐
    SP connectivity — verify each registered SP receives login events. No events from an expected SP = likely ACS URL or attribute mapping issue
  • ☐
    Audit log streaming — confirm events are flowing to SIEM if configured
  • ☐
    Database growth — monitor disk usage; confirm Flyway migration completed cleanly
  • ☐
    Redis memory — watch redis_memory_used_bytes; session accumulation at peak should be within capacity
  • ☐
    Error log review — review application ERROR-level logs daily for the first week; unknown errors need root cause analysis

First-Week Review

Day 2
Authentication report: review login volume, MFA enrollment rate, failed login count, top user-reported issues
Day 3
SP health check: confirm each integrated SP is seeing correct attribute values; validate logout chain for any SP that had issues
Day 5
Risk engine review: in MONITOR mode, review the risk signals logged; adjust thresholds before switching to ENFORCE if required
Day 7
One-week sign-off: review all open issues, close resolved items, schedule next review for 30 days
✓
Ongoing Operations

After the initial stabilization period, see the Operations Guide for routine maintenance procedures: certificate renewal, database vacuuming, Hawiyati upgrades, and backup verification schedules.

HawiyatiDocumentation · v2026 · Spring Boot 3.5