Skip to content

SSO setup: Keycloak➧

Overview

Step-by-step setup of WildcoreDMS sign-in through Keycloak. General description (how SSO works, roles, common errors) is on the Single Sign-On page.

Examples below use:

  • WildcoreDMS address — https://dms.example.com;
  • Keycloak address — https://sso.example.com, realm — main;
  • Client ID — wildcore.

What you need to know up front➧

Parameter Value
Redirect URI https://dms.example.com/api/v1/auth/oidc/callback
Configuration address (Keycloak 17+) https://sso.example.com/realms/main/.well-known/openid-configuration
Configuration address (before 17 or with /auth) https://sso.example.com/auth/realms/main/.well-known/openid-configuration
Groups claim (recommended) resource_access.wildcore.roles — client roles

Keycloak public address

Keycloak builds the issuer from the request address. Fix the public address with KC_HOSTNAME / --hostname (Keycloak 17+) or the Frontend URL field in Realm settings (older versions), and make sure the WildcoreDMS server reaches Keycloak at the same address as the browser.

There are two ways: the quick one — importing a JSON generated by the WildcoreDMS wizard, and the manual one — through the Keycloak UI.

The WildcoreDMS wizard generates a file that creates the client, the mapper and roles for all WildcoreDMS roles in the realm with a single import.

On the WildcoreDMS server:

  1. Run sudo wca auth:configure, choose sign-in methods (internal,oidc) and the keycloak provider.
  2. Enter https://sso.example.com/realms/main/.well-known/openid-configuration.
  3. Client ID — any, e.g. wildcore (the client is created by the import). Client secret may be left empty — the wizard generates it and writes it both to the JSON and to the WildcoreDMS settings.
  4. Groups claim — keep the default resource_access.wildcore.roles (client roles). Alternatives: realm_access.roles (realm roles) or groups (Keycloak groups).
  5. Answer yes to Generate Keycloak partial import JSON and select the WildcoreDMS roles to create in Keycloak. Names are taken from the role's "SSO groups mapping" field; if it's empty, they are transliterated (Офіс Менеджер → ofis-menedzher) and saved into the role mapping.
  6. The wizard prints the JSON and saves it to var/keycloak-import-wildcore.json (the full path is shown in the output). Copy the file to your computer.

In the Keycloak admin console:

  1. Select realm main (realm list in the top left corner).
  2. Realm settings → Action button (top right) → Partial import.
  3. Upload the JSON file, select resources (Clients, Roles/Groups) → Import.
  4. Assign roles to users: Users → user → Role mapping tab → Assign role → Filter by clients → select wildcore client roles → Assign. (If you chose groups, add users to groups: Users → user → Groups → Join Group.)
  5. Make sure users have an Email (Users → user → Details).

A separate Client ID for every installation

If the client already exists, Overwrite on import replaces its secret — and every installation using it stops signing in. Use separate Client IDs, e.g. wildcore-dms and wildcore-dms-dev.

Option 2. Manual setup through the UI➧

Keycloak 19+ (new admin console)➧

1. Create the client

  1. Select the realm → Clients → Create client.
  2. General settings:
    • Client type — OpenID Connect;
    • Client ID — wildcore;
    • Name — WildcoreDMS (any) → Next.
  3. Capability config:
    • Client authentication — On (makes the client confidential);
    • Authorization — Off;
    • Authentication flow — only Standard flow (uncheck Direct access grants, Implicit flow, Service accounts roles);
    • PKCE Method (if your version has it) — S256 → Next.
  4. Login settings:
    • Valid redirect URIs — https://dms.example.com/api/v1/auth/oidc/callback;
    • Root URL / Home URL — https://dms.example.com (optional);
    • Web origins — may stay empty → Save.
  5. Open the Credentials tab: Client Authenticator — Client Id and Secret, copy the Client secret.
  6. (Optional, for older 19+ without the PKCE field) Advanced tab → Advanced settings → Proof Key for Code Exchange Code Challenge Method — S256 → Save.

2. Roles for WildcoreDMS

  1. Clients → wildcore → Roles tab → Create role.
  2. Role name — the name to map to a WildcoreDMS role, e.g. administrator, operator, installer → Save. Repeat for each role.

3. Mapper — roles in the ID token

By default Keycloak puts roles only into the access token, while WildcoreDMS reads the ID token and userinfo, so a mapper is required:

  1. Clients → wildcore → Client scopes tab → wildcore-dedicated.
  2. Configure a new mapper (or Add mapper → By configuration) → User Client Role.
  3. Fill in:
    • Name — client roles;
    • Client ID — wildcore;
    • Multivalued — On;
    • Token Claim Name — resource_access.${client_id}.roles;
    • Claim JSON Type — String;
    • Add to ID token — On, Add to access token — On, Add to userinfo — On → Save.

Other group sources:

Source Mapper type Token Claim Name Groups claim in WildcoreDMS
Client roles (recommended) User Client Role, Client ID wildcore, Multivalued On resource_access.${client_id}.roles resource_access.wildcore.roles
Realm roles User Realm Role, Multivalued On realm_access.roles realm_access.roles
Groups Group Membership, Full group path Off groups groups

With Full group path On groups come as /wca-admins — then use the leading slash in the role mapping as well.

4. Assign roles to users

Users → user → Role mapping tab → Assign role → Filter by clients → wildcore client roles → Assign. Make sure the user has an Email.

5. Check the token

Clients → wildcore → Client scopes → Evaluate tab → select a user → Generated ID token. The token must contain email, preferred_username and resource_access.wildcore.roles.

Keycloak before 19 (old admin console)➧

  1. Realm → Clients → Create: Client ID wildcore, Client Protocol openid-connect → Save.
  2. Settings tab:
    • Access Type — confidential;
    • Standard Flow Enabled — On, Implicit Flow / Direct Access Grants / Service Accounts — Off;
    • Valid Redirect URIs — https://dms.example.com/api/v1/auth/oidc/callback → Save.
  3. Credentials tab → copy the Secret.
  4. Roles tab → Add Role — create roles for WildcoreDMS.
  5. Mappers tab → Create: Mapper Type User Client Role, Client ID wildcore, Multivalued On, Token Claim Name resource_access.${client_id}.roles, Add to ID token On, Add to userinfo On → Save.
  6. For users: Users → user → Role Mappings → Client Roles wildcore → Add selected.

Configure WildcoreDMS➧

sudo wca auth:configure

Choose the keycloak provider, enter the configuration address, Client ID and Client secret, groups claim resource_access.wildcore.roles. Or manually in /opt/wildcore-dms/.env:

AUTH_METHODS=internal,oidc
OIDC_NAME=Keycloak
OIDC_ISSUER=https://sso.example.com/realms/main
OIDC_CLIENT_ID=wildcore
OIDC_CLIENT_SECRET=<Client secret>
OIDC_LOGIN_CLAIM=preferred_username
OIDC_GROUPS_CLAIM=resource_access.wildcore.roles
OIDC_MATCH_BY=email
OIDC_SYNC_ROLE=yes

and run sudo wca system:http:reset.

Then in the WildcoreDMS web panel: Users management > Roles → Edit → "SSO groups mapping" — enter Keycloak role names (if they match the role names, the field may stay empty — see Roles).