[RFD - 0002] - Custom User Roles

[AleksandarCole]

[RFD - 0002] - Custom User Roles

Authors	State
@darkofabijan @AleksandarCole @VeljkoMaksimovic @mattrym	In progress

What

Semaphore currently employs role-based access control, where users can have different predefined roles at both the organization level and the project level.

Custom User Roles is a proposed feature that will allow organizations to create their own user roles, assign specific permissions to those roles, and apply them at both the organization and project levels.

Why

While the default roles available on Semaphore suit most users, there have been several use cases and organization types that require custom adjustments to permissions. Organizations with a large number of members, as well as those adhering to security standards like SOC 2, often need more granular control over permissions.

Implementing this feature would provide maximum flexibility, allowing users to fully customize access rights within their Semaphore organization.

---

Use-cases

Case 1 - Organization secrets access

The default Member role in an organization includes access to the organization secrets page. Several organizations prefer restricting this access to Admin or higher roles, adhering to the principle of least privilege. This restriction helps these organizations comply with their security policies more easily.

However, other organizations rely on the member role having this access, as it aligns with their workflow. Changing this default behavior could cause disruptions for them.

Case 2 - No ssh access for Contributor role in the project

The default Contributor role in an organization allows users to SSH into jobs. Some organizations prefer to restrict this capability to those with the Admin role on a project, enhancing security and control over sensitive operations.

---

Solutions

⚠ NOTE
The implementation of this project has already been kicked off.

Semaphore team working on a project can find links to the: Architecture details, wireframe and tasks breakdown [HERE].(https://renderedtext.operately.com/projects/b1ae334e-848c-4700-9b14-c0302df184cf)

Based on the results of the security review, these details will not be public.

However, we're describing the solution and functionality in more detail below.

Role Management Page - Summary

With the rollout of Project roles and Groups the backend system has been switched to full RBAC.

This allows us to create a new page in Organization Settings that would allow users to manage roles within Semaphore.

Within this page, for both organization and project roles users should be able to:

• View existing roles
• Create new roles
• Edit user created roles
• Edit default Semaphore roles (not available in v1)
• Delete user created roles
• Delete default Semaphore roles (not available in v1)

UI and Navigation

Roles main page

On this page user can see all the roles that exist.

1. Page is located in the organization settings
2. It is a new section in the settings side menu
3. User can create new roles
4. See existing roles including the quick overview of number of permissions assigned
5. View/Edit the existing role - this will open the Role single page

Roles single page

This page is used to create a new role or edit/view existing one.

User can select:

• Role name
• Role description
• Permissions that the role will have within the role scope (organization or project)
• Organization roles only: (optional) default project role that will be assigned.

roles_single.mov

⚠ Default project role

When creating the organization role, user can decide to automatically give access to all projects to the users with such role assigned. For example, by default all users that have owner organization role are automatically assigned admin role on every project within organization.

Organization Role Permissions

List of the permissions that can be assigned to the organization role:

• organization.activity_monitor.view - View organization's activity monitor.
• organization.audit_logs.manage - Manage audit log settings for the organization (such as log streams).
• organization.audit_logs.view - View audit logs.
• organization.change_owner - Change the owner of the organization.
• organization.contact_support - Contact support on behalf of the organization.
• organization.custom_roles.manage - Modify definition of roles within the organization.
• organization.custom_roles.view - View roles within the organization and permissions they carry.
• organization.dashboards.manage - Create new dashboard views.
• organization.dashboards.view - View the existing dashboards within the organization.
• organization.delete - Delete the organization.
• organization.general_settings.manage - Manage general settings of the organization.
• organization.general_settings.view - View general settings for the organization.
• organization.groups.manage - Manage groups within the organization and modify group members.
• organization.groups.view - View user groups within the organization.
• organization.ip_allow_list.manage - Modify the IP allow list for the organization.
• organization.ip_allow_list.view - View the IP allow list.
• organization.notifications.manage - Modify organization notification settings.
• organization.notifications.view - View organization notification settings.
• organization.okta.manage - Modify existing Okta integrations, or create a new one.
• organization.okta.view - View Okta integration settings for the organization.
• organization.people.invite - Invite new people to the organization.
• organization.people.manage - Remove people from the organization, or change their roles within the organization.
• organization.people.view - View list of people within the organization, together with the roles they have.
• organization.plans_and_billing.manage - Modify billing information or subscription plan.
• organization.plans_and_billing.view - Access the billing page.
• organization.pre_flight_checks.manage - Modify pre-flight checks within the organization.
• organization.pre_flight_checks.view - View pre-flight checks within the organization.
• organization.projects.create - Create a new project within the organization.
• organization.secrets.manage - Manage secrets within the organization.
• organization.secrets.view - View secrets within the organization.
• organization.secrets_policy_settings.manage - Manage secrets policy settings within the organization.
• organization.secrets_policy_settings.view - View existing secrets policy settings.
• organization.self_hosted_agents.manage - Manage self-hosted agents within the organization.
• organization.self_hosted_agents.view - View the list of self-hosted agents within the organization.
• organization.view - Access to the organization. This permission is needed to access any page within the organization domain.

Project Role Permissions

List of the permissions that can be assigned to the project role:

• project.access.manage - Manage who has access to the project.
• project.access.view - View people, groups and bots that have acces to the project.
• project.artifacts.delete - Remove individual artifacts.
• project.artifacts.modify_settings - Modify artifact settings, such as retention policy.
• project.artifacts.view - Access the artifacts on the project, workflow and job level.
• project.artifacts.view_settings - View artifact settings.
• project.debug - Run debug jobs.
• project.delete - Delete the project.
• project.deployment_targets.manage - Manage deployment targets.
• project.deployment_targets.view - View existing deployment targets.
• project.flaky_tests.manage - Create new filters and notifications for flaky tests.
• project.flaky_tests.view - View the flaky tests page.
• project.general_settings.manage - Modify general settings for the project.
• project.general_settings.view - View general settings for the project.
• project.insights.manage - Change how insights for the project are calculated.
• project.insights.view - View insights and analytics for the project.
• project.job.attach - SSH into the running job, or start a debug session.
• project.job.rerun - Manually rerun jobs or entire workflows
• project.job.stop - Manually stop running jobs or workflows.
• project.job.view - View jobs on the projects workflow.
• project.notifications.manage - Manage project notifications.
• project.notifications.view - View project notifications.
• project.pre_flight_checks.manage - Modify pre-flight checks for the project.
• project.pre_flight_checks.view - View pre-flight checks for the project.
• project.repository_info.manage - Modify git repository information.
• project.repository_info.view - View git repository information.
• project.scheduler.manage - Modify project tasks.
• project.scheduler.run_manually - Trigger manual runs of any existing tasks.
• project.scheduler.view - View tasks within the project.
• project.secrets.manage - Manage project secrets.
• project.secrets.view - View existing secrets related to the project.
• project.view - Access the project. This permission is needed to see any page within the project.
• project.workflow.manage - Change workflow definition (jobs that will run within the workflow).
• project.workflow.view - View workflows in the project.

[mattrym]

It would be good to have an overview on the role assignments for particular users. For starters, I think including a number of users/groups directly assigned to a role would be enough.

Since there are a few ways to acquire a role (e.g. through Github or through role inheritance), there could be many ways to represent that in a clear way, especially for organizations with broader set of roles.

[AleksandarCole]

It would be good to have an overview on the role assignments for particular users. For starters, I think including a number of users/groups directly assigned to a role would be enough.

@mattrym that's a good idea. You mean something like this:

---

Since there are a few ways to acquire a role (e.g. through Github or through role inheritance), there could be many ways to represent that in a clear way, especially for organizations with broader set of roles.

I'm a bit less clear on this one. Can you please clarify a bit more?

[mattrym]

@AleksandarCole That's exactly what I meant!

As for the latter part of my suggestion, what I meant is that it might not be clear if the numbers here reflect all the users, or just those who were granted the role manually. It would be good to have a breakdown for each role displaying how that role was acquired (through Github, through Okta, through role inheritance, and so on) and the numbers. Even better if we can display some avatars (like for Deployment Targets). That doesn't necessarily need to be placed in that view, but it would be good to have it in general.

[TomFern]

We're going to track progress of the documentation for this feature in #87 since we are already planning a "Permissions page"