Identity Service — Migration Plan

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · SERVICE_OVERVIEW §13 Source reconciliation

1. Migration scope

identity-service consolidates three legacy modules that previously ran as separate concerns inside the monolithic Ghasi EHR application:

Legacy module	New location	Notes
iam (auth, users, sessions, MFA, OIDC)	identity-service core	Primary migration target
licensing (module catalogue, assignments, resolver)	identity-service — merged	Co-located for trust-boundary reasons
access-policy (RBAC, roles, evaluate)	tenant-service (not here)	Moved to correct bounded context

2. Legacy event subject aliases

During migration, identity-service dual-publishes events on both legacy and new subjects. Consumers should migrate to new subjects by M2.

Legacy subject	New subject	Decommission milestone
com.ghasi-ehr.iam.user.registered	identity.user.registered.v1	M2
com.ghasi-ehr.iam.user.suspended	identity.user.suspended.v1	M2
com.ghasi-ehr.iam.session.created	identity.session.created.v1	M2
licensing.assignment.created	identity.license.assignment.created.v1	M2
licensing.assignment.status_changed	identity.license.assignment.status_changed.v1	M2

3. Legacy FR prefix mapping

Legacy prefix	New prefix	Domain
FR-IAM-AUTH-*	FR-IDENT-AUTH-*	Authentication
FR-IAM-USR-*	FR-IDENT-USR-*	User lifecycle
FR-IAM-SVC-*	FR-IDENT-SVC-*	Service accounts
FR-IAM-PROV-*	FR-IDENT-PROV-*	Provider hierarchy linking
FR-IAM-CTX-*	FR-IDENT-CTX-*	Access context aggregation
FR-LICN-*	FR-IDENT-LIC-*	Licensing
FR-ACPOL-*	FR-TENANT-ACC-*	Moved to tenant-service

Legacy refs are preserved in traceability tables and story "Legacy FR refs" columns.

4. Database migration phases

Phase 1 — Schema extraction (M0)

1. Create identity PostgreSQL schema from monolith public schema.
2. Run COPY or pg_dump --schema=public --table=users ... to seed identity tables.
3. Deploy identity-service pointing at new schema; monolith reads from same DB (read-only shadow).
4. Run integration tests: tenant-isolation, outbox, inbox.
5. Cut traffic to identity-service for auth endpoints; monolith delegates.

Phase 2 — Licensing data migration (M1)

1. Export module_catalogue and license_assignments rows from legacy licensing tables.
2. Transform to new modules / license_assignments schema (ULID IDs, status enum alignment).
3. Validate dependency graph integrity (BR-LIC-001).
4. Seed module_bundles for existing bundle definitions.
5. Verify effective license resolver output matches legacy resolver for sampled tenants.

Phase 3 — Keycloak realm alignment (M2)

1. Audit existing Keycloak realms; map to provider_kind = keycloak_broker.
2. Backfill keycloak_user_id on users rows for broker-mode tenants.
3. Retire legacy Keycloak token-exchange proxy; use identity-service /auth/keycloak/token-exchange.

Phase 4 — Legacy monolith decommission (M3)

1. Verify 30 days of zero traffic to legacy auth/licensing routes.
2. Remove dual-publish legacy event aliases.
3. Archive legacy iam and licensing source modules.
4. Drop shadow DB access grants.

5. Tenant migration checklist

For each existing tenant migrating to identity-service:

• Users exported and imported with hashed credentials (argon2id re-hash if bcrypt legacy).
• Sessions migrated or invalidated (force re-login is acceptable for M0 cutover).
• MFA factors migrated (TOTP seeds re-wrapped with KMS; WebAuthn credentials re-enrolled if format incompatible).
• Devices re-registered (offline binding certificates reissued).
• License assignments migrated and verified.
• Keycloak user IDs backfilled (if keycloak_broker mode).
• Tenant admin notified of cutover window.

6. Rollback plan

Phase	Rollback mechanism
Phase 1	Feature flag IDENTITY_SERVICE_AUTH_ENABLED=false routes to monolith; DB schema untouched
Phase 2	Revert licensing seed; re-enable legacy licensing tables in monolith
Phase 3	Disable Keycloak broker mode per tenant; revert token-exchange proxy
Phase 4	Irreversible; dual-publish removal is only executed after 30-day verification

7. Open questions

• Credential re-hashing strategy for tenants with bcrypt legacy hashes — re-hash on first successful login or batch job?
• SCIM provider migration timeline (scim-owned by tenant-service; needs coordination).