H· Hawiyati Documentation

Migration Guide

This guide covers migrating user populations and service providers to Hawiyati — from pre-migration planning through bulk import, account claim rollout, database migration sequencing, phased delivery, and production cutover. It applies to both greenfield deployments and brownfield migrations running Hawiyati alongside an existing IdP.

This guide covers migrating user populations and service providers to Hawiyati — from pre-migration planning through bulk import, account claim rollout, database migration sequencing, phased delivery, and production cutover. It applies to both greenfield deployments and brownfield migrations running Hawiyati alongside an existing IdP.

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 migration strategies, bulk import, account claim rollout, and database sequencing. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.

This guide covers migrating user populations and service providers to Hawiyati — from pre-migration planning through bulk import, account claim rollout, database migration sequencing, phased delivery, and production cutover. It applies to both greenfield deployments and brownfield migrations running Hawiyati alongside an existing IdP.

Migration Strategy Overview

Governed identity migration from discovery through decommissioning
Every stage has reconciliation and acceptance gates before a pilot or production cutover proceeds.

Hawiyati supports three primary migration scenarios. Choose based on your existing identity infrastructure, risk tolerance, and timeline.

Why Migrate to Hawiyati

On-Premises Sovereignty NIST SP 800-63A-4 Alignment Custom SAML 2.0 + OIDC Stack Built-in KYC Workflows Adaptive Risk Engine

Key drivers for migrating identity infrastructure to Hawiyati:

  • Data sovereignty: All user data and credentials remain on your infrastructure. No cloud routing of authentication requests.
  • Regulatory compliance: Assurance levels L0–L4 aligned with NIST SP 800-63A-4. Built-in KYC workflows for government and regulated industries.
  • Consolidation: Replace fragmented LDAP directories, legacy RADIUS servers, and ad-hoc SSO integrations with a single, auditable identity platform.
  • Modern protocols: Full SAML 2.0 and OIDC (Authorization Code + PKCE) support. SCIM 2.0 inbound provisioning. FIDO2/WebAuthn passkeys.

Migration Types

Type Description Risk Recommended When
Greenfield New Hawiyati deployment with no existing IdP. Users register fresh or are imported with no prior SSO. Low New application launches, startup environments, or when no existing user base needs migration.
Brownfield — Parallel Run Hawiyati deployed alongside existing IdP. SPs migrated one at a time. Users claimed gradually. Medium Production systems with active users. Most common migration pattern.
Full Cutover Hard cutover: all SPs and users switched to Hawiyati on a fixed date. Old IdP decommissioned immediately. High Small user populations, legacy IdP decommission deadline, or when a parallel run is not operationally feasible.
✓
Recommended Approach

The Brownfield Parallel Run approach is strongly recommended for production environments. It allows SP-by-SP migration, gradual user claim, independent rollback per SP, and monitoring before full cutover. The additional operational overhead is offset by significantly reduced risk.

Phased Rollout Benefits

  • Parallel run: Old and new IdPs operate simultaneously. Traffic can be routed back to the old IdP per SP if issues arise.
  • Gradual user claim: Users are imported in MIGRATED_UNCLAIMED state and claim their accounts on their own timeline. No forced password reset for all users on day one.
  • Rollback window: Each SP has an independent rollback point until its claim rate reaches the threshold (typically 80%+).
  • Risk isolation: A problem with one SP's migration does not affect others.

Pre-Migration Planning

User Inventory

Before importing users, establish a complete inventory of your existing user population:

Inventory Item Questions to Answer Impact on Migration
Total user count How many users need to be imported? Batch sizing, claim notification volume
User source systems LDAP, Active Directory, local DB, legacy IdP, Excel/CSV? Determines extraction method and attribute mapping
Credential availability Can password hashes be exported? Are they bcrypt, PBKDF2, Argon2id? If hashes unavailable, all users must set new passwords during claim
Active SSO users Which users actively use SSO vs just have accounts? Prioritize active users for claim notifications
Contact info completeness Do all users have email and/or E.164 phone numbers? Required for claim notification delivery
Group memberships What groups exist? Which are used in authorization policies? Groups must be created in Hawiyati before user import

SP Inventory

List all service providers to migrate and determine their integration requirements:

Field Collect For Each SP
Application name Human-readable name for the admin console
Current protocol SAML 2.0, LDAP bind, Kerberos, basic auth, custom?
Target protocol SAML 2.0 or OIDC in Hawiyati
SP metadata / config EntityID, ACS URL (SAML) or redirect_uri (OIDC)
Required attributes Which user attributes does the SP expect? NameID format?
Required assurance level Does the SP require MFA, KYC verification, or a minimum L-level?
SLO support Does the SP support Single Logout? Required for full SSO lifecycle.
Migration priority Which SPs migrate first? (low-risk internal tools → production apps)

Data Mapping

Map legacy user attributes to Hawiyati schema fields before import:

Legacy Field Hawiyati Field Notes
username / sAMAccountName / uid users.username Must be unique. Lowercase recommended.
mail / email users.email Required if SMS not available
mobile / telephoneNumber users.phone_number Must be E.164 format (+213XXXXXXXXX)
givenName / sn users.given_name, users.family_name Used in notification templates
Password hash credentials.hashed_value Only Argon2id hashes accepted. Other algorithms require re-set during claim.
memberOf / groups group_memberships Groups must exist in Hawiyati before import
employeeID / objectGUID users.external_id Preserves link to source system; also settable via SCIM externalId

Bulk Import

Hawiyati supports importing existing user populations via CSV file or the Admin API batch endpoint. Imported users are placed in the MIGRATED_UNCLAIMED state and cannot log in until they claim their account.

CSV Import Format

users-import.csv — required headers
username,email,phone_number,given_name,family_name,external_id,groups alice.martin,[email protected],+213551234567,Alice,Martin,EMP-001,staff;managers bob.hassan,[email protected],+213661234568,Bob,Hassan,EMP-002,staff
ℹ
Optional Fields

Password hashes (argon2id_hash) may be included if available from the source system. Only Argon2id hashes are accepted — bcrypt, PBKDF2, or MD5 hashes cannot be imported and users with those credentials must set new passwords during the claim flow. If argon2id_hash is omitted, the user must set a new password during claim.

Batch Import API

POST /admin/users/batch-import
{ "users": [ { "username": "alice.martin", "email": "[email protected]", "phone_number": "+213551234567", "given_name": "Alice", "family_name": "Martin", "external_id": "EMP-001", "groups": ["staff", "managers"] } ], "options": { "send_claim_notifications": false, "deduplication": "skip_existing" } }

Import Validation Rules

  • At least one of email or phone_number is required per user
  • Phone numbers must be E.164 format (e.g., +213551234567)
  • Email addresses must be syntactically valid and unique within the tenant
  • Usernames must be unique and contain only letters, digits, dots, underscores, hyphens
  • Group names must already exist in Hawiyati before import (pre-create groups first)
  • Duplicate usernames: configurable behaviour — skip_existing (default), fail_on_duplicate, or update_existing
⚠
Test Against a Copy First

Always run a dry-run import against a staging environment using a representative sample (500–1000 users) before importing your full population. Verify data mapping, group assignment, and notification delivery before proceeding.

MIGRATED_UNCLAIMED State

Imported users are placed in the MIGRATED_UNCLAIMED state immediately after bulk import. This is a deliberate holding state that prevents login until the user has verified their identity and set credentials.

Database Representation

The state is stored as two boolean flags on the users table. There is no separate status column — the state is computed from the combination:

State active pending_approval Can Login?
ACTIVE true false Yes
ACTIVE_LIMITED true true Restricted (awaiting approval)
INACTIVE false false No
MIGRATED_UNCLAIMED false true No — must claim account first
⚠
ACTIVE_LIMITED Is Not a Database Column

ACTIVE_LIMITED is a computed presentation state derived from active=true, pending_approval=true. It does NOT exist as a value in any database column. Code and queries must check both flags, never a hypothetical status enum value.

What MIGRATED_UNCLAIMED Means

  • The user record exists in Hawiyati with imported profile data
  • Login attempts are rejected with a prompt to claim the account
  • A claim token is generated and can be dispatched via email or SMS
  • The account transitions to ACTIVE only after successful claim (identity verification + credential enrollment)

Monitoring Unclaimed Accounts

Track claim progress in the Admin Console under Users → filter by Status = MIGRATED_UNCLAIMED. The bulk import report also shows: total imported, claim token dispatched, claimed, failed dispatch.

Account Claim Rollout

Secure migrated-account claim flow
A single-use invitation, identity evidence, collision handling, and a fresh login protect account binding.

After bulk import, users must claim their accounts to activate them. The claim rollout involves generating claim tokens, dispatching notifications, and monitoring claim rates.

Claim Flow

1
Claim Token Generated
System generates a 256-bit random claim token. HMAC-SHA256 stored in the database. Token TTL is 15 minutes from the moment the user follows the link (not from generation).
2
Notification Dispatched
Claim link sent to user's email or phone via the configured notification gateway. Link contains the claim token as a URL parameter. Dispatched via the notification outbox (SKIP LOCKED, exponential backoff 30s/2m/8m/32m/128m).
3
User Follows Claim Link
User clicks the link. Hawiyati validates the token (HMAC-SHA256 match, not expired, not yet used). Token is single-use — validated and marked consumed atomically.
4
Identity Verification
User verifies their identity: confirms name, enters a one-time code sent to their email/phone, or completes a KYC step if required by your policy.
5
Credential Enrollment
User sets a new password (if no Argon2id hash was imported) and optionally enrolls a second factor (TOTP, FIDO2, or email/SMS OTP). Existing Argon2id hash is retained if present.
6
Account Activated — State → ACTIVE
Database updated: active = true, pending_approval = false. Audit event ACCOUNT_CLAIMED recorded. User can now log in through any registered SP.

Claim Token Mechanics

Claim tokens are the security mechanism that enables safe account claim without requiring admin intervention per user.

Token Properties

PropertyValue
Entropy256-bit cryptographically random (SecureRandom)
StorageHMAC-SHA256 of raw token stored in DB — raw token never persisted
TTL15 minutes from the moment the link is activated
Single-useYes — token consumed atomically on first valid use; replaying returns 410 Gone
ScopeBound to a single user_id — cannot be used to claim a different account
DeliveryURL parameter in claim link: /claim?token=<raw_token>
⚠
Token Expiry Handling

If a user follows a claim link after the 15-minute TTL, they receive an expiry page with a "resend claim link" option. Admins can also resend from the admin console. Design your notification strategy to minimise TTL expirations — send claim links during business hours when users are likely to act immediately.

Batch Claim Dispatch

After bulk import, claim links can be dispatched in batches:

POST /admin/users/dispatch-claim-notifications
{ "filter": { "status": "MIGRATED_UNCLAIMED", "group": "staff", "not_notified_since": "2026-09-01T00:00:00Z" }, "batch_size": 500, "channel": "email" }

Re-Sending Claim Links

For users who miss the initial notification:

  • Admin Console: Users page → select user → Actions → Resend Claim Link
  • API: POST /admin/users/{id}/resend-claim
  • Self-service: Users can request a new claim link from the login page by entering their email/phone

Claim Rate Tracking

Monitor claim progress from Admin Console → Dashboard → Migration Status:

  • Total imported / Claimed / Pending / Notification failed
  • Claim rate by group
  • Claim rate over time (7-day chart)
  • Oldest unclaimed accounts (risk indicator)

Unclaimed Account Expiry Policy

Define a policy for accounts that remain unclaimed after the rollout window. Options:

  • Keep indefinitely: No automatic action. Accounts remain MIGRATED_UNCLAIMED until admin action.
  • Auto-deactivate: After N days, transition to INACTIVE. Users must contact admin to reactivate.
  • Notify and warn: Send reminder notifications at 7, 14, and 30 days before auto-deactivation.

Database Migration Sequence

Hawiyati uses Flyway for versioned schema migrations. The current production head is V62. The following migrations implement the registration, KYC, and account claim feature set planned in this guide (authored when head was V53 — verify and renumber starting from V63 before applying):

V54
Registration Sessions
Adds registration_sessions table — tracks SP-initiated registration flows with continuation token (stores sp_entity_id FK only, never raw URL), state, and expiry. Adds completion_tokens table.
Phase A
V55
KYC Sessions
Adds kyc_sessions table with workflow type (BASIC/STANDARD/STRONG/HIGH_ASSURANCE), state machine column, face_match_score DOUBLE PRECISION, document reference FK, and reviewer assignment.
Phase C
V56
KYC Profiles
Adds kyc_profiles table — source of truth for current_level (L0–L4). Adds profile_valid_until, reverification_required_at. Adds document fingerprint index on kyc_documents.
Phase C
V57
Account Claim Tokens
Adds account_claim_tokens table — stores HMAC-SHA256 of token, user_id FK, expires_at, used_at, revoked_at. Unique index on token_hash.
Phase D
V58
SCIM Provisioning
Adds scim_resources table with external_id, source_instance_id, etag. Adds scim_sync_log for idempotency tracking. No credential or assurance fields via SCIM.
Phase E
V59
Notification Outbox
Adds notification_outbox table — idempotency key, payload, scheduled_at, sent_at, error, retry_count. Supports SKIP LOCKED polling pattern and exponential backoff (30s/2m/8m/32m/128m).
Phase D
V60
Bulk Import Audit
Adds bulk_import_jobs and bulk_import_rows tables. Tracks per-row import status, error messages, and claim dispatch state. Enables migration status dashboard queries.
Phase F

Zero-Downtime Migration Strategy

Database migrations must be safe to run against a live production database. Follow these rules:

  • Additive-only in V54–V59: All migrations add new tables or nullable columns. No existing table is altered in a breaking way.
  • No NOT NULL without defaults: If a column is added to an existing table, it must have a DEFAULT or be nullable. Backfill in a separate step.
  • Index creation with CONCURRENTLY: Large table indexes use CREATE INDEX CONCURRENTLY in PostgreSQL to avoid table locks.
  • Test against a production data copy: Run all migrations against a recent production dump before applying to production. Verify migration duration and lock contention.
  • Rollback scripts: Each migration has a corresponding V-rollback script (e.g., V54__rollback.sql) that drops only the objects added by V54. Rollback is tested in the same environment as the migration.
⚠
Apply Migrations Before Deploying Application Code

Migrations V54–V60 must be applied and verified before the application code that references the new tables is deployed. Deploy the migration first, verify schema, then roll out the new application version. Never deploy application code that references tables that don't yet exist.

Phase A — Foundation

Phase A: Foundation & Schema Phase A

Establish the foundational data model changes required by all subsequent phases. No user-facing feature changes in this phase — focus is entirely on schema preparation and core service extensions.

Key Deliverables

  • Flyway migration V54 applied: registration sessions and completion tokens tables
  • Continuation token model implemented: stores sp_entity_id FK only (no raw URL — open redirect prevention)
  • Completion token service: 256-bit random, HMAC-SHA256 stored, 15-min TTL, single-use validation
  • Account status model documented and enforced: two-flag system (active + pending_approval)
  • Source-of-truth rule codified: kyc_profiles.current_level is authoritative — never users.assurance_level

Acceptance Criteria

  • V54 migration runs clean against staging database
  • Completion token generated, stored as HMAC, validated, and single-use consumption verified
  • Continuation token stores only sp_entity_id; open redirect test rejects raw URL injection
  • All Phase A unit and integration tests pass

Rollback Point

V54 rollback script drops the two new tables. No application behaviour changes in Phase A, so rollback has no user impact.

Phase B — Registration Flows

Phase B: Registration Flows Phase B

Implement all five user registration flows: self-service, admin-driven invitation, SP-initiated, enterprise provisioning, and bulk import. Each flow is independently testable.

Key Deliverables

  • Self-service registration endpoint with email/phone verification and L0 account creation
  • Admin-driven invitation flow: admin creates account, invite email dispatched, user sets password
  • SP-initiated registration: completion token returned to SP after successful registration
  • Account status transitions: MIGRATED_UNCLAIMED → ACTIVE on claim, ACTIVE_LIMITED → ACTIVE on approval
  • Registration rate limiting and duplicate account detection
  • Audit events for all registration state transitions

Acceptance Criteria

  • All five registration flows pass end-to-end integration tests
  • Completion token delivered to SP and validated in SP demo application
  • Duplicate registration rejected at email/phone level
  • All registration events appear in audit log with correct actor and outcome

Rollback Point

New registration endpoints can be disabled via feature flag. Existing accounts and sessions are not affected.

Phase C — KYC Integration

Phase C: KYC & Assurance Phase C

Integrate the KYC verification workflows and assurance level management. Applies Flyway migrations V55 and V56 to add KYC sessions and profiles.

Key Deliverables

  • V55 and V56 migrations: KYC sessions and profiles tables
  • KYC state machine: NOT_STARTED → IN_PROGRESS → DOCUMENT_SUBMITTED → UNDER_REVIEW → APPROVED/REJECTED
  • Basic and Standard workflows (document OCR/MRZ + optional selfie/face match)
  • Document fingerprinting: HMAC-SHA256 of normalized country|docType|docNumber
  • Duplicate fingerprint → manual review signal (not hard block)
  • L3/L4 frozen at UNDER_REVIEW pending biometric team approval
  • kyc_profiles.current_level as authoritative assurance level source

Acceptance Criteria

  • Document submission transitions KYC session to DOCUMENT_SUBMITTED
  • Approved session updates kyc_profiles.current_level to L2 (Standard) or L3 (Strong)
  • Duplicate document fingerprint routes to manual review queue, not rejection
  • L3/L4 approval requires explicit admin action in reviewer queue
  • All KYC state transitions recorded in audit log

Rollback Point

V55/V56 rollback scripts drop KYC tables. KYC workflows can be disabled at the SP policy level; existing assurance levels are unaffected.

Phase D — Account Claim

Phase D: Account Claim & Notifications Phase D

Implement the account claim flow for MIGRATED_UNCLAIMED users, claim token lifecycle management, notification outbox, and bulk claim dispatch. Applies V57 and V59 migrations.

Key Deliverables

  • V57 migration: account_claim_tokens table with HMAC storage and single-use enforcement
  • V59 migration: notification_outbox table with idempotency key and retry state
  • Claim token generation and delivery endpoint
  • Claim redemption flow: token validation → identity verification → credential enrollment → ACTIVE transition
  • Outbox processor: SKIP LOCKED, exponential backoff (30s/2m/8m/32m/128m), dead-letter handling
  • Admin console: resend claim link, view pending notifications, bulk dispatch

Acceptance Criteria

  • Claim token is single-use: second redemption returns 410 Gone
  • Expired token shows re-send prompt, not generic error
  • Notification outbox retries on gateway failure with exponential backoff
  • Bulk claim dispatch of 1,000 users completes without memory overflow
  • Claim audit event records actor (user), outcome (SUCCESS/FAILURE), and token metadata

Rollback Point

V57/V59 rollback drops token and outbox tables. Unclaimed users remain in MIGRATED_UNCLAIMED — no data loss. Claim links in transit become invalid.

Phase E — SCIM Provisioning

Phase E: SCIM 2.0 Provisioning Phase E

Implement inbound SCIM 2.0 provisioning from SP systems. Applies V58 migration. SCIM creates users in MIGRATED_UNCLAIMED state, triggering the account claim flow automatically.

Key Deliverables

  • V58 migration: scim_resources and scim_sync_log tables
  • SCIM 2.0 endpoints: /Users (GET/POST/PATCH/DELETE), /Groups (GET/POST/PATCH/DELETE)
  • Extension schema: externalId, sourceInstanceId, pendingApproval ONLY — no credential or assurance fields
  • SCIM-created users start in MIGRATED_UNCLAIMED; claim token auto-generated on creation
  • Bearer token authentication for SCIM clients
  • ETag-based optimistic concurrency on PATCH operations

Acceptance Criteria

  • SCIM POST /Users creates user in MIGRATED_UNCLAIMED state and generates claim token
  • SCIM PATCH /Users/{id} active=false transitions account to INACTIVE
  • SCIM PATCH /Users/{id} with password field returns 400 — credentials not settable via SCIM
  • ETag mismatch on PATCH returns 412 Precondition Failed
  • SCIM test suite (RFC 7644 compliance) passes at hawiyati-sp-scim-test

Rollback Point

V58 rollback drops SCIM tables. SCIM endpoint returns 503 after rollback. Existing users provisioned via SCIM are unaffected — they are regular Hawiyati users at that point.

Phase F — Monitoring & Hardening

Phase F: Monitoring, Audit & Hardening Phase F

Production-readiness phase: monitoring dashboards, alert rules, bulk import audit trail, operational runbooks, and security hardening for the new registration and KYC flows.

Key Deliverables

  • V60 migration: bulk_import_jobs and bulk_import_rows tables for migration status dashboard
  • Migration status dashboard: claim rate by group, notification failures, oldest unclaimed accounts
  • Prometheus metrics for claim rate, KYC completion rate, outbox queue depth, token expiry rate
  • Alert rules: claim rate below threshold, KYC review queue > N items, outbox dead-letter count > 0
  • Operational runbook: resend claims, unblock manual review queue, handle notification gateway outage
  • Security audit of new endpoints: claim token brute-force protection, rate limiting on resend

Acceptance Criteria

  • Migration status dashboard shows accurate per-group claim rate
  • Alert fires within 5 minutes when outbox dead-letter count exceeds threshold
  • Claim token brute-force: 10 invalid attempts triggers account-level lockout on claim endpoint
  • All Phase F acceptance tests and runbook walkthroughs completed by operations team

Rollback Point

Phase F is additive (monitoring only). V60 rollback drops audit tables — functional behaviour is unchanged. Monitoring can be disabled without affecting user-facing features.

Parallel Run

In a brownfield migration, Hawiyati operates alongside the existing IdP. Traffic is migrated SP by SP. Both systems process authentication requests during the transition window.

SP Migration Order

Recommended migration order (lowest to highest risk):

1
Internal Low-Risk Applications
Intranet portals, dev tools, internal dashboards. Low user impact if issues arise. Validates Hawiyati configuration and attribute mapping in production.
2
Pilot Group — Business Applications
Migrate one or two business-critical applications with a pilot user group (5–10% of users). Monitor for 1–2 weeks before expanding.
3
Bulk Migration — Remaining SPs
Migrate remaining SPs in batches. Continue monitoring claim rates and error rates per SP. Dispatch claim notifications for newly migrated user groups.
4
Final Cutover
All SPs migrated. Claim rate > 80%. Old IdP set to read-only. Decommission scheduled.

Monitoring During Parallel Run

Metric Target Action if Breached
Login success rate (Hawiyati) > 99.5% Investigate errors; consider reverting SP to old IdP
Login latency p95 < 500ms Check Redis connectivity; review database query plans
Claim rate (7-day rolling) Increasing week-over-week Re-send notifications; check notification gateway delivery logs
Notification delivery failure < 1% Check email/SMS gateway; review outbox dead-letter queue
Support tickets related to login No spike vs baseline Categorize tickets; prioritize user-facing issues

Cutover Sequence

Cutover Decision Criteria

Do not proceed with cutover until all of the following conditions are met:

  • All SPs migrated to Hawiyati and tested in production
  • Claim rate > 80% across all user groups
  • Login success rate > 99.5% sustained over 7 days
  • Zero open P1/P2 defects against Hawiyati
  • On-call runbook reviewed and signed off by operations team
  • Rollback plan tested (not just documented) in staging environment
  • TLS certificates valid for 12+ months on all Hawiyati endpoints
  • Backup verified within 24 hours of cutover date

Cutover Steps

1
Maintenance Window Notification
Notify users 72 hours and 24 hours before cutover. Specify the maintenance window (recommend 2–4 hours, off-peak). Notify SP owners separately with expected downtime for their application.
2
Old IdP — Drain and Freeze
Stop new session creation on old IdP. Allow active sessions to expire naturally (do not force logout). Set old IdP metadata endpoints to return HTTP 410.
3
DNS / Metadata Switchover
Update DNS records to point IdP hostname to Hawiyati. Update SP configurations to use Hawiyati metadata endpoint. Verify SP metadata has been re-fetched (cache TTL may require manual refresh).
4
Smoke Test
Run pre-prepared smoke test suite: login via each SP (SAML + OIDC), MFA enrollment, password reset, audit log capture. Must pass before opening to users.
5
Open to Users — Monitor 48 Hours
Lift maintenance window. Monitor login success rate, latency, error rate, and support tickets for 48 hours. On-call engineer on standby throughout.

Post-Cutover Decommission Checklist

  • Old IdP sessions fully expired (wait for configured session TTL + 1 hour)
  • Old IdP audit logs exported and archived to long-term storage
  • Old IdP database backed up and stored per retention policy
  • Old IdP infrastructure decommissioned (VMs stopped, DNS entries removed)
  • SP owners notified that old IdP is fully decommissioned
  • Old IdP certificates revoked

Rollback Plan

Rollback Triggers

Execute the rollback plan if any of the following occur during cutover or the 48-hour monitoring window:

✕
Immediate Rollback Triggers

Login success rate drops below 95% for more than 5 minutes. P0 defect discovered (data loss, credential exposure, session fixation). More than 10% of SP owners report authentication failures. Hawiyati service becomes unresponsive for more than 2 minutes.

Rollback Procedure

1
Declare Rollback
Incident commander declares rollback. Notify all SP owners and on-call teams immediately. Set Hawiyati to return HTTP 503 on login endpoints to stop new authentication attempts.
2
DNS Revert
Revert DNS records to point IdP hostname back to old IdP. Use pre-prepared DNS change — do not edit during incident. TTL should have been pre-lowered to 60 seconds before cutover.
3
Invalidate Redis Cache
Flush Hawiyati Redis session cache and SP config cache. This forces all in-flight sessions back to the old IdP without stale routing data.
4
Restore Old IdP
Bring old IdP back to full operation. Verify metadata endpoints are responsive. Ask SP owners to clear their IdP metadata cache (or wait for natural TTL expiry).
5
Verify and Communicate
Confirm login success rate restored on old IdP. Send status update to all SP owners and affected users. Document rollback timeline, trigger, and next steps for retrying migration.

Data Consistency After Rollback

Users who claimed their accounts during the cutover window will have their credentials stored in Hawiyati. If rolled back:

  • Claimed users can log in to the old IdP only with their old credentials (the ones before claim). If they had no Argon2id hash imported, they cannot log in to old IdP and must use the password reset flow there.
  • New user registrations created during the cutover window exist only in Hawiyati and will not be available in the old IdP.
  • Re-migration will pick up where it left off — claimed users retain their Hawiyati accounts; only the SP routing changes.
⚠
Pre-Prepare the Rollback

The rollback plan must be tested in staging before cutover, not just documented. Record the exact commands, DNS change IDs, and Redis flush commands. During an incident is not the time to figure out the procedure.

User Communication Template

Subject: [Action Required] Authentication system maintenance update We are currently experiencing an issue with our authentication system update and have temporarily reverted to our previous login system. If you recently set a new password as part of the account claim process, you may need to use your previous password to log in. If you cannot remember your previous password, please use the "Forgot Password" link on the login page. We apologize for the inconvenience and will communicate next steps within [X hours]. — [Your IT Team]
HawiyatiDocumentation · v2026 · Spring Boot 3.5