Skip to content

Commit

Permalink
Adding rbac related stuff without custom roles
Browse files Browse the repository at this point in the history
  • Loading branch information
@VeljkoMaksimovic
VeljkoMaksimovic committed Jan 24, 2024
1 parent 9dee20b commit 13ed724
Show file tree
Hide file tree
Showing 4 changed files with 292 additions and 0 deletions.
132 changes: 132 additions & 0 deletions docs/security/default-roles.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
Default roles are available to all Semaphore users, regardless of the plan they are on.

### Organization roles
<table style="background-color: rgb(255, 255, 255);">
<thead>
<tr>
<td>
Role name
</td>
<td>
Permissions
</td>
<td>
Notes
</td>
</tr>
</thead>
<tbody>
<tr>
<td>
**Member**
</td>
<td>
<ul>
<li>Can create new projects.</li>
<li>Can view existing notifications and settings.</li>
</ul>
</td>
<td>
</td>
</tr>
<tr>
<td>
**Admin**
</td>
<td>
<ul>
<li>Can do everything a member can.</li>
<li>Can view, manage, and modify everything within the organization
(people, secrets, pre-flight checks,
notifications, etc), except general settings and financial information.</li>
</ul>
</td>
<td>
Each of the organization's Admins is also Admin within every project owned by the given organization automatically.
</td>
</tr>
<tr>
<td>
**Owner**
</td>
<td>
<ul>
<li>Can do everything within the organization, including changing general
settings and deleting it.</li>
</ul>
</td>
<td>
By default, this role is assigned to the user that creates the organization.
<br/>
Each of the organization's Owners is also Admin within every project owned by the given organization.
</td>
</tr>
</tbody>
</table>

### Project roles
<table style="background-color: rgb(255, 255, 255);">
<thead>
<tr>
<td>
Role name
</td>
<td>
Permissions
</td>
<td>
Notes
</td>
</tr>
</thead>
<tbody>
<tr>
<td>
**Reader**
</td>
<td>
<ul>
<li>Can view project activity, workflows, and jobs executed within those workflows.</li>
</ul>
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
**Contributor**
</td>
<td>
<ul>
<li>Can manually run, modify and stop workflows/jobs.</li>
<li>Can view project-level secrets and organization-wide secrets scoped for the given project.</li>
<li>Can attach to running jobs or debug jobs and projects.</li>
<li>Can view schedulers, project insights, and repository info.</li>
<li>Can manually run schedulers.</li>
<li>Can view, modify and delete artifacts for that project.</li>
</ul>
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
**Admin**
</td>
<td>
<ul>
<li>Can do everything within the project, including deleting it.</li>
</ul>
</td>
<td>
By default, this role is assigned to the user that created the project, and
this user is a primary repository token holder.
</td>
</tr>
</tbody>
</table>

67 changes: 67 additions & 0 deletions docs/security/rbac-authorization.md
View file
Original file line number Diff line number Diff line change
@@ -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__.<br />
Organization-level roles define access to functionalities and assets that apply to the entire organization (Audit Logs, Billing,
Organization Members, Projects, etc.).<br/>
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.<br/>
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.<br/>
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/).<br/>
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**:<br/> *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.

89 changes: 89 additions & 0 deletions docs/security/repository-to-role-mappings.md
View file
Original file line number Diff line number Diff line change
@@ -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:

<table style="background-color: rgb(255, 255, 255);">
<thead>
<tr>
<td>Repository permission level</td>
<td>Semaphore project role</td>
</tr>
</thead>
<tbody>
<tr>
<td>
Admin
</td>
<td>
Admin
</td>
</tr>
<tr>
<td>
Push
</td>
<td>
Contributor
</td>
</tr>
<tr>
<td>
Pull
</td>
<td>
Reader
</td>
</tr>
</tbody>
</table>

#### Bitbucket:

<table style="background-color: rgb(255, 255, 255);">
<thead>
<tr>
<td>Repository permission level</td>
<td>Semaphore project role</td>
</tr>
</thead>
<tbody>
<tr>
<td>
Admin
</td>
<td>
Admin
</td>
</tr>
<tr>
<td>
Write
</td>
<td>
Contributor
</td>
</tr>
<tr>
<td>
Read
</td>
<td>
Reader
</td>
</tr>
</tbody>
</table>
4 changes: 4 additions & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 13ed724

Please sign in to comment.