Manage roles and permissions

Manage server access permissions for users and groups in Alpacon.

Permission model#

Alpacon permissions work at two levels:

1. User roles (Workspace level)#

2. Server access permissions (Group-based)#

• Assign groups to servers
• All group members can access the server
• Users can belong to multiple groups

Role-based access control (RBAC)#

Workspace-level permissions (user roles described above) are managed through RBAC. Built-in RBAC roles correspond to the user role levels, while server access is primarily group-based—see Permission inheritance below for the full picture. You can also create custom roles for fine-grained permission control.

Built-in roles#

Built-in roles map to the user role levels and are automatically assigned:

Built-in roles are automatically assigned and managed by the system. Regular users (neither staff nor superuser) aren’t given a workspace-wide role; their access comes from group membership and any roles directly assigned to them.

Direct-login review#

External access uses permissions of its own. Every workspace comes with the reviewer, auditor and security_admin roles, which a Superuser assigns explicitly; admin is the built-in role Staff members get automatically. This is what each of them holds:

These roles work only when assigned workspace-wide. superuser holds every permission. For what each role sees in the console, see Roles and permissions.

Custom roles#

Create custom roles to define fine-grained permissions tailored to your organization’s needs. Custom roles support two scope levels:

• Global scope: The permission applies to all objects of the resource type
• Object scope: The permission is limited to specific resource types and objects

RBAC permissions#

Permissions follow the resource:action format (e.g., server:read, server:update). Assign permissions to roles, then assign roles to users or groups. The same vocabulary is used for token scopes, so every permission name is listed in the scopes reference.

Permission inheritance is additive—a user’s effective permissions are the union of all permissions from all assigned roles, including roles inherited through group membership.

Create and manage roles#

Only Superuser members can manage roles in Workspace settings → Roles.

Resource-scoped roles#

Resource-scoped roles come with Alpacon, like built-in roles, but each one covers a single resource, such as one server or one group, instead of the whole workspace.

Examples include server:maintainer and group:member. Each role’s description in the role list says how it is assigned.

Role list#

The role list displays all roles in the workspace, showing each role’s name, description, and created date.

Create a role#

1. Click New role
2. Enter the Name and Description for the role
3. Optionally, pick one or more Permission templates to fill in the role’s permissions
4. Save

A template is one of the presets in the scopes reference, and a role built from it gets every scope the template lists, whichever extensions are on. A role created without a template starts with no permissions. Assign permissions, users, and groups from the role detail page, where you can also change the permissions a template filled in.

Delete a role#

1. Navigate to the role detail page
2. Go to the Settings tab
3. Click Delete role
4. Confirm the deletion

Role detail page#

The role detail page has four tabs: Permissions, User assignments, Group assignments, and Settings.

Permissions tab#

Manage permissions assigned to this role. Each permission follows the resource:action format (e.g., server:read, server:update); the full list is in the scopes reference.

The permissions list shows the permission name, and whether it is scoped to a specific resource type and object.

You can search permissions using the search bar and filter by All or Assigned status.

Assign a permission:

1. Click Assign permission
2. Select a Permission from the dropdown
3. Optionally, check Limit to specific resource to restrict the permission to a specific resource type and object:
   • Select a Resource type from the dropdown
   • Select one or more Object entries from the checkbox list
   • If no objects are available for the selected resource type, the permission applies to all objects of that type
4. Save

Remove a permission:

Select the assignment and click Remove assignment to remove it from this role.

User assignments tab#

Manage users assigned to this role. The list shows each user’s name, email, and scope information.

Assign a user:

1. Click Assign user
2. Select a User from the dropdown
3. Optionally, configure the Scope to limit this role to a specific resource
4. Save

Remove a user assignment:

Select the assignment and click Remove assignment to remove it.

A Superuser’s admin assignment cannot be removed on its own—remove their superuser assignment first.

Group assignments tab#

Manage groups assigned to this role. When a role is assigned to a group, all members of that group inherit the role’s permissions.

Assign a group:

1. Click Assign group
2. Select a Group from the dropdown
3. Optionally, configure the Scope to limit this role to a specific resource
4. Save

Remove a group assignment:

Select the assignment and click Remove assignment to remove it.

Settings tab#

Edit the role’s name and description, or delete the role.

• Name: A unique name for this role
• Description: An optional description of the role’s purpose

Click Save to apply changes, or Delete role to permanently remove the role and all its assignments.

Set user roles#

How to change:

1. Select user in IAM > Users
2. Click Edit
3. Change Role
4. Click Save

Required permission: Staff or Superuser

Details: Manage users

Configure server access#

Access control via groups#

Step 1: Create groups

• Create groups

Step 2: Add users to groups

• Assign users

Step 3: Assign groups to servers

• Server group management

Set individual server permissions#

1. Select server in Servers page
2. Click Edit
3. Select Assigned groups
4. Click Save

All members of selected groups can access the server.

Feature permissions#

Websh (Terminal)#

Terminal access to servers assigned to group:

• Login as IAM username
• sudo access available

WebFTP (File management)#

File upload/download to servers assigned to group:

• Access user home directory
• Access other directories based on permissions

MFA required actions#

On Enterprise, Superusers can select these actions under Policies > Authentication to require fresh MFA. None are selected by default:

• Server actions: upgrading or restarting the agent, and installing alpamon-pam
• Web terminal: connecting as a system account other than your own
• Code editor: opening the editor as a system account other than your own
• File transfer: transferring files as a system account other than your own
• Command: running a command as a system account other than your own
• Approval decisions: approving or rejecting a request as a reviewer

Configure: Policies > Authentication

Permission examples#

Example 1: Development team server access#

Group: developers
Members: user1 (User), user2 (User), user3 (Staff)

Servers: dev-server-01, dev-server-02
Assigned groups: developers

Result: user1, user2, user3 all access both servers

Example 2: Production server restriction#

Group: senior-engineers
Members: user3 (Staff), user4 (Superuser)

Server: prod-server-01
Assigned groups: senior-engineers

Result: Only user3, user4 access production server

Permission inheritance#

Multiple group membership:

• If user belongs to groups A and B
• Can access all servers assigned to A and B

Roles and groups:

• Superuser (RBAC superuser) and Staff (RBAC admin) members access all servers, without group assignment

Server maintainers and object-scoped roles:

• A server’s maintainer can access it even without group assignment. A maintainer is a user who holds the server:maintainer role scoped to that server, either directly or as a member of a group the role is assigned to. An admin grants or revokes the role through the RBAC role API; registering a server or becoming its owner does not grant it. A server registered while Alpacon still granted the role automatically keeps that grant for the user who registered it. Assigned workspace-wide or scoped to a server group, the role does not make anyone a maintainer
• A maintainer can also connect as other existing accounts on the server, like an owner or manager of an assigned group
• Assigning a user or group a custom role that grants server:read, scoped to one server or to one of its groups (object scope), reaches that server the same way
• A user reached this way can also use the server as a work session or sudo policy target, like a group member

Role inheritance through groups:

• When a role is assigned to a group, all members of that group inherit the role’s permissions
• A user’s effective permissions are the union of all directly assigned roles and group-inherited roles

Security best practices#

Principle of least privilege:

• Grant minimum required permissions
• Regularly review and adjust permissions

Use groups:

• Manage permissions via groups rather than individual users
• Separate groups by environment, project

Limit Superusers:

• Keep Superuser role to minimum
• Grant only to trusted administrators

Audit logs#

All permission changes are logged:

• Who changed permissions and when
• Which user/group permissions were changed

Related docs#

• Manage users
• Manage groups
• Server group management
• Workspace settings