diff --git a/docs/security/custom-roles.md b/docs/security/custom-roles.md new file mode 100644 index 000000000..2d49a51e1 --- /dev/null +++ b/docs/security/custom-roles.md @@ -0,0 +1,37 @@ +--- +Description: Custom roles for Semaphore platform. +--- + +# Custom Roles + +If your organization needs more roles where permissions would be assigned with +higher granularity, you can define custom roles. + +### Creating a new role + +When defining a custom role, you need to give it a unique name (that does not clash +with any of the default roles) and select which [permissions](/security/permissions/) will +its users have. Role inheritance is also allowed, so you can create a new role +**Sys Admin** that will have all the same permissions as **Developer**, for example, +plus access to Self hosted agents (`organization.self_hosted.create`). Permissions +for the Sys Admin role are determined "dynamically", so if you later modify the Developer role +and add/remove some permissions from it, the Sys Admin role will reflect those +changes. + +**TODO** Picture of UI for creating new role, when the ui gets made + +### Organization role to project role mapping + +If there is any role within the organization that needs to have access to all of the +projects, you can define an "*org-role to project-role mapping*" for it. If you want your +Sys Admins to have Admin level access to all of the projects, you can say that the Sys Admin role +maps to the project Admin role. + +!!! warning "Note" + Custom roles are currently only available on our [enterprise plan](pricing). + +!!! info "Default Roles" + As an organization that has Custom Roles enabled, you will still have access to the default roles as well. + +Do you need Custom roles in order to use Semaphore? Contact us via this [form](/contact) + diff --git a/docs/security/default-roles.md b/docs/security/default-roles.md new file mode 100644 index 000000000..95244b307 --- /dev/null +++ b/docs/security/default-roles.md @@ -0,0 +1,180 @@ +Default roles are available to all Semaphore users, regardless of the plan they are on. + +If you or your organization need more roles with different permissions, there is an option +to create your own [custom roles](/security/custom-roles). + +### Organization roles + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Role name + + Permissions + + Notes +
+ **Guest** + +
    +
  • Does not have any permissions within the organization, and can't see any information.
    • +
+ 		+ This role is intended for users that need access to some projects, but should not see + any information regarding the organization. +
+ **Member** + +
    +
  • Can create new projects.
    • +
  • Can view existing notifications.
    • +
+ 		+
+ **Admin** + +
    +
  • Can do everything a member can.
    • +
  • Can view, manage, and modify everything within the organization + (people, secrets, pre-flight checks, + notifications, etc), except general settings and financial information.
    • +
+ 		+ Each of the organization's Admins is also Admin within every project owned by the given organization automatically. +
+ **Owner** + +
    +
  • Can do everything within the organization, including changing general + settings and deleting it.
    • +
+ 		+ By default, this role is assigned to the user that creates the organization. +
+ Each of the organization's Owners is also Admin within every project owned by the given organization. +
+ **Accountant** + +
    +
  • Manages billing
    • +
+ 		+ This role cant access any part of the Semaphore except for pages regarding + spending and financial information. +
+ +### Project roles + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Role name + + Permissions + + Notes +
+ **Reader** + +
    +
  • Can view project activity, workflows, and jobs executed within those workflows.
    • +
+ 		+ Intended for someone who should monitor what is being done, but isn't a developer and shouldn't + modify anything. Perhaps an Engineering Project Manager. +
+ **Contributor** + +
    +
  • Can manually run, modify and stop workflows/jobs.
    • +
  • Can view project-level secrets and organization-wide secrets scoped for the given project.
    • +
  • Can attach to running jobs or debug jobs and projects.
    • +
  • Can view schedulers, project insights, and repository info.
    • +
  • Can manually run schedulers.
    • +
  • Can view, modify and delete artifacts for that project.
    • +
+ 		+ For developers who are currently working on the project, but aren't responsible for maintaining it + and setting up/modifying the environment in which the project exists. +
+ **Maintainer** + +
    +
  • Can do everything a contributor can.
    • +
  • Can view and manage people within the project.
    • +
  • Can view modify and manage project-level secrets, schedulers and, + project-level pre-flight checks.
    • +
  • Can view and manage project settings.
    • +
+ 		+ Usually developers who own the project. +
+ **Admin** + +
    +
  • Can do everything within the project, including deleting it.
    • +
+ 		+ By default, this role is assigned to the user that created the project, and + this user is a primary repository token holder. +
+ diff --git a/docs/security/permissions.md b/docs/security/permissions.md new file mode 100644 index 000000000..083ff4fb5 --- /dev/null +++ b/docs/security/permissions.md @@ -0,0 +1,188 @@ +--- +Description: List of all permissions within the Semaphore. +--- + +# Permissions + +This page lists all permissions within the Semaphore system. This can be used +when creating custom roles and defining what they can do. + +Similar to roles, permissions are also divided into **organization-level** +and **project-level**. + +!!! info "Note" + Some permissions are not yet part of Semaphore but will be introduced in the near future. These are marked with **✕** + + +## Organization permissions + +
+#### Organization secrets [↗](/essentials/using-secrets/) + +`organization.secrets.view`
+The following permissions are related to +[secrets management](/essentials/using-secrets/#creating-and-managing-secrets).
+`organization.secrets.create`
+`organization.secrets.modify`
+`organization.secrets.delete`
+ +#### Audit logs [↗](/security/audit-logs/) + +`organization.audit_logs.view`
+`organization.audit_logs.export` [↗](/security/audit-logs-exporting/)
+`organization.audit_logs.streaming.view` [↗](/security/audit-logs-exporting/#streaming)
+`organization.audit_logs.streaming.manage`
+ +#### Self-hosted agents [↗](/ci-cd-environment/self-hosted-agents-overview/) + +`organization.self_hosted_agents.view`
+`organization.self_hosted_agents.create`
+`organization.self_hosted_agents.reset_token`
+`organization.self_hosted_agents.disable`
+`organization.self_hosted_agents.delete`
+ +#### General settings + +`organization.general_settings.view`
+`organization.general_settings.modify`
+ +#### Organizational notifications [↗](/essentials/webhook-notifications/) + +`organization.notifications.view`
+`organization.notifications.create`
+`organization.notifications.modify`
+`organization.notifications.delete`
+ +#### Organizational pre-flight checks [↗](/essentials/configuring-pre-flight-checks/) + +`organization.pre_flight_checks.view`
+`organization.pre_flight_checks.modify`
+ +#### Billing + +`organization.plans_and_billing.view`
+`organization.plans_and_billing.modify`
+ +#### Dashboards [↗](/essentials/deployment-dashboards/) + +These permissions don't control whether or not a user can see deployment pipelines +defined by the dashboards, rather they control whether a user can access and modify the definition of those +dashboards using the `sem` cli tool, as shown [here](/essentials/deployment-dashboards/#creating-a-dashboard).
+`organization.dashboards.view`
+`organization.dashboards.create`
+`organization.dashboards.modify`
+`organization.dashboards.delete`
+ +#### Managing people + +`organization.people.view`
+`organization.people.invite`
+`organization.people.remove`
+`organization.people.change_role`
+ +#### Role management **✕** + +`organization.roles.view`
+`organization.roles.create`
+`organization.roles.remove`
+`organization.roles.modify`
+ +#### Managing how repository access levels map to Semaphore project roles **✕** + +`organization.repo_to_role_mappers.view`
+`organization.repo_to_role_mappers.create`
+`organization.repo_to_role_mappers.delete`
+`organization.repo_to_role_mappers.modify`
+ +#### Other permissions + +`organization.projects.create`
+`organization.activity_monitor.view`
+ +## Project permissions + +
+#### Managing people + +`project.people.change_role`
+`project.people.remove`
+`project.people.invite`
+ +#### Accessing/running jobs + +`project.job.view`
+`project.job.rerun`
+`project.job.artifacts.view`
+`project.job.artifacts.delete` +(Grants permissions for the [job level](/essentials/artifacts/#job-artifacts) artifacts)
+`project.job.stop`
+The follwing permissions are needed to +access jobs via the `sem` [cli tool](/reference/sem-command-line-tool/#operations).
+`project.job.port_forwarding`
+`project.job.attach`
+`project.job.debug`
+`project.debug`
+ +#### Project level secrets **✕** + +`project.secrets.view`
+`project.secrets.create`
+`project.secrets.modify`
+`project.secrets.delete`
+`project.authorized_org_secrets.list`
(List of organization level secrets +that are whitelisted to be used within a given project)
+ +#### Project notifications **✕** + +`project.notifications.view`
+`project.notifications.create`
+`project.notifications.modify`
+`project.notifications.delete`
+ +#### Schedulers [↗](/essentials/schedule-a-workflow-run/) + +`project.scheduler.view`
+`project.scheduler.create`
+`project.scheduler.delete`
+`project.scheduler.modify`
+`project.scheduler.run_manually`
+`project.scheduler.deactivate`
+ +#### Workflow + +`project.workflow.view`
+`project.workflow.modify`
+`project.workflow.rerun`
+`project.workflow.stop`
+`project.workflow.artifacts.view `
+(Grants permissions for the [workflow level](/essentials/artifacts/#workflow-artifacts) artifacts)
+`project.workflow.artifacts.delete`
+ +#### Artifacts [↗](/essentials/artifacts/) + +`project.artifacts.delete`
+`project.artifacts.view`
+`project.artifacts.view_settings` +(Grants permissions for the [project level](/essentials/artifacts/#project-artifacts) artifacts)
+`project.artifacts.modify_settings`
+ +#### Project pre-flight checks [↗](essentials/configuring-pre-flight-checks/#project-pre-flight-checks) + +`project.pre_flight_checks.view`
+`project.pre_flight_checks.modify`
+ +#### Project insights + +`project.insights.view`
+`project.insights.modify`
+ +#### Project settings and other permissions + +`project.view`
+`project.delete`
+`project.general_settings.view`
+`project.general_settings.modify`
+`project.repository_info.view`
+`project.repository_info.modify`
+`project.badge.view`
+`project.badge.manage`
diff --git a/docs/security/rbac-authorization.md b/docs/security/rbac-authorization.md new file mode 100644 index 000000000..1232533f4 --- /dev/null +++ b/docs/security/rbac-authorization.md @@ -0,0 +1,69 @@ +--- +Description: This page explains the RBAC model that Semaphore 2.0 uses for user authorization. Here, you will find information about existing permissions, roles, and role management. +--- + +# Rbac model + +Semaphore 2.0 uses a **Role-Based Access Control** model for user authorization. +This page will give a brief overview of permissions, roles, and how to manage them. + +## Roles on Semaphore + +All of the roles (and permissions) within the Semaphore are divided into __organization-level__ and __project-level__.
+Organization-level roles define access to functionalities and assets that apply to the entire organization (Audit Logs, Billing, +Organization Members, Projects, etc.).
+On the other hand, project-level roles are assigned within a single project, and grant access +to information scoped only to that one project (Schedulers, Insights, Workflows, Artifacts). +To get any project-level role, you have to be a part of the organization +which owns that project (you must have a role within the organization). + +There is a set of pre-defined [default roles](/security/default-roles) that are available to all users, but there is also +a possibility to define your own [custom roles](/security/custom-roles). + +## Role Management + +#### Organization roles + +To be considered a part of the organization, the user must have a role within that organization. +Each user can have up to one role assigned to them directly. Other than that +users can have one role within the organization assigned to them indirectly through each of the groups +they are a part of.
+If the user has more than one role, all permissions those roles grant are combined to +make a full set of permissions the user has within the given organization. + +#### Organization role to project role mappings + +Some organization roles can grant you automatically a project-level role on each project +that the organization owns. For example, the Organization Admin role makes you an Admin on all +of the organization's projects. To see which organization roles grant you project-level +access, see the "*Notes*" column of [this table](/security/default-roles/#organization-roles). + +#### Project roles + +Project role assignment works similarly to the organization role assignment, only there +are two additional ways a user can get a role within the project.
+If the user has access to the project's remote repository, that automatically grants them +a role within the Semaphore project according to these ["*repo-to-role mapping*" +rules](/security/repository-to-role-mappings/).
+Next, each organization-level role can grant access to the organization's projects, as mentioned +[above](organization-role-to-project-role-mappings). Finally, user can be assigned a role +within the project directly (from projects Admin or Maintainer), and can also get a role through + membership in the group which was assigned a role within the given project. + +**Example**:
*Owen* has access to the project's GitHub repository, which automatically makes him +a Contributor to that project on Semaphore. He is the organization's Admin, which makes him Admin on +all of the organization's projects, and someone assigned him directly the role of Maintainer. +So, *Owen* has three roles within this project: Contributor, Admin, and Maintainer, and +same as with organization roles, the sum of permissions that those roles grant make a total set +of permission *Owen* has within this project. + +#### Retracting roles + +Only roles that were assigned to a user directly can be retracted. If the user has a role +through a membership in some group, he either has to be removed from the group, or +the role has to be retracted from the entire group. + +If a project role was assigned through access to the remote repository, the only way to remove that +role is to remove the user from the repository, and if it was assigned through an organization-level +role, that role has to be retracted. + diff --git a/docs/security/repository-to-role-mappings.md b/docs/security/repository-to-role-mappings.md new file mode 100644 index 000000000..e90a9ce57 --- /dev/null +++ b/docs/security/repository-to-role-mappings.md @@ -0,0 +1,89 @@ +--- +Description: This page describes how access to remote repository grants you access to Semaphore projects. +--- + +# Repository-to-role mappings + +On Semaphore, each project has to stem from a code base on a remote repository, like GitHub +or Bitbucket. Semaphore keeps track of all accounts that have access to those remote +repositories (collaborators), and if any of them is associated with a Semaphore account, that +Semaphore user is given access to the project (if he is a member of the organization which owns it). + +## Rules for assigning project roles + +Depending on user's premissions within the remote repository, a different role +is assigned to them on the Semaphore project. + +#### GitHub: + + + + + + + + + + + + + + + + + + + + + + +
Repository permission levelSemaphore project role
+ Admin + + Maintainer +
+ Push + + Contributor +
+ Pull + + Reader +
+ +#### Bitbucket: + + + + + + + + + + + + + + + + + + + + + + +
Repository permission levelSemaphore project role
+ Admin + + Maintainer +
+ Write + + Contributor +
+ Read + + Reader +
diff --git a/mkdocs.yml b/mkdocs.yml index 1a558edea..0ad4236a9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -204,6 +204,12 @@ nav: - Audit logs: security/audit-logs.md - Audit logs exporting: security/audit-logs-exporting.md - Audit Events reference: security/audit-events-reference.md + - "User authorization": + - RBAC overview: security/rbac-authorization.md + - Permissions: security/permissions.md + - Default roles: security/default-roles.md + - Custom roles: security/custom-roles.md + - Repo-to-role mapping: security/repository-to-role-mappings.md - FAQ: - FAQ: faq/faq.md - Managing projects: faq/managing-projects.md