Skip to content

Agent authorization for private manifest projects - Initial design explorations

Problem to solve

As an agent "owner", I want a way to allow the agent access to manifest projects, without me personally having access to those projects.

As a manifest project owner, I want a way to allow the agent access to my manifest project, without allowing read access to others.

Intended users

User experience goal

Be able to allow access to a specific agent in a project's settings.

Proposal

Use deploy tokens to authorize an agent to access the a private manifest project.

Assuming that Priyanka manages the agent configuration project, and Sasha manages the manifest project, the user flow is the following:

Prerequisites:

  1. Priyanka set up the agent configuration project, and installs the agent
  2. Sasha creates the manifest project

Authorization and deployment setup:

  1. Sasha creates a deploy token under "Settings/Repository/Deploy Tokens"
  2. Sasha shares the deploy token credentials (username + password) with Priyanka, outside of GitLab
  3. Priyanka registers the deploy token credentials under a UI of the config project
    • A single agent configuration project might include the configuration of multiple agents. The deploy token should be registered for the selected agents only.
    • The authorization in step 3 may expose the existence of private projects, or private groups as GitLab will show the full path of the project to Priyanka.
  4. Priyanka adds the manifest project slug to the agent configuration yaml

An optimization of the above might be to have a UI for steps 3 and 4 together. That is when Priyanka registers the deploy token, a new branch + commit + MR (or a commit on master directly) are automatically created that add the manifest project to the agent configuration.

Documentation

Security note During authorization of manifest projects for a cluster agent, GitLab may expose the existence of private projects, and private groups to the maintainers of the configuration project.

TBC: Should GitLab show the full path of the config project to Sasha ?

Constraints

  1. All private groups (names, paths) remain private only to their members
  2. All private projects (names, paths) remain private only to their members
  3. All agents (names, cluster names) remain private only to the config project, and projects that authorized the agent.

Alternatives

We've discussed many alternatives, and decided to move on with the approach that uses deploy tokens.

These alternatives were:

  • start with automatically authorizing the configuration project to access itself for manifest files too
  • create a workflow where most of the authorization is done in the manifest repo
  • add support for service accounts to manage the authorizations
  • provide group level agents to allow access to any project under the group

Some of these might be implemented in future issues.

User story

Use cases with various private projects

The basic approach is the one recommended by Emily when adding the project should happen in the config project, and it might notify the manifest project's maintainers.

Currently we have 3 proposals that complement each other:

The proposal in this issue is the last one: authorization using deploy tokens.

Use case 0

Given that user has a single, private project to store the agent configuration and manifests
When the user updates the manifests in the project
Then the agent can read the manifests without any further user setup and authorization

Use case 1

Given that user has a public/internal agent configuration project in group A
and a user has a public/internal manifest project in group A
When the user adds the manifest project to the configuration project
Then we can already support this setup

✅ This is already supported

Use case 2

Given that user has a private agent configuration project in group A
and a user has a public/internal manifest project in group A
When the user adds the manifest project to the configuration project
Then we can already support this setup

✅ This is already supported

Use case 3

Given that user Alfred has a private agent configuration project in group A
and user Bill has a private manifest project in group A
When Alfred adds the manifest project to the agent configuration
Then Bill receives an e-mail to authorize the agent
When Bill authorizes the agent
Then the agent can access the manifest project
And the agent shows up on the manifest project as being authorized
And the agent's authorization can be reoved on the manifest project page
When Bill does not authorize the agent
Then nothing is changed, nobody is notified any further

❓ Based on the discussions until now, we seem to converge here. Please, let me know if I misunderstood something.

Use case 4

Given that user Alfred has a public/internal agent configuration project in group A
and user Bill has a private manifest project in group A
When Alfred adds the manifest project to the agent configuration
Then Bill receives an e-mail to authorize the agent
When Bill authorizes the agent
Then the agent can access the manifest project
And the agent shows up on the manifest project as being authorized
And the agent's authorization can be reoved on the manifest project page
When Bill does not authorize the agent
Then nothing is changed, nobody is notified any further

❓ Based on the discussions until now, we seem to converge here. Please, let me know if I misunderstood something.

Use case 5

Given that user has a group level agent configuration project in group A
and a user has a private manifest project in group A
When the user adds the manifest project to the configuration project
Then the agent can automatically access the given project

Needs support for group level agents

Use case 6

Given that user has a group level agent configuration project in group A
and a user has a public manifest project in group A
When the user adds the manifest project to the configuration project
Then we can already support this setup

Needs support for group level agents

Security boundaries are hard

Cross-group access is not allowed.

❓ Based on the discussions until now, we seem to converge here. Please, let me know if I misunderstood something.

Given that user Alfred has a private agent configuration project in group A
and user Bill has a private manifest project in group B
When Alfred adds the manifest project to the agent configuration
Then we notify Alfred that crossing groups is not allowed.
Given that user Alfred has a public/internal agent configuration project in group A
and user Bill has a private manifest project in group B
When Alfred adds the manifest project to the agent configuration
Then we notify Alfred that crossing groups is not allowed.
Given that user has a group level agent configuration project in group A
and a user has a private manifest project in group A
When the user adds the manifest project to the configuration project
Then we notify the user that crossing groups is not allowed.
Given that user has a group level agent configuration project in group A
and a user has a public manifest project in group B
When the user adds the manifest project to the configuration project
Then we notify the user that crossing groups is not allowed.

Moving manifest projects around

One option is here to keep "security boundaries are hard", and loose the authorization when a manifest project is moved to a different group.

Another option is to allow some kind of migration. Let's keep it simple, and start with restricting ourselved to hard security boundaries.

❓ What do you think about this simplification?

I'm trying to describe various use cases following the question what happens if the user later looses access to the manifest project

Given that the user has a configuration project in group A
and the user has a manifest project in group A
and the user is a member of group B
When the manifest project is moved to group B
Then the user has to update the configuration project with the group B path of the manifest project
And ... do we need re-authorization or not?
...
Given that the user has a configuration project in group A
and the user has a manifest project in group A
and the user is not a member of group B
When the manifest project is moved to group B
...
Given that the user has a configuration project in group A
and the user has a manifest project in group A
When the user leaves the company
...
Edited by Thong Kuah