2017-02-13 11:59:57 -05:00
|
|
|
# New CI job permissions model
|
2016-09-21 10:28:48 -04:00
|
|
|
|
|
|
|
> Introduced in GitLab 8.12.
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
GitLab 8.12 has a completely redesigned [job permissions] system. You can find
|
2016-09-22 07:45:36 -04:00
|
|
|
all discussion and all our concerns when choosing the current approach in issue
|
|
|
|
[#18994](https://gitlab.com/gitlab-org/gitlab-ce/issues/18994).
|
2016-09-21 10:28:48 -04:00
|
|
|
|
2016-09-22 07:45:36 -04:00
|
|
|
---
|
2016-09-21 10:28:48 -04:00
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
Jobs permissions should be tightly integrated with the permissions of a user
|
|
|
|
who is triggering a job.
|
2016-09-21 10:28:48 -04:00
|
|
|
|
2016-09-22 07:45:36 -04:00
|
|
|
The reasons to do it like that are:
|
|
|
|
|
|
|
|
- We already have a permissions system in place: group and project membership
|
|
|
|
of users.
|
2017-02-13 11:59:57 -05:00
|
|
|
- We already fully know who is triggering a job (using `git push`, using the
|
2016-09-22 07:45:36 -04:00
|
|
|
web UI, executing triggers).
|
|
|
|
- We already know what user is allowed to do.
|
2017-02-13 11:59:57 -05:00
|
|
|
- We use the user permissions for jobs that are triggered by the user.
|
2016-09-22 07:45:36 -04:00
|
|
|
- It opens a lot of possibilities to further enforce user permissions, like
|
|
|
|
allowing only specific users to access runners or use secure variables and
|
|
|
|
environments.
|
2017-02-13 11:59:57 -05:00
|
|
|
- It is simple and convenient that your job can access everything that you
|
2016-09-22 07:45:36 -04:00
|
|
|
as a user have access to.
|
2017-02-13 11:59:57 -05:00
|
|
|
- Short living unique tokens are now used, granting access for time of the job
|
2016-09-22 07:45:36 -04:00
|
|
|
and maximizing security.
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
With the new behavior, any job that is triggered by the user, is also marked
|
2016-09-22 07:45:36 -04:00
|
|
|
with their permissions. When a user does a `git push` or changes files through
|
|
|
|
the web UI, a new pipeline will be usually created. This pipeline will be marked
|
2017-02-13 11:59:57 -05:00
|
|
|
as created be the pusher (local push or via the UI) and any job created in this
|
2016-09-22 07:45:36 -04:00
|
|
|
pipeline will have the permissions of the pusher.
|
|
|
|
|
|
|
|
This allows us to make it really easy to evaluate the access for all projects
|
2016-11-30 14:40:53 -05:00
|
|
|
that have [Git submodules][gitsub] or are using container images that the pusher
|
2017-02-13 11:59:57 -05:00
|
|
|
would have access too. **The permission is granted only for time that job is
|
|
|
|
running. The access is revoked after the job is finished.**
|
2016-09-22 07:45:36 -04:00
|
|
|
|
|
|
|
## Types of users
|
|
|
|
|
|
|
|
It is important to note that we have a few types of users:
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
- **Administrators**: CI jobs created by Administrators will not have access
|
2016-09-22 07:45:36 -04:00
|
|
|
to all GitLab projects, but only to projects and container images of projects
|
|
|
|
that the administrator is a member of.That means that if a project is either
|
|
|
|
public or internal users have access anyway, but if a project is private, the
|
|
|
|
Administrator will have to be a member of it in order to have access to it
|
2017-02-13 11:59:57 -05:00
|
|
|
via another project's job.
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
- **External users**: CI jobs created by [external users][ext] will have
|
2016-09-22 09:48:56 -04:00
|
|
|
access only to projects to which user has at least reporter access. This
|
|
|
|
rules out accessing all internal projects by default,
|
2016-09-22 07:45:36 -04:00
|
|
|
|
|
|
|
This allows us to make the CI and permission system more trustworthy.
|
|
|
|
Let's consider the following scenario:
|
|
|
|
|
|
|
|
1. You are an employee of a company. Your company has a number of internal tools
|
2017-02-13 11:59:57 -05:00
|
|
|
hosted in private repositories and you have multiple CI jobs that make use
|
2016-09-22 07:45:36 -04:00
|
|
|
of these repositories.
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
2. You invite a new [external user][ext]. CI jobs created by that user do not
|
2016-09-22 09:48:56 -04:00
|
|
|
have access to internal repositories, because the user also doesn't have the
|
|
|
|
access from within GitLab. You as an employee have to grant explicit access
|
|
|
|
for this user. This allows us to prevent from accidental data leakage.
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
## Job token
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
A unique job token is generated for each job and it allows the user to
|
2016-09-22 07:45:36 -04:00
|
|
|
access all projects that would be normally accessible to the user creating that
|
2017-02-13 11:59:57 -05:00
|
|
|
job.
|
2016-09-22 07:45:36 -04:00
|
|
|
|
|
|
|
We try to make sure that this token doesn't leak by:
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
1. Securing all API endpoints to not expose the job token.
|
|
|
|
1. Masking the job token from job logs.
|
|
|
|
1. Allowing to use the job token **only** when job is running.
|
2016-09-22 07:45:36 -04:00
|
|
|
|
|
|
|
However, this brings a question about the Runners security. To make sure that
|
|
|
|
this token doesn't leak, you should also make sure that you configure
|
|
|
|
your Runners in the most possible secure way, by avoiding the following:
|
|
|
|
|
|
|
|
1. Any usage of Docker's `privileged` mode is risky if the machines are re-used.
|
2017-02-13 11:59:57 -05:00
|
|
|
1. Using the `shell` executor since jobs run on the same machine.
|
2016-09-22 07:45:36 -04:00
|
|
|
|
|
|
|
By using an insecure GitLab Runner configuration, you allow the rogue developers
|
2017-02-13 11:59:57 -05:00
|
|
|
to steal the tokens of other jobs.
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2017-03-17 12:13:23 -04:00
|
|
|
## Pipeline triggers
|
2016-09-22 09:48:56 -04:00
|
|
|
|
2017-05-11 08:06:06 -04:00
|
|
|
Since 9.0 [pipeline triggers][triggers] do support the new permission model.
|
2017-03-17 12:13:23 -04:00
|
|
|
The new triggers do impersonate their associated user including their access
|
|
|
|
to projects and their project permissions. To migrate trigger to use new permisison
|
|
|
|
model use **Take ownership**.
|
2016-09-22 09:48:56 -04:00
|
|
|
|
2016-09-22 07:45:36 -04:00
|
|
|
## Before GitLab 8.12
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
In versions before GitLab 8.12, all CI jobs would use the CI Runner's token
|
2016-09-22 07:45:36 -04:00
|
|
|
to checkout project sources.
|
|
|
|
|
|
|
|
The project's Runner's token was a token that you could find under the
|
2017-05-11 15:21:14 -04:00
|
|
|
project's **Settings > Pipelines** and was limited to access only that
|
2016-09-22 07:45:36 -04:00
|
|
|
project.
|
2016-09-22 08:04:57 -04:00
|
|
|
It could be used for registering new specific Runners assigned to the project
|
|
|
|
and to checkout project sources.
|
|
|
|
It could also be used with the GitLab Container Registry for that project,
|
2017-02-13 11:59:57 -05:00
|
|
|
allowing pulling and pushing Docker images from within the CI job.
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2016-09-22 08:04:57 -04:00
|
|
|
---
|
2016-09-22 07:45:36 -04:00
|
|
|
|
|
|
|
GitLab would create a special checkout URL like:
|
|
|
|
|
|
|
|
```
|
|
|
|
https://gitlab-ci-token:<project-runners-token>/gitlab.com/gitlab-org/gitlab-ce.git
|
|
|
|
```
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
And then the users could also use it in their CI jobs all Docker related
|
2016-09-22 07:45:36 -04:00
|
|
|
commands to interact with GitLab Container Registry. For example:
|
|
|
|
|
|
|
|
```
|
2017-03-10 05:20:08 -05:00
|
|
|
docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com
|
2016-09-22 07:45:36 -04:00
|
|
|
```
|
|
|
|
|
2016-09-22 08:04:57 -04:00
|
|
|
Using single token had multiple security implications:
|
2016-09-22 07:45:36 -04:00
|
|
|
|
|
|
|
- The token would be readable to anyone who had developer access to a project
|
2017-02-13 11:59:57 -05:00
|
|
|
that could run CI jobs, allowing the developer to register any specific
|
2016-09-22 07:45:36 -04:00
|
|
|
Runner for that project.
|
|
|
|
- The token would allow to access only the project's sources, forbidding from
|
|
|
|
accessing any other projects.
|
|
|
|
- The token was not expiring and was multi-purpose: used for checking out sources,
|
|
|
|
for registering specific runners and for accessing a project's container
|
|
|
|
registry with read-write permissions.
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
All the above led to a new permission model for jobs that was introduced
|
2016-09-22 07:45:36 -04:00
|
|
|
with GitLab 8.12.
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
## Making use of the new CI job permissions model
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
With the new job permissions model, there is now an easy way to access all
|
2016-09-22 07:45:36 -04:00
|
|
|
dependent source code in a project. That way, we can:
|
|
|
|
|
2017-03-24 12:39:45 -04:00
|
|
|
1. Access a project's dependent repositories
|
2016-11-30 14:40:53 -05:00
|
|
|
1. Access a project's [Git submodules][gitsub]
|
2016-09-22 07:45:36 -04:00
|
|
|
1. Access private container images
|
|
|
|
1. Access project's and submodule LFS objects
|
|
|
|
|
2016-10-13 03:30:18 -04:00
|
|
|
Below you can see the prerequisites needed to make use of the new permissions
|
|
|
|
model and how that works with Git submodules and private Docker images hosted on
|
2016-09-22 07:45:36 -04:00
|
|
|
the container registry.
|
|
|
|
|
2016-10-13 03:30:18 -04:00
|
|
|
### Prerequisites to use the new permissions model
|
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
With the new permissions model in place, there may be times that your job will
|
2016-10-13 03:30:18 -04:00
|
|
|
fail. This is most likely because your project tries to access other project's
|
2017-02-13 11:59:57 -05:00
|
|
|
sources, and you don't have the appropriate permissions. In the job log look
|
2016-10-13 03:30:18 -04:00
|
|
|
for information about 403 or forbidden access messages.
|
|
|
|
|
|
|
|
In short here's what you need to do should you encounter any issues.
|
|
|
|
|
|
|
|
As an administrator:
|
|
|
|
|
|
|
|
- **500 errors**: You will need to update [GitLab Workhorse][workhorse] to at
|
|
|
|
least 0.8.2. This is done automatically for Omnibus installations, you need to
|
2016-10-14 04:07:36 -04:00
|
|
|
[check manually][update-docs] for installations from source.
|
2016-10-13 03:30:18 -04:00
|
|
|
- **500 errors**: Check if you have another web proxy sitting in front of NGINX (HAProxy,
|
|
|
|
Apache, etc.). It might be a good idea to let GitLab use the internal NGINX
|
|
|
|
web server and not disable it completely. See [this comment][comment] for an
|
|
|
|
example.
|
|
|
|
- **403 errors**: You need to make sure that your installation has [HTTP(S)
|
|
|
|
cloning enabled][https]. HTTP(S) support is now a **requirement** by GitLab CI
|
|
|
|
to clone all sources.
|
|
|
|
|
|
|
|
As a user:
|
|
|
|
|
|
|
|
- Make sure you are a member of the group or project you're trying to have
|
|
|
|
access to. As an Administrator, you can verify that by impersonating the user
|
2017-02-13 11:59:57 -05:00
|
|
|
and retry the failing job in order to verify that everything is correct.
|
2016-10-13 03:30:18 -04:00
|
|
|
|
2017-03-24 12:39:45 -04:00
|
|
|
### Dependent repositories
|
|
|
|
|
|
|
|
The [Job environment variable][jobenv] `CI_JOB_TOKEN` can be used to
|
|
|
|
authenticate any clones of dependent repositories. For example:
|
|
|
|
|
|
|
|
```
|
|
|
|
git clone https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.com/myuser/mydependentrepo
|
|
|
|
```
|
|
|
|
|
|
|
|
It can also be used for system-wide authentication
|
|
|
|
(only do this in a docker container, it will overwrite ~/.netrc):
|
|
|
|
|
|
|
|
```
|
|
|
|
echo -e "machine gitlab.com\nlogin gitlab-ci-token\npassword ${CI_JOB_TOKEN}" > ~/.netrc
|
|
|
|
```
|
|
|
|
|
2016-10-13 03:30:18 -04:00
|
|
|
### Git submodules
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2016-11-30 14:40:53 -05:00
|
|
|
To properly configure submodules with GitLab CI, read the
|
|
|
|
[Git submodules documentation][gitsub].
|
2016-09-21 10:28:48 -04:00
|
|
|
|
|
|
|
### Container Registry
|
|
|
|
|
2016-09-22 07:45:36 -04:00
|
|
|
With the update permission model we also extended the support for accessing
|
|
|
|
Container Registries for private projects.
|
|
|
|
|
2016-12-01 08:24:12 -05:00
|
|
|
> **Notes:**
|
|
|
|
- GitLab Runner versions prior to 1.8 don't incorporate the introduced changes
|
|
|
|
for permissions. This makes the `image:` directive to not work with private
|
|
|
|
projects automatically and it needs to be configured manually on Runner's host
|
|
|
|
with a predefined account (for example administrator's personal account with
|
|
|
|
access token created explicitly for this purpose). This issue is resolved with
|
|
|
|
latest changes in GitLab Runner 1.8 which receives GitLab credentials with
|
|
|
|
build data.
|
2017-06-13 08:10:31 -04:00
|
|
|
- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
|
|
|
|
to pass a [personal access token][pat] instead of your password in order to
|
|
|
|
login to GitLab's Container Registry.
|
2016-09-21 10:28:48 -04:00
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
Your jobs can access all container images that you would normally have access
|
2016-09-22 07:45:36 -04:00
|
|
|
to. The only implication is that you can push to the Container Registry of the
|
2017-02-13 11:59:57 -05:00
|
|
|
project for which the job is triggered.
|
2016-09-21 10:28:48 -04:00
|
|
|
|
2016-09-22 07:45:36 -04:00
|
|
|
This is how an example usage can look like:
|
2016-09-21 10:28:48 -04:00
|
|
|
|
|
|
|
```
|
|
|
|
test:
|
|
|
|
script:
|
2017-03-10 05:20:08 -05:00
|
|
|
- docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY
|
2016-09-21 10:28:48 -04:00
|
|
|
- docker pull $CI_REGISTRY/group/other-project:latest
|
|
|
|
- docker run $CI_REGISTRY/group/other-project:latest
|
|
|
|
```
|
2016-09-22 07:45:36 -04:00
|
|
|
|
2017-02-13 11:59:57 -05:00
|
|
|
[job permissions]: ../permissions.md#jobs-permissions
|
2016-10-13 03:30:18 -04:00
|
|
|
[comment]: https://gitlab.com/gitlab-org/gitlab-ce/issues/22484#note_16648302
|
2016-09-22 09:48:56 -04:00
|
|
|
[ext]: ../permissions.md#external-users
|
2016-11-30 14:40:53 -05:00
|
|
|
[gitsub]: ../../ci/git_submodules.md
|
2016-10-13 03:30:18 -04:00
|
|
|
[https]: ../admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols
|
2016-09-22 09:48:56 -04:00
|
|
|
[triggers]: ../../ci/triggers/README.md
|
2016-10-14 04:07:36 -04:00
|
|
|
[update-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update
|
2016-10-13 03:30:18 -04:00
|
|
|
[workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse
|
2017-03-30 10:44:30 -04:00
|
|
|
[jobenv]: ../../ci/variables/README.md#predefined-variables-environment-variables
|
2017-06-13 08:10:31 -04:00
|
|
|
[2fa]: ../profile/account/two_factor_authentication.md
|
|
|
|
[pat]: ../profile/personal_access_tokens.md
|