KeepSafe Identity Migration Plan

Dedicated identity authority for KeepSafe public and admin surfaces.

Goal

Move KeepSafe authentication and authorization off the older shared KeepSafeAdmin login model and onto https://identity.keepsafe.ai. The new service owns app clients, login methods, OAuth/OIDC tokens, hosted login pages, admin login, MFA, session controls, user type, permissions, and the global authorization claims consumed by KeepSafe subdomains.

Phase 1: Dedicated Service Baseline

Create the SilverPineSoftware/keepsafe-identity-service repository from the reusable SSO server code.
Deploy to the EC2 host behind identity.keepsafe.ai with Caddy TLS, systemd, root-only environment files, and a service-local SQLite database.
Verify /health, /docs, /openapi.json, OIDC discovery, JWKS, hosted login, and admin login.

Phase 2: Canonical KeepSafe Clients

Create one Identity app client per KeepSafe surface instead of sharing the old KeepSafeAdmin client.
Register exact callback, logout, and allowed-origin settings for Sources, Finalizer, Notifier, Messenger, Brivo, KeepSafe Web, and any remaining admin tools.
Keep the old SSO configuration available during validation so each app has a rollback path.

Phase 3: Identity-Backed Authorization

Store global user authorization in Identity by email: user by default, admin scoped to the user's assigned organization, and superadmin for full Identity administration.
Expose Identity-managed role, roles, global_role, organization_id, organization_name, permissions, is_admin, and is_superuser claims from ID tokens, userinfo, token responses, session introspection, and shared admin cookies.
Keep app-scoped standard/superuser compatibility as app_role while migrating subdomains to enforce the global Identity role.

Phase 4: Admin App Migration

Move sources.keepsafe.ai, finalizer.keepsafe.ai, notifier.keepsafe.ai, messenger.keepsafe.ai, and brivo.keepsafe.ai to identity.keepsafe.ai one app at a time.
Keep per-app Identity clients and callbacks, but standardize admin browsers on the shared keepsafe_admin_session cookie scoped to .keepsafe.ai.
Validate login, callback, logout, session expiry, userinfo, token introspection, admin role checks, and rollback config before moving the next app.

Phase 5: KeepSafe-Web Migration

Replace Auth.js direct Google/email login and TypeORM adapter tables with redirects to Identity.
Keep Google, email, passwordless, username/password, and MFA decisions behind Identity rather than inside KeepSafe Web.
Use Identity claims for user type and privilege checks after login; use Entity for product users, assets, organizations, settings, and domain data.

Phase 6: Retire Old KeepSafeAdmin Login

Remove KeepSafe callbacks and origins from the older shared SSO host once all KeepSafe apps have moved.
Remove only old sso.keepsafe.ai / KeepSafeAdmin dependencies from service env files, docs, and admin UIs.
Leave non-KeepSafe UU/SPSW apps on the old SSO host only if they still need it.

Current Status

The baseline service is live on identity.keepsafe.ai. Identity clients exist for Admin Hub, Status, Monitor, Sources, Analyze, Finalizer, Notifier, Brivo, Messenger, Renderer, and Identity Admin. Browser login for those admin surfaces points at identity.keepsafe.ai with per-app clients while sharing one keepsafe_admin_session cookie across .keepsafe.ai.

The old sso.keepsafe.ai host remains available as a compatibility bridge while final smoke testing, source documentation cleanup, KeepSafe-web migration, and any remaining machine-token integrations are finished. GitHub publication is waiting for the SilverPineSoftware/keepsafe-identity-service repository or matching create/access permission. Identity now carries the global KeepSafe authorization source; the next migration slice is wiring remaining relying parties to consume those claims.