User Management

ubTrace uses Keycloak as its identity provider (via OpenID Connect) to manage user authentication and authorization. Users, roles, and groups are managed through the Keycloak Admin Console – not in Sphinx conf.py files.

Note

How secure is it?

ubTrace can grant access to pages and specific areas of a page.

If a secured area contains an image, this image is not shown to the user, if the user does not have the needed permissions. However, this image may still be available in the _static/ folder or at some other places, which are not secured by ubTrace and can be browsed by the user without any restrictions.

User handling

Users are managed in Keycloak and authenticate via OIDC. The ubTrace backend validates access tokens issued by Keycloak and enforces role-based permissions.

Creating users

  1. Open the Keycloak Admin Console at your configured KC_HOSTNAME URL (default: http://localhost:7181, see Environment Variables)

  2. Log in with the admin credentials

  3. In the left sidebar, click Manage realms, then select ubtrace (you’ll land on the “Welcome to ubtrace” page)

  4. Navigate to Users → Add user

  5. Fill in the required fields (username, email) and click Create

  6. Go to the Credentials tab and set a password

For production deployments, you can also connect Keycloak to external identity providers (LDAP, Active Directory, SAML, social logins) through its federation features.

Roles & Permissions

Roles and permissions control access to secured content within the documentation.

Keycloak manages user-to-role assignments.

Assigning roles

  1. In Keycloak Admin Console, navigate to Realm roles

  2. Create roles that match your content permission scheme (e.g., internal, customer, admin)

  3. Assign roles to users via Users > select user > Role mapping