Administrator Role-Based Access Control (RBAC)

Administrator Role-Based Access Control (RBAC) in RADKit Service allows fine-grained control over what actions different administrator users can perform within the system. Instead of giving all administrators the same level of access, RBAC uses a role-based system where administrators are assigned specific roles that define their permissions.

Overview 

The Administrator RBAC system works by:

Roles: Defined sets of permissions that can be assigned to administrators
Claims/Permissions: Individual permissions that define specific actions (e.g., “READ_DEVICES”, “MODIFY_ADMINS”)
Role Assignment: Administrators are assigned one role that determines their level of access

This system replaces the previous direct assignment of individual permissions to administrators, providing a more manageable and scalable approach to access control.

Built-in Roles 

RADKit Service comes with two built-in roles that cannot be deleted:

basic-admin

A standard administrator role with access to core functionality including:

Read and modify devices
Read and modify remote users
Read and modify labels
Read logs
Read activity
Read settings
Read device templates
Read external sources

sysadmin

A system administrator role with full access to all functionality. System administrators bypass all permission checks and can perform any action in the system, including:

Full system configuration access
Access to all administrative functions

Note

The superadmin user (created during initial bootstrap) operates outside the role system and has unrestricted access to all functionality.

Available Permissions (Claims)

The system defines the following permissions that can be assigned to roles:

Device Management

READ_DEVICES: View device inventory and properties
MODIFY_DEVICES: Add, update, and delete devices

User Management

READ_REMOTE_USERS: View remote users
MODIFY_REMOTE_USERS: Add, update, and delete remote users

Administrator Management

READ_ADMINS: View administrator accounts
MODIFY_ADMINS: Create, update, and delete administrator accounts

Role Management

READ_ROLES: View roles and their permissions

Label Management

MODIFY_LABELS: Create, update, and delete labels

System Management

READ_ROLES: View roles of other administrators
READ_LOGS: Access system logs
READ_ACTIVITY: View active connections and system activity
MODIFY_ACTIVITY: Cancel active connections
READ_EXTERNAL_SOURCES: View external authentication sources
READ_SETTINGS: View system settings
MODIFY_SETTINGS: Modify system settings
READ_DEVICE_TEMPLATES: View device templates

Warning

Role and claim/permissions management (creating, updating, deleting roles) is restricted to system administrators only. The same applies to creating, updating and deleting device templates and external sources.

Permission Hierarchy 

The system implements a permission hierarchy where certain permissions automatically grant access to related permissions:

MODIFY_DEVICES automatically includes READ_DEVICES
MODIFY_REMOTE_USERS automatically includes READ_REMOTE_USERS
MODIFY_ADMINS automatically includes READ_ADMINS
MODIFY_ACTIVITY automatically includes READ_ACTIVITY
MODIFY_SETTINGS automatically includes READ_SETTINGS

Creating Custom Roles 

System administrators can create custom roles to meet specific organizational needs.

Creating roles using Service WebUI 

Navigate to the Roles management page in the RADKit Service UI
Click the “Add Role” button
Fill in the role details:
- Name: A unique identifier for the role (alphanumeric characters, hyphens, and underscores allowed)
- Description: A descriptive explanation of the role’s purpose
- Permissions: Select the specific permissions this role should have
Click “Save” to create the role

Note

Role names must be unique. Choose descriptive names that clearly indicate the role’s purpose.

Creating roles using Control API 

Roles can also be created programmatically using the Control API:

from radkit_service.control_api import ControlAPI
from radkit_service.permissions import Claim

with ControlAPI.create(
    base_url="https://localhost:8081/api/v1",
    admin_name="superadmin",
    admin_password=...
) as service:
    # Create a role for device administrators
    role_result = service.create_role(
        name="device-admin",
        description="Role for managing devices",
        claims={Claim.READ_DEVICES, Claim.MODIFY_DEVICES, Claim.READ_SETTINGS}
    )

    if role_result.success:
        print(f"Created role: {role_result.result.name}")
    else:
        print(f"Failed to create role: {role_result.error}")

Assigning Roles to Administrators 

Administrators can be assigned roles during creation or through updates to existing administrator accounts.

Assigning roles during admin creation 

When creating a new administrator account, you can specify the role:

Navigate to the Administrator management page
Click “Add Administrator”
Fill in the administrator details (username, password, email, etc.)
In the “Role” section, select the appropriate role from the dropdown
Click “Save” to create the administrator with the assigned role

Note

If no role is specified during administrator creation, the administrator will be created without any role assignment and will have no permissions until a role is explicitly assigned.

Updating administrator roles 

To change an existing administrator’s role:

Navigate to the Administrator management page
Find the administrator and click “Edit”
In the role selection dropdown, choose the new role
Click “Update” to apply the changes

Warning

Administrators cannot modify their own role assignments. Role changes must be performed by another administrator with sufficient permissions.

Role Management via Control API 

The Control API provides comprehensive role management capabilities:

List all roles

roles_result = service.list_roles()
if roles_result.success:
    for role in roles_result.result:
        print(f"Role: {role.name} - {role.description}")
        print(f"Permissions: {', '.join(role.claims)}")
        print(f"Read-only: {role.readOnly}")

Update a role

update_result = service.update_role(
    role_id=3,
    name="updated-role-name",
    description="Updated description",
    claims={Claim.READ_DEVICES, Claim.READ_SETTINGS}
)

Delete a role

delete_result = service.delete_role(role_id=3)

Warning

When a role is deleted, all administrators assigned to that role will have their role assignment removed (set to None). This effectively removes their permissions until a new role is assigned.

Permission Enforcement 

The RBAC system enforces permissions at multiple levels:

API Endpoint Protection: Each API endpoint checks that the requesting administrator has the required permissions before allowing access.
UI Element Visibility: The web interface dynamically shows or hides UI elements based on the administrator’s permissions.
Database Operations: Database operations verify permissions before executing changes.
Audit Logging: All permission checks and administrative actions are logged for security auditing.

System Administrator Privileges 

System administrators (those assigned to roles with isSysadmin=True) have special privileges:

Bypass all individual permission checks
Can create, update, and delete roles
Can modify other administrators’ permissions
Have full access to all system functionality
Cannot have their system administrator status removed through role changes (requires direct modification)

Warning

Be very careful when assigning system administrator roles, as they provide unrestricted access to the entire system.

Note

All role management operations are logged in the system audit logs for security and compliance purposes.