Defining user roles¶

WEISS uses two roles to differentiate what users can do:

Role	Description
Operator	Read-only access to repos. Can operate and view deployed OPI snapshots in runtime mode. Cannot edit files, commit, or deploy.
Developer	Full access. Can edit OPIs in the editor, commit changes, manage repositories, and deploy snapshots.

Role assignment is controlled by a roles.toml file on the server. Any authenticated user whose username is listed in that file is granted the developer role; everyone else is treated as an operator.

Note

A simple config file is a deliberate choice for the current scale of the system, where the number of users and roles changes infrequently and a full database service would be disproportionate overhead. If your deployment grows to the point where dynamic role management, audit trails, or per-repository permissions become necessary, this mechanism can be replaced with a database-backed solution without changing the rest of the application.

Setup¶

A template file is included in the repository at backend/api/roles.example.toml. Copy it to roles.toml in the same directory and edit it:

cp backend/api/roles.example.toml roles.toml

The file uses TOML format. Add the usernames of the users who should have the developer role under [roles]:

[roles]
developers = [
    "andre@example.com",
    "flavia@example.com",
]

Keep roles.toml out of version control - it is already listed in .gitignore.

Note

The username format depends on the authentication provider in use:

Microsoft Entra ID - use the user’s userPrincipalName (UPN), typically their organisational email address (e.g. username@example.com).
Other providers (e.g. LDAP, to be supported) - use the login name as it appears in the user’s session (e.g. username or DOMAIN\username).

Usernames are matched case-insensitively.

Mounting the file (Docker)¶

The compose files expect roles.toml to be mounted into the API container. By default, they look for it at ./roles.toml relative to the project root. If you want to keep it elsewhere, set ROLES_CONFIG_FILE in your .env file:

ROLES_CONFIG_FILE=/path/to/your/roles.toml

The file is mounted read-only at /config/roles.toml inside the container.

Applying changes without restarting¶

After editing roles.toml, you can reload it without restarting the server by calling the reload endpoint - no existing user sessions are interrupted:

curl -X POST https://<your-host>/api/v1/auth/admin/reload-roles \
     -H "Cookie: weiss_session=<your-session-cookie>"

This endpoint requires the caller to already have the developer role. The response includes the number of developer usernames loaded from the file:

{ "reloaded": true, "developer_count": 2 }

Role changes take effect on the next request made by each user - there is no need to force anyone to log out and back in.

Note

If roles.toml is not found when the server starts, a warning is logged and all users fall back to the operator role. The file can be created and loaded at any time using the reload endpoint above without restarting.