Skip to content

roles-and-access-control.md

Latest commit

 

History

History
238 lines (168 loc) · 8.72 KB

roles-and-access-control.md

File metadata and controls

238 lines (168 loc) · 8.72 KB

Roles and Access Control

Role hierarchy

rustguac implements a 4-tier role hierarchy:

Role Level Description
admin 4 Full access — manage users, connections, recordings, sessions, group mappings, all API tokens
poweruser 3 Ad-hoc session creation + connections connect + self-service API tokens
operator 2 Connections connect only (no ad-hoc sessions); can view own API tokens
viewer 1 Read-only — view sessions and recordings; no API token access

Roles are hierarchical: each role includes all permissions of lower roles. For example, a poweruser can do everything an operator can, plus create ad-hoc sessions.

Authentication paths

rustguac supports three authentication methods, tried in order: admin API key, user API token, OIDC session cookie.

API key admins

API key holders always have full admin access (level 4). There is no way to restrict an API key to a lower role. API keys are intended for automation, CI/CD, and system administration.

# Create an API key admin
rustguac add-admin --name automation

# With IP restrictions and expiry
rustguac add-admin --name ci-bot \
  --allowed-ips "10.0.0.0/8,192.168.1.0/24" \
  --expires "2026-12-31T00:00:00Z"

User API tokens

User API tokens authenticate as the OIDC user who owns the token, with an effective role capped by the token's max_role. Tokens use the same Authorization: Bearer <token> header as admin API keys — rustguac tries admin keys first, then user tokens. See User API tokens below for details.

OIDC users

OIDC users are assigned a role through three mechanisms (in order of precedence):

  1. Group-to-role mappings — evaluated on every OIDC login. If the user's OIDC groups match any mappings, the highest matching role is applied.
  2. Manual role assignment — admins can set a user's role via CLI, API, or the Admin page.
  3. Default role — new users get the default_role from OIDC config on first login (default: operator).

Endpoint access control

Session management

Endpoint Required role Notes
POST /api/sessions poweruser Create ad-hoc sessions
GET /api/sessions operator List all sessions
GET /api/sessions/:id operator View session details
DELETE /api/sessions/:id operator Non-admins can only delete their own sessions

Connections

Endpoint Required role Notes
GET /api/addressbook/folders operator Filtered by OIDC group membership
GET /api/addressbook/folders/:scope/:folder/entries operator Requires folder group access
POST .../entries/:entry/connect operator Creates session from connections entry
POST /api/addressbook/folders admin Create folders
PUT /api/addressbook/folders/:scope/:folder admin Update folder config
DELETE /api/addressbook/folders/:scope/:folder admin Delete folders
POST .../entries admin Create entries
PUT .../entries/:entry admin Update entries
DELETE .../entries/:entry admin Delete entries

Recordings

Endpoint Required role Notes
GET /api/recordings operator List recordings
GET /api/recordings/:name operator Download/play recording
DELETE /api/recordings/:name admin Delete recording

User management

Endpoint Required role
GET /api/users admin
PUT /api/users/:email/role admin
DELETE /api/users/:email admin
POST /api/users/:email/disable admin
POST /api/users/:email/enable admin
DELETE /api/users/:email/sessions admin

Group-to-role mappings

Endpoint Required role
GET /api/admin/group-mappings admin
POST /api/admin/group-mappings admin
PUT /api/admin/group-mappings/:id admin
DELETE /api/admin/group-mappings/:id admin

User API tokens (self-service)

Endpoint Required role Notes
POST /api/me/tokens poweruser Create a personal API token
GET /api/me/tokens operator List own tokens (metadata only)
DELETE /api/me/tokens/:id poweruser Revoke own token

Operators can view their tokens (created by an admin on their behalf) but cannot create or revoke them.

User API tokens (admin)

Endpoint Required role Notes
POST /api/admin/user-tokens admin Create token for any user
GET /api/admin/user-tokens admin List all user tokens
DELETE /api/admin/user-tokens/:id admin Revoke any user token
GET /api/admin/token-audit admin View token audit log

Public endpoints

Endpoint Auth required Notes
GET /api/health None Always returns 200
GET /api/auth/status None Returns OIDC enabled status
GET /api/me Any authenticated Returns current user info

Folder access control

Connections folders have group-based access control. Each folder has an allowed_groups list stored in its .config entry in Vault.

  • Admins bypass group checks and see all folders
  • Operators and powerusers see only folders where their OIDC groups intersect with the folder's allowed_groups
  • If allowed_groups is empty, all authenticated users can see the folder

Example

A folder with allowed_groups: ["engineering", "devops"]:

  • A user with OIDC groups ["engineering", "marketing"] can access it (engineering matches)
  • A user with OIDC groups ["marketing", "sales"] cannot access it (no match)
  • An admin can always access it regardless of groups

Group-to-role mappings

Admins can configure automatic role assignment based on OIDC group membership. This is managed in the Admin page or via the API.

How it works

  1. When a user logs in via OIDC, their group memberships are extracted from the JWT
  2. Each group is checked against the group_role_mappings table
  3. If any groups match, the highest role among all matches is applied
  4. If no groups match, the user's existing role is preserved

Example

OIDC Group Mapped Role
sysadmin admin
engineering poweruser
support operator

A user with groups ["engineering", "support"] would get poweruser (the higher of the two matching roles).

User API tokens

User API tokens allow OIDC users to authenticate via bearer token for automation and scripting (e.g., creating ad-hoc sessions via CI/CD, or integrating with monitoring tools).

Who can create tokens

User role Self-service Admin creates for them
admin Yes Yes
poweruser Yes Yes
operator No Yes
viewer No No

The primary use case is powerusers creating tokens for service account automation, and admins creating tokens for select operators who need API access.

Effective role

Each token has an optional max_role cap. When the token is used to authenticate, the effective role is:

effective_role = min(user_current_role, token_max_role)

This means:

  • A poweruser who creates a token with max_role: operator gets operator-level access when using that token
  • If an admin later demotes the user to operator, the token's effective access drops accordingly
  • The max_role can never grant more access than the user currently has

Token management UI

  • Tokens page (/tokens.html) — self-service for powerusers and admins to create, view, and revoke their own tokens. Operators can view tokens created for them.
  • Admin page (/admin.html) — admins can create tokens for any user, view all tokens across all users, revoke any token, and view the audit log.

User management CLI

# List all OIDC users
rustguac list-users

# Set a user's role
rustguac set-role --email user@example.com --role poweruser

# Disable a user (blocks login)
rustguac disable-user --email user@example.com

# Re-enable a user
rustguac enable-user --email user@example.com

# Delete a user
rustguac delete-user --email user@example.com

Admin (API key) management CLI

# Create an admin
rustguac add-admin --name myadmin

# With IP restrictions
rustguac add-admin --name myadmin --allowed-ips "10.0.0.0/8,192.168.1.0/24"

# With expiry
rustguac add-admin --name myadmin --expires "2026-12-31T00:00:00Z"

# List admins
rustguac list-admins

# Disable/enable
rustguac disable-admin --name myadmin
rustguac enable-admin --name myadmin

# Rotate key (generates new key, invalidates old immediately)
rustguac rotate-key --name myadmin

# Delete
rustguac delete-admin --name myadmin