RBAC & Roles

arxsec-site product-docs docs/admin/rbac.md

ARX 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

ARX 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. Can create API keys and review approvals. 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.

``python @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:

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

with HTTP status 403 Forbidden.

The User object carries the role throughout the request lifecycle:

```python 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 ARX 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:

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

| IdP Group Name | Auto-Mapped Role | |---|---| | "ARX Admins" | admin | | "ARX Deployers" | deployer | | "Security Auditors" | auditor | | "ARX Viewers" | viewer |

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

Role Architecture

ARX 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:

Moving a user from deployer to auditor revokes all deployment permissions and grants audit access.
There is no "escalation path" where a lower role can perform actions of a higher role.
Endpoint authors must explicitly list every role that should have access.

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

Principle of least privilege. Assign the minimum role required for each user's job function.
Use SCIM groups for role management. Automate role assignment through IdP group membership rather than manual assignment.
Reserve admin for platform administrators. Day-to-day operational work should use the deployer role.
Use auditor for compliance teams that need to review logs without the ability to modify resources.
Separate service accounts. Create dedicated service account users with specific roles for API key-based integrations.
Audit role assignments regularly. Review the users table periodically to ensure role assignments are current.
Monitor RBAC denials. Configure SIEM alerts on auth.rbac.denied events to detect potential unauthorized access attempts.