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). The documentation navigation tree follows the same rules: a role only sees the entries for documents it may open, so a restricted user cannot read the titles of documents its rules exclude.

What a need-type pattern does and does not cover. A rule pairs a document pattern with a need-type pattern, and the pair is one grant: a need is visible only when a single rule matches both its document and its type. The need-type half applies to need-level surfaces – need reads, the traceability graph, search results, metrics and the need-type list. It does not redact document bodies: a rendered documentation page contains the needs authored on it, and access to a page is decided by the document pattern alone. So a role granted every document but only one need type can still read the rendered text of the other types on those pages. To keep a need type unreadable, restrict the document pattern to pages that do not contain it. The reverse asymmetry also holds, for the same reason: the list of need types in a version carries no document, so it is decided by the need-type pattern alone.

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.