Auth Service — Migration Plan

Status: populated Owner: Engineering + SRE Last updated: 2026-04-19

1. Context

auth-service is new — no legacy production data. What changes is:

1. The integration posture with Kong (JWKS + custom API key lookup plugin).
2. The IdP baseline: we ship with Keycloak as the default IdP and a pluggable IdentityProvider port. Firebase is demoted to a legacy/optional provider. External tenant OIDC/SAML SSO is a future capability on the same abstraction — no downstream refactor needed when the first such tenant lands.

2. Changes

1. Expose /.well-known/jwks.json (new endpoint).
2. Expose internal GET /v1/api-keys/lookup?hash= for Kong custom plugin (new).
3. API key raw format standardized (ghasi_live_...); migrate any dev keys to new format.
4. Outbox table introduced; event publication moves through relay.
5. Keycloak deployed in ghasi-identity namespace; realm ghasi-<env> per environment.
6. Schema additions: tenant_identity_providers, external_identities, idp_session_audit; users gains primary_provider_id, drops hard-coded firebase_uid.
7. New endpoints: /v1/auth/sso/*, /v1/auth/saml/*, /v1/tenants/{tenantId}/identity-providers/*, /scim/v2/*.

3. Phases

Phase	Duration	State
0	1 week	Deploy Keycloak to staging with realm, test users, and Vault-managed signing keys.
1	1 week	Deploy auth-service to staging; Kong points to its JWKS; native + Keycloak login smoke tests pass.
2	3 days	Customer-portal + admin-dashboard switched to use auth-service Keycloak SSO; native fallback retained for break-glass.
3	2 days	Kong custom ghasi-api-key-lookup plugin enabled on staging; dry-run against real traffic.
4	Production	Cutover behind feature flag AUTH_KONG_PATH=on for 10% tenants → full.
5	Post-GA	First enterprise tenant onboarded with external OIDC IdP (Azure AD / Okta / Google) via /v1/tenants/{id}/identity-providers.
6	Post-GA	First enterprise tenant onboarded with external SAML 2.0 IdP.
7	TBD	Firebase legacy provider retirement: migrate residual Firebase-only users to Keycloak (force password reset or social-login bind); drop firebase-legacy provider.

4. Data migration

• No legacy user data in production.
• Existing dev/Firebase users: imported by email; each user is (a) created in Keycloak, (b) linked via external_identities (provider_id='firebase-legacy', external_subject=firebaseUid), (c) prompted to re-verify at next login so they end up linked to keycloak going forward.

5. Rollback

• Kong can revert to no JWT plugin (all 401) temporarily while we patch.
• Feature flag on lookup plugin allows instant disable.
• For per-tenant IdP rollout, auth.tenant_identity_providers.status = 'disabled' forces that tenant back to the default keycloak provider without restart.

6. Exit

• All services accept only Kong-injected identity headers.
• No service validates JWT directly anymore (lesson from retired api-gateway).
• Downstream services remain IdP-agnostic — adding a new tenant IdP is a config change, not a code change.