debian-mirror-gitlab/doc/development/permissions.md

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

175 lines
7.8 KiB
Markdown
Raw Normal View History

2021-01-29 00:20:46 +05:30
---
stage: Manage
2022-04-04 11:22:00 +05:30
group: Authentication and Authorization
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-29 00:20:46 +05:30
---
2022-03-02 08:16:31 +05:30
# Implementing permissions
2018-12-05 23:21:45 +05:30
There are multiple types of permissions across GitLab, and when implementing
anything that deals with permissions, all of them should be considered.
2022-05-07 20:08:51 +05:30
## Instance
### User types
Each user can be one of the following types:
- Regular.
- External - access to groups and projects only if direct member.
- [Internal users](internal_users.md) - system created.
- [Auditor](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/app/policies/ee/base_policy.rb#L9):
- No access to projects or groups settings menu.
- No access to Admin Area.
- Read-only access to everything else.
- [Administrator](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/policies/base_policy.rb#L6) - read-write access.
See the [permissions page](../user/permissions.md) for details on how each user type is used.
2018-12-05 23:21:45 +05:30
## Groups and Projects
### General permissions
Groups and projects can have the following visibility levels:
2020-05-24 23:13:21 +05:30
- public (`20`) - an entity is visible to everyone
- internal (`10`) - an entity is visible to logged in users
- private (`0`) - an entity is visible only to the approved members of the entity
2018-12-05 23:21:45 +05:30
2020-07-28 23:09:34 +05:30
By default, subgroups can **not** have higher visibility levels.
For example, if you create a new private group, it can not include a public subgroup.
2020-04-08 14:13:33 +05:30
The visibility level of a group can be changed only if all subgroups and
2020-07-28 23:09:34 +05:30
sub-projects have the same or lower visibility level. For example, a group can be set
to internal only if all subgroups and projects are internal or private.
2021-02-22 17:27:13 +05:30
WARNING:
2020-07-28 23:09:34 +05:30
If you migrate an existing group to a lower visibility level, that action does not migrate subgroups
in the same way. This is a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/22406).
2018-12-05 23:21:45 +05:30
Visibility levels can be found in the `Gitlab::VisibilityLevel` module.
### Feature specific permissions
Additionally, the following project features can have different visibility levels:
- Issues
- Repository
2022-05-07 20:08:51 +05:30
- Merge request
2021-06-08 01:23:25 +05:30
- Forks
2018-12-05 23:21:45 +05:30
- Pipelines
2021-06-08 01:23:25 +05:30
- Analytics
- Requirements
- Security & Compliance
2018-12-05 23:21:45 +05:30
- Wiki
- Snippets
2021-06-08 01:23:25 +05:30
- Pages
- Operations
- Metrics Dashboard
2018-12-05 23:21:45 +05:30
These features can be set to "Everyone with Access" or "Only Project Members".
They make sense only for public or internal projects because private projects
can be accessed only by project members by default.
### Members
Users can be members of multiple groups and projects. The following access
2021-09-30 23:02:18 +05:30
levels are available (defined in the
[`Gitlab::Access`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/access.rb)
module):
2018-12-05 23:21:45 +05:30
2020-06-23 00:09:42 +05:30
- No access (`0`)
2021-09-30 23:02:18 +05:30
- [Minimal access](../user/permissions.md#users-with-minimal-access) (`5`)
2020-06-23 00:09:42 +05:30
- Guest (`10`)
- Reporter (`20`)
- Developer (`30`)
- Maintainer (`40`)
- Owner (`50`)
2018-12-05 23:21:45 +05:30
2022-07-16 23:28:13 +05:30
If a user is the member of both a project and the project parent groups, the
2022-08-27 11:52:29 +05:30
highest permission is the applied access level for the project.
2018-12-05 23:21:45 +05:30
2022-07-16 23:28:13 +05:30
If a user is the member of a project, but not the parent groups, they
2018-12-05 23:21:45 +05:30
can still view the groups and their entities (like epics).
Project membership (where the group membership is already taken into account)
is stored in the `project_authorizations` table.
2022-07-23 23:45:48 +05:30
NOTE:
In [GitLab 14.9](https://gitlab.com/gitlab-org/gitlab/-/issues/351211) and later, projects in personal namespaces have a maximum role of Owner.
Because of a [known issue](https://gitlab.com/gitlab-org/gitlab/-/issues/219299) in GitLab 14.8 and earlier, projects in personal namespaces have a maximum role of Maintainer.
2020-06-23 00:09:42 +05:30
2018-12-05 23:21:45 +05:30
### Confidential issues
2021-10-27 15:23:28 +05:30
[Confidential issues](../user/project/issues/confidential_issues.md) can be accessed
only by project members who are at least
2018-12-05 23:21:45 +05:30
reporters (they can't be accessed by guests). Additionally they can be accessed
by their authors and assignees.
2020-03-13 15:44:24 +05:30
### Licensed features
Some features can be accessed only if the user has the correct license plan.
## Permission dependencies
Feature policies can be quite complex and consist of multiple rules.
Quite often, one permission can be based on another.
Designing good permissions means reusing existing permissions as much as possible
and making access to features granular.
In the case of a complex resource, it should be broken into smaller pieces of information
and each piece should be granted a different permission.
A good example in this case is the _Merge Request widget_ and the _Security reports_.
2021-02-22 17:27:13 +05:30
Depending on the visibility level of the _Pipelines_, the _Security reports_ are either visible
2020-03-13 15:44:24 +05:30
in the widget or not. So, the _Merge Request widget_, the _Pipelines_, and the _Security reports_,
have separate permissions. Moreover, the permissions for the _Merge Request widget_
and the _Pipelines_ are dependencies of the _Security reports_.
### Permission dependencies of Secure features
Secure features have complex permissions since these features are integrated
into different features like Merge Requests and CI flow.
Here is a list of some permission dependencies.
| Activity level | Resource | Locations |Permission dependency|
|----------------|----------|-----------|-----|
2020-06-23 00:09:42 +05:30
| View | License information | Dependency list, License Compliance | Can view repository |
| View | Dependency information | Dependency list, License Compliance | Can view repository |
2020-03-13 15:44:24 +05:30
| View | Vulnerabilities information | Dependency list | Can view security findings |
2022-05-07 20:08:51 +05:30
| View | Black/Whitelisted licenses for the project | License Compliance, merge request | Can view repository |
| View | Security findings | merge request, CI job page, Pipeline security tab | Can read the project and CI jobs |
| View | Vulnerability feedback | merge request | Can read security findings |
2020-03-13 15:44:24 +05:30
| View | Dependency List page | Project | Can access Dependency information |
| View | License Compliance page | Project | Can access License information|
2021-04-29 21:17:54 +05:30
## Where should permissions be checked?
By default, controllers, API endpoints, and GraphQL types/fields are responsible for authorization. See [Secure Coding Guidelines > Permissions](secure_coding_guidelines.md#permissions).
### Considerations
- Many actions are completely or partially extracted to services, finders, and other classes, so it is normal to do permission checks "downstream".
- Often, authorization logic must be incorporated in DB queries to filter records.
- `DeclarativePolicy` rules are relatively performant, but conditions may perform database calls.
- Multiple permission checks across layers can be difficult to reason about, which is its own security risk. For example, duplicate authorization logic could diverge.
- Should we apply defense-in-depth with permission checks? [Join the discussion](https://gitlab.com/gitlab-org/gitlab/-/issues/324135)
### Tips
If a class accepts `current_user`, then it may be responsible for authorization.
### Example: Adding a new API endpoint
By default, we authorize at the endpoint. Checking an existing ability may make sense; if not, then we probably need to add one.
As an aside, most endpoints can be cleanly categorized as a CRUD (create, read, update, destroy) action on a resource. The services and abilities follow suit, which is why many are named like `Projects::CreateService` or `:read_project`.
Say, for example, we extract the whole endpoint into a service. The `can?` check will now be in the service. Say the service reuses an existing finder, which we are modifying for our purposes. Should we make the finder check an ability?
- If the finder doesn't accept `current_user`, and therefore doesn't check permissions, then probably no.
- If the finder accepts `current_user`, and doesn't check permissions, then it would be a good idea to double check other usages of the finder, and we might consider adding authorization.
- If the finder accepts `current_user`, and already checks permissions, then either we need to add our case, or the existing checks are appropriate.