Keycloak

Feature availability

Feature	Support
User management	✅ Full
Organizations	✅ Native (requires Keycloak 26.6+ with Organizations enabled)
Audit logs	✅ Basic (requires Events enabled in realm)

Setup

1. Create or choose a realm

   In the Keycloak Admin Console, create a dedicated realm for your application users (e.g. my-app) or use an existing one.

   Note the realm name — you will need it as KEYCLOAK_REALM.

2. Create a service account client

   In your realm: Clients → Create client.

   • Client type: OpenID Connect
   • Client ID: aums-management (or any name you prefer)
   • Client authentication: On (confidential)
   • Service accounts roles: Enabled
   • Standard flow / Direct access grants: Off (not needed)

3. Grant realm management permissions

   Go to the client → Service accounts roles tab → Assign role.

   Filter by realm-management client and assign:

   • manage-users — create, update, delete, disable users
   • view-users — list and read users
   • query-users — required for search

   For audit log access, also assign:

   • view-events — read realm events

   For organization management, also assign:

   • manage-organizations — create, update, delete organizations and manage members

4. Copy the client secret

   Go to the client → Credentials tab. Copy the Client secret.

5. Set environment variables

   PROVIDER=keycloak
   KEYCLOAK_BASE_URL=https://keycloak.example.com
   KEYCLOAK_REALM=my-app
   KEYCLOAK_CLIENT_ID=aums-management
   KEYCLOAK_CLIENT_SECRET=your-client-secret

Tip

KEYCLOAK_BASE_URL is the root URL of your Keycloak server, without a trailing slash (e.g. https://auth.example.com). AUMS will automatically scope all requests to the configured realm.

Organizations

Keycloak Organizations (introduced in Keycloak 26.0, stable in 26.6+) are supported natively. AUMS maps Keycloak organizations to its organization model:

AUMS field	Keycloak field
id	id
name	name
displayName	alias
description	description

Prerequisites:

1. Keycloak version 26.6.0 or later.
2. Organizations feature enabled in your realm: Realm settings → General → Organizations → On.
3. Service account has the manage-organizations role (see Setup step 3).

Note

Organization member roles are managed at the realm level in Keycloak, not at the organization level. Members listed in AUMS will show no organization-scoped roles; use Keycloak’s Admin Console to assign realm roles.

Invitations are sent via email using Keycloak’s built-in invitation flow. Ensure your realm has a working email provider configured (Realm settings → Email) before using the invite feature.

Support actions, attributes and roles

AUMS lists a user’s sessions and signs them out, resets their second factors (OTP, WebAuthn, recovery codes), unlinks federated identities, edits their attributes and assigns realm roles. Roles Keycloak gives everyone (default-roles-*, offline_access, uma_authorization) are not offered.

• Emails (password reset, verification) go through the realm’s email settings (Realm settings, Email): configure an SMTP server first, or sending fails.
• Attributes are kept only if the realm’s user profile allows undeclared ones: enable Unmanaged attributes (Realm settings, General). Without it Keycloak accepts the change and drops the attributes; AUMS reports that instead of a success.
• The service account needs the realm-management roles for users, realm roles and, for organizations, organizations.
• Organizations without a domain need Keycloak 26.1 or later.

Audit logs

Keycloak audit logs are read from the realm Events store. Events must be enabled in the realm settings:

1. Go to Realm settings → Events tab.
2. Enable Save events.
3. Optionally extend Expiration to retain events longer (default: 1 day).
4. Select the event types you want to track under Saved event types.

Once enabled, AUMS will surface user events (logins, failures, password resets, etc.) on the Audit Logs page, with filtering by user, event type, and date range.

Note

Admin events (user created/updated/deleted by an admin) are tracked separately in Keycloak and are not currently surfaced in AUMS. Only user-initiated events are shown.

OIDC login (optional)

To protect the AUMS dashboard with Keycloak SSO, create a separate OpenID Connect client in Keycloak (standard flow, not service account):

AUTH_CLIENT_OPENID_CONFIGURATION_URL=https://keycloak.example.com/realms/my-app
AUTH_CLIENT_ID=aums-dashboard
AUTH_CLIENT_SECRET=your-oidc-client-secret

Add <BASE_URL>/api/auth/callback/oidc to the client’s Valid redirect URIs.