From 13ed724317ec8a3a89f056ea48bff75d7dc7d9b4 Mon Sep 17 00:00:00 2001 From: VeljkoMaksimovic Date: Wed, 24 Jan 2024 14:55:40 +0100 Subject: [PATCH] Adding rbac related stuff without custom roles --- docs/security/default-roles.md | 132 +++++++++++++++++++ docs/security/rbac-authorization.md | 67 ++++++++++ docs/security/repository-to-role-mappings.md | 89 +++++++++++++ mkdocs.yml | 4 + 4 files changed, 292 insertions(+) create mode 100644 docs/security/default-roles.md create mode 100644 docs/security/rbac-authorization.md create mode 100644 docs/security/repository-to-role-mappings.md diff --git a/docs/security/default-roles.md b/docs/security/default-roles.md new file mode 100644 index 00000000..5818dcfa --- /dev/null +++ b/docs/security/default-roles.md @@ -0,0 +1,132 @@ +Default roles are available to all Semaphore users, regardless of the plan they are on. + +### Organization roles + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Role name + + Permissions + + Notes +
+ **Member** + +
    +
  • Can create new projects.
    • +
  • Can view existing notifications and settings.
    • +
+ 		+
+ **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. +
+ +### 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. +
+ **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/rbac-authorization.md b/docs/security/rbac-authorization.md new file mode 100644 index 00000000..862aba65 --- /dev/null +++ b/docs/security/rbac-authorization.md @@ -0,0 +1,67 @@ +--- +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. + +## 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). + +**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 Reader. +So, *Owen* has three roles within this project: Contributor, Admin, and Reader, 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 00000000..754edf71 --- /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 + + Admin +
+ Push + + Contributor +
+ Pull + + Reader +
+ +#### Bitbucket: + + + + + + + + + + + + + + + + + + + + + + +
Repository permission levelSemaphore project role
+ Admin + + Admin +
+ Write + + Contributor +
+ Read + + Reader +
diff --git a/mkdocs.yml b/mkdocs.yml index d58fe7a4..14a8d811 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -230,6 +230,10 @@ nav: - "Okta integration": - Overview: security/okta/overview.md - Installation: security/okta/installation.md + - "User authorization": + - RBAC overview: security/rbac-authorization.md + - Default roles: security/default-roles.md + - Repository-to-role mappings: security/repository-to-role-mappings.md - Score: - Insights: score/project-insights.md - Custom dashboards: score/custom-dashboards.md