Skip to main content

Keycloak Setup Guide

Citadel uses Keycloak (or any OIDC-compliant provider) as its Identity Provider. For local development, we provide scripts to automate the configuration of a citadel realm.

Realm Configuration​

The core configuration is defined in scripts/keycloak/realm-template.json. This template includes:

  • Realm Name: citadel
  • Clients:
    • shell-app: Public client for the frontend (PKCE enabled).
    • citadel: Confidential client for backend services (Service Accounts enabled).
  • Roles:
    • admin: Platform administrator role.
    • user: Standard user role.

Automated Setup (Local)​

When running locally (via docker-compose or Dev Container), you can configure Keycloak using the included helper script.

Prerequisites​

  • Keycloak must be running and accessible at http://localhost:8080 (or the configured URL).
  • Node.js must be installed to run the setup script.

Running the Script​

# From workspace root
./scripts/keycloak/setup.sh

This script:

  1. Connects to Keycloak using the bootstrap admin credentials (admin/admin).
  2. Creates the citadel realm if it doesn't exist.
  3. Creates the shell-app and citadel clients.
  4. Creates a test admin user (admin/password).
  5. Important: Updates your .env file with the generated Client Secrets and User UUIDs.

Manual Configuration (Production)​

For production environments, you should configure Keycloak using Terraform or the Keycloak Admin Console.

Required Clients​

1. Backend Client (citadel)​

  • Access Type: Confidential
  • Service Accounts Enabled: Yes
  • Valid Redirect URIs: None needed (S2S only)

2. Frontend Client (shell-app)​

  • Access Type: Public
  • Standard Flow Enabled: Yes
  • Direct Access Grants: No
  • Valid Redirect URIs:
    • https://<your-domain>/callback
    • https://<your-domain>/silent-renew-callback.html
  • Web Origins: https://<your-domain>

Adding External IdPs (Federation)​

To enable "Login with Google" or "Login with MeriPehchan":

  1. Go to Identity Providers in the Keycloak Admin Console.
  2. Select the provider (e.g., Google, OpenID Connect).
  3. Enter the Client ID and Secret obtained from the external provider.
  4. (Optional) Configuring mappers to import claims like district or kyc_level into Keycloak User Attributes.

Citadel's iam-service will automatically detect these attributes if they are mapped to the access token.