RBAC & Roles

ARXsec enforces role-based access control (RBAC) on every API endpoint. Every authenticated request is checked against the user's assigned role before the endpoint logic executes. This guide covers the four built-in roles, the permission matrix, role assignment, and integration with SCIM group-to-role mapping.

Roles

ARXsec defines four roles, each representing a distinct level of platform access:

Role Description
admin Full platform access. Can manage organization settings, users, encryption keys, SIEM integrations, IP allowlists, notification channels, and all operational functions.
deployer Operational access. Can create, configure, deploy, and manage agents and connectors. Cannot modify organization-level security settings.
auditor Read-only access to audit logs, compliance reports, and operational data. Can view agents and deployments but cannot modify them.
viewer Minimal read-only access. Can view agents, dashboards, and status information. Cannot access audit logs or security settings.

Permission Matrix

The following table shows which endpoint categories each role can access. The require_role decorator is applied to every endpoint, and the allowed roles are specified per endpoint.

Endpoint Category admin deployer auditor viewer
Organization Settings
IP allowlist (CRUD) Yes No No No
SIEM integrations (CRUD) Yes No No No
Encryption / CMEK config Yes No No No
Notification channels (CRUD) Yes No No No
User Management
List / manage users Yes No No No
Manage API keys Yes Yes No No
Agent Operations
List agents Yes Yes Yes Yes
Create / update agents Yes Yes No No
Deploy agents Yes Yes No No
Delete agents Yes No No No
Connector Management
List connectors Yes Yes Yes Yes
Create / update connectors Yes Yes No No
Delete connectors Yes No No No
Approvals
View approval requests Yes Yes Yes Yes
Review (approve/deny) Yes Yes No No
Audit & Compliance
View audit logs Yes No Yes No
Export audit data Yes No Yes No
Dashboards & Status
View dashboards Yes Yes Yes Yes
View agent status Yes Yes Yes Yes

How RBAC Is Enforced

RBAC is enforced at the API layer using the require_role decorator. This decorator wraps every endpoint handler and checks the authenticated user's role field against the list of allowed roles before the handler executes.

@router.post("/agents/{agent_id}/deploy")
@require_role(["admin", "deployer"])
async def deploy_agent(agent_id: UUID, current_user: User = Depends(get_current_user)):
    ...

If the user's role is not in the allowed list, the API returns:

{
  "detail": "Requires one of roles: admin, deployer"
}

with HTTP status 403 Forbidden.

The User object carries the role throughout the request lifecycle:

class User:
    id: UUID
    org_id: UUID
    email: str
    role: str
    full_name: str | None

    def has_role(self, roles: list[str]) -> bool:
        return self.role in roles

Role Assignment

Roles can be assigned through three mechanisms:

1. Direct Assignment

Administrators can set a user's role directly by updating the role field in the users table. This is the simplest method and is suitable for small teams.

2. JIT Provisioning Default

When a user is provisioned via SAML or OIDC SSO for the first time (JIT provisioning), they are assigned the viewer role by default. An administrator must manually upgrade their role if they need elevated permissions.

3. SCIM Group-to-Role Mapping

For automated role management at scale, SCIM groups can be mapped to ARXsec roles. When a group has a role_mapping field set, all members of that group automatically receive the mapped role.

The mapping works as follows:

  1. The IdP pushes a group to ARXsec via SCIM (e.g., "ARXsec Deployers").
  2. If the group name contains a valid role keyword, ARXsec sets role_mapping automatically.
  3. When users are added to the group, their role in the users table is updated.
  4. When group membership is modified (add, remove, replace), role synchronization runs for all current members.

Example group-to-role mappings:

IdP Group Name ARXsec Role
ARXsec Admins admin
ARXsec Deployers deployer
Security Auditors auditor
ARXsec Viewers viewer

For groups that do not follow the naming convention, the role_mapping field can be set manually by an administrator.

Role Hierarchy

ARXsec does not implement role inheritance. Each role is a flat set of permissions. The admin role is not a superset of deployer by design -- both must be explicitly listed in the require_role decorator for endpoints that both roles should access.

This means:

Organization Scoping

All RBAC checks are additionally scoped to the user's organization (org_id). A user with the admin role in Organization A cannot access resources belonging to Organization B. This scoping is enforced at the database query level.

Denied Access Logging

When a user is denied access due to insufficient role permissions, the event is logged with structured logging:

auth.rbac.denied  user_id=<uuid>  role=viewer  required_roles=["admin", "deployer"]

These events can be forwarded to your SIEM integration for security monitoring and alerting.

Best Practices