Skip to content

Keycloak: Realms Overview

Keycloak acts as the OIDC identity provider for both Messages and Calendars. It runs as part of the Messages stack with its own PostgreSQL database.

Realms

Each application gets its own realm:

Realm Admin URL Clients
messages https://auth.messages.<domain>/admin/messages/console/ messages, rest-api, account, account-console, security-admin-console
calendars https://auth.messages.<domain>/admin/calendars/console/ calendars, account, account-console, security-admin-console

Shared Configuration

Both realms use:

  • Standard Flow OIDC (Authorization Code)
  • RS256 signing algorithm
  • openid email scopes
  • SSL required for external requests only (sslRequired: external)

Admin Access

URL Username Password
https://auth.messages.<domain>/admin admin Set in compose environment

Realm Import

Realms are imported on Keycloak startup via JSON files:

volumes:
  - ./keycloak-realm.json:/opt/keycloak/data/import/realm.json:ro
  - ../calendars/keycloak-realm.json:/opt/keycloak/data/import/calendars-realm.json:ro

Each file must be a single JSON object (not an array). In Keycloak 26.x, multi-realm arrays in a single file cause import failures.

User Management

Users must be created per-realm:

  1. Go to the realm's admin console
  2. Navigate to Users → Create user
  3. Set email, username, and password
  4. Users login via OIDC at their respective application

The OIDC_CREATE_USER=True setting auto-creates Django user accounts on first login.