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.

Note

Where role-based visibility is enforced.

The roles you assign in Keycloak drive the backend artifact-permission rules, which filter the organizations, projects, versions and needs each role can see through the API. These rules can additionally be narrowed by artifact dimensions (dimensionFilters) so a role only sees versions whose dimension labels match – see ubtrace.dimensions and the “Permissions” section of the offline deployment guide (README-offline.md).

Page- and section-level content security inside the documentation (the secure field and .. secure:: directive in RST/Markdown) is a separate, currently paused mechanism – the sections describing it below are not yet active.

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

Managing artifact-permission rules

Artifact-permission rules decide which organizations, projects, versions, documents and need types each role can see. They are managed in the admin application under the Artifact permissions page (route /artifact-permissions). The version scope you have selected is reflected in the page URL, so a rules view can be bookmarked or shared.

  1. Open the admin application and go to Artifact permissions. The page lists every existing rule with its role, the glob patterns (organization, project, version, document, need type) and any dimension filters.

  2. Click New rule to open the rule editor. Enter a Role name and the glob patterns to match – for example acme-* for the organization, or * to match everything at that level. Click Save rule to create it.

  3. To remove a rule, click the delete icon on its row and confirm. Users in that role lose access to artifacts that only this rule granted; the action cannot be undone.

Note

Dimension filters (beta).

When the dimension-scoped access beta (artifact-dimensions) is enabled, the rule editor also shows a dimension filters section. Adding filters there (for example ecu=hpc) narrows the rule to versions whose dimension labels match – see ubtrace.dimensions. When the beta is off, the editor simply omits this section and any dimension filters already on a rule are left untouched.