Skip to content

Keycloak

Single sign-on, identity management, and role-based access control.
URL https://identity.akko.local
Admin console https://identity.akko.local/admin/
Helm sub-chart akko-keycloak (custom)

Overview

Keycloak is the identity provider for the entire AKKO platform. Every service that has a web UI authenticates through Keycloak using OAuth2 / OpenID Connect, providing a unified login experience across all tools.

Key capabilities:

  • Single Sign-On (SSO) -- log in once, access all services
  • Role-Based Access Control (RBAC) -- five platform roles control what users can see and do
  • Realm export -- the full configuration is version-controlled in keycloak/realm-akko.json
  • Brute force protection -- enabled by default (locks after 5 failed attempts)

Realm: akko

All AKKO configuration lives in a single Keycloak realm named akko. The realm is imported automatically on first startup from keycloak/realm-akko.json.

Key realm settings:

Setting Value
Realm name akko
Display name AKKO
Login theme akko (custom)
Signature algorithm RS256
Access token lifespan 300 seconds (5 min)
SSO session idle timeout 1800 seconds (30 min)
SSO session max lifespan 36000 seconds (10 hours)
Registration Disabled
Brute force protection Enabled (5 failures, 5 min lockout)

OAuth2 Clients

The realm includes 13 OAuth2 clients (10 AKKO service clients + 3 Keycloak internal surfaced by default):

Client Type Service
jupyterhub Confidential JupyterHub notebook environment
superset Confidential Apache Superset BI
airflow Confidential Apache Airflow orchestration
grafana Confidential Dashboards
trino Confidential Trino SQL engine
polaris Confidential Apache Polaris catalog
openmetadata Confidential OpenMetadata governance
oauth2-proxy Confidential OAuth2 Proxy (protects services without native OAuth)
minio Confidential object storage console
svc-cockpit-admin Confidential Cockpit admin service account (Keycloak Admin API)
account Public Keycloak account management (built-in)
admin-cli Public Keycloak admin CLI (built-in)
realm-management Confidential Keycloak realm management (built-in)

Additional Keycloak built-in clients

Keycloak also ships account-console, broker, and security-admin-console in every realm for its own admin UI. They are not counted in the "13 clients" figure because they are internal to Keycloak and not consumed by AKKO services.

Confidential vs Public clients

Confidential clients use a client secret for server-side auth code flow. Public clients use PKCE for browser-based flows. OpenMetadata specifically requires a confidential client to avoid login loops with self-signed certificates in Safari.

RBAC Roles

Five platform-wide roles control access across all services:

Role Description Typical Access
akko-admin Platform administrator Full access to all services, admin consoles, DDL operations
akko-engineer Data engineer Spark, Airflow, Trino DDL, notebook write, pipeline management
akko-analyst Data analyst Notebooks, Superset, Trino read-only, catalog browsing
akko-user Standard user / compliance Trino read-only with PII masking, audit, catalog browsing
akko-viewer Dashboard viewer Superset dashboards (view only), Dashboards

Default role

New users are automatically assigned the akko-analyst role via the default-roles-akko composite role.

For the full RBAC access matrix (per-service, per-catalog, column masking, row filtering), see the RBAC Administration Guide.

Default Users

Five test users are pre-configured in the realm:

Username Role Password Description
alice akko-admin alice123 (dev) Platform administrator
bob akko-engineer bob123 (dev) Data engineer
carol akko-analyst carol123 (dev) Data analyst
eve akko-user eve123 (dev) Standard user
dave akko-viewer dave123 (dev) Dashboard viewer

emailVerified must be true

All users must have emailVerified=true in Keycloak. The oauth2-proxy service rejects users without a verified email, causing login failures for JupyterHub and other proxied services.

Admin Console

The Keycloak admin console is accessible at:

https://identity.akko.local/admin/

Admin credentials are defined in the Helm values (global.auth.keycloakAdminPassword). In dev mode, see helm/examples/values-dev.yaml.

From the admin console you can:

  • Manage users (create, disable, reset passwords)
  • Assign roles and groups
  • Configure OAuth2 clients
  • View active sessions
  • Monitor login events and errors

Adding a New User

  1. Open the admin console at https://identity.akko.local/admin/
  2. Select the akko realm (top-left dropdown)
  3. Navigate to Users > Add user
  4. Fill in:
    • Username (required)
    • Email (required)
    • First name, Last name
    • Toggle Email verified to ON
  5. Click Create
  6. Go to the Credentials tab and set a password
  7. Go to the Role mapping tab:
    • Click Assign role
    • Filter by realm roles
    • Select the appropriate role (akko-admin, akko-engineer, akko-analyst, akko-user, or akko-viewer)

Persistent configuration

User changes made in the admin console are stored in the Keycloak PostgreSQL database and survive restarts. They are not written back to realm-akko.json. To export the current realm state:

kubectl exec -n akko deploy/akko-keycloak -- /opt/keycloak/bin/kc.sh export \
    --dir /opt/keycloak/data/export \
    --realm akko

Adding a New Service Client

When adding a new service to AKKO that requires Keycloak authentication:

  1. Open the admin console and navigate to Clients > Create client
  2. Set the Client ID (e.g., my-service)
  3. Choose Client authentication = ON for confidential clients
  4. Configure Valid redirect URIs: https://my-service.akko.local/*
  5. Configure Web origins: https://my-service.akko.local
  6. Save and copy the client secret from the Credentials tab
  7. Add the client configuration to keycloak/realm-akko.json for version control

Known Issues

KC_HOSTNAME, not KC_HOSTNAME_URL

Keycloak 26.x uses hostname v2 configuration. The environment variable is KC_HOSTNAME (not KC_HOSTNAME_URL, which is v1 and silently ignored). Use KC_HOSTNAME_BACKCHANNEL_DYNAMIC: false for a consistent issuer across internal and external access.

Realm import is first-start only

The realm-akko.json file is imported when the Keycloak database is empty (first startup). Subsequent changes to the JSON file will not be applied automatically. Either re-import manually or make changes via the admin console.

Password persistence in PostgreSQL

Keycloak stores its data in PostgreSQL. If you regenerate the .env file with new passwords, the old Keycloak admin password persists in the database. You must either:

  • Reset via ALTER USER in PostgreSQL
  • Or delete the Keycloak volume: docker volume rm akko_keycloak-data