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:
- Priyanka set up the agent configuration project, and installs the agent
- Sasha creates the manifest project
Authorization and deployment setup:
- Sasha creates a deploy token under "Settings/Repository/Deploy Tokens"
- Sasha shares the deploy token credentials (username + password) with Priyanka, outside of GitLab
- 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.
- 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
- All private groups (names, paths) remain private only to their members
- All private projects (names, paths) remain private only to their members
- 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:
- Shipping "Use case 0" described next
- Adding support for group level agents: #283885 (closed)
- Using deploy tokens for authorization of private manifest projects: #268019 (comment 446183623)
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
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
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
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
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.
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.
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
...