Deployment

The target deployment runs Taifa’s Go issuer, Svelte portal, Python management service, PostgreSQL, and the required private worker and Mail connections. The issuer’s production startup currently refuses to run, so this is a preparation and acceptance guide, not a production command sequence.

Keep boundaries separate

Expose only approved OIDC and portal routes through trusted HTTPS ingress. Keep the issuer’s private challenge listener, management write API, database, machine admission routes, and worker traffic on private authenticated paths. The issuer string must remain stable through host or ingress changes because products use (issuer, subject) as their durable identity key. Use exact callback and WebAuthn origins; do not disable TLS validation to pass a preview.

Select the owned issuer

An issuer is the exact HTTPS identity of the authentication server. Configure Go with AUTH_ISSUER and connected services with the same OIDC_ISSUER. It identifies Taifa’s own server, which exposes discovery and verification keys. It does not require an external authentication service or a /realms/ path.

Management requires an explicit IDENTITY_PROVIDER=owned selection. For an isolated prepared development deployment, the issuer configuration is:

IDENTITY_ENV=development
IDENTITY_PROVIDER=owned
OWNED_DEVELOPMENT_ISSUER=https://localhost:19725
OIDC_ISSUER=https://localhost:19725
OIDC_JWKS_URL=https://localhost:19725/keys

The development pin must equal the issuer byte for byte. Only canonical HTTPS loopback origins are accepted. Use the prepared CA certificate through OIDC_CA_BUNDLE for Management’s public discovery probe. Staging and production configuration pin the owned origins https://accounts-staging.govconnect.ke and https://accounts.govconnect.ke; accepting these URLs does not enable production startup.

IDENTITY_PROVIDER=keycloak selects retained legacy migration operations. An absent selector defaults to that legacy mode for existing deployments. An invalid selector fails closed. Its realm issuer is a different identity from the owned origin, so changing this configuration does not migrate accounts or registrations. Legacy adapters and queued legacy provider actions refuse owned mode. The separate owned permission-catalog and client-policy review APIs remain available, with sign-in activation still requiring their unfinished private writer/readback acceptance. See client registration.

Prepare state and secrets

Apply database migrations in order to a scratch environment, then rehearse forward migration and restore with preserved credential, audit, idempotency, and outbox data. The auth service currently has forward-only credential migrations; destructive downgrades are not an acceptable rollback. Keep OIDC signing, lifecycle signing, TOTP encryption, passkey encryption, admission, Mail, and client secrets distinct. Restrict private key files to the service owner and document key IDs and rotation overlap.

Prove release gates

The isolated Go service uses development-only loopback listeners and disposable database checks. Before changing that guard, complete reviewed person provisioning and privileged admission, recovery, multi-client registration and SSO, central logout and back-channel revocation, key rotation, PostgreSQL 16 validation, rate limiting, real authenticator tests, lifecycle expiry and catch-up, Mail holder delivery, and product acknowledgement. Build an immutable release image and test restore and failover. Do not infer readiness from local unit tests.

Roll out a product

Register one reviewed client and one project-scoped lifecycle consumer per environment. Verify issuer discovery, exact redirects, signed token claims, Institution mapping, account linking, a revoked-user path, and product session shutdown in staging. Start with a small sponsored Institution and observe lifecycle lag and worker diagnostics before expanding. See product migration.