Keycloak Authentication

Keycloak handles authentication and authorization for both the Taxpayer Portal and Tax Admin Dashboard. Each environment has its own Keycloak instance.

Instances

Environment	URL	Image	Database
DEV	https://auth.swarm.ayinza.dev	keycloak:26.0-sseris	DEV PostgreSQL
UAT	https://auth.ayinza.dev	keycloak:26.0	UAT PostgreSQL

Realm Configuration

Both environments use a realm called ssra (SSERIS South Sudan Revenue Authority).

The realm export is stored at /home/kaks/stacks/ssra-realm-export.json on Azure and is imported when Keycloak first starts.

Key Differences Between DEV and UAT

Feature	DEV	UAT
Image	keycloak:26.0-sseris	keycloak:26.0
Custom theme	Custom SSERIS theme (26.0-sseris)	Base Keycloak (26.0, no custom theme)
Domain	auth.swarm.ayinza.dev	auth.ayinza.dev
Database	DEV PostgreSQL (port 5432)	UAT PostgreSQL (port 5433)

Custom Theme

Keycloak DEV uses a custom SSERIS theme for the login pages. The theme is baked into the Docker image (keycloak:26.0-sseris). UAT uses the base Keycloak image (keycloak:26.0) without a custom theme. To update the DEV theme:

1. Modify the theme in the keycloak theme repo
2. Build a new Docker image
3. Push to Harbor
4. Update the service

Common Tasks

Access Admin Console

1. Go to https://auth.swarm.ayinza.dev (DEV) or https://auth.ayinza.dev (UAT)
2. Click Administration Console
3. Log in with the admin credentials (stored in the stack YAML)

Create a New User

1. Admin Console → Users → Add User
2. Set username, email, first/last name
3. After creating, go to Credentials tab → Set Password
4. Assign realm roles as needed

Export Realm Configuration

# On the Keycloak container
/opt/keycloak/bin/kc.sh export --dir /opt/keycloak/data/export --realm ssra