docs: add GitLab OAuth setup and provider enrollment guide#6477
Conversation
Tested end-to-end on local Minder instance. Documents the feature flag, server config, OAuth app setup, and enrollment steps. Refs mindersec#6435
|
coverage: 60.449% (+0.003%) from 60.446% — intelligent-ears:docs/gitlab-provider-setup into mindersec:main |
evankanderson
left a comment
evankanderson
left a comment
There was a problem hiding this comment.
Thanks for documenting this! I was able to create a GitLab provider and register a repository. Interestingly, it only showed up in my minder repo list when I explicitly listed by provider; that seems to be an API behavior which is mirrored by the GitHub App implementation when you have multiple apps installed, so I think it is expected.
The OAuth flow implemented by the GitLab implementation means that Minder is acting as the user who authenticates, rather than as something like a service account in the GitHub model. This means that if the registering user loses access to a repository (e.g. leaves a company / project), Minder will no longer be able to execute policy until the OAuth token is rotated via minder provider enroll.
Also, it appears that creating a service account in a group using using the service account's PAT doesn't work because GitLab PATs contain ".", and our validation pattern doesn't permit "." as a valid character.
| http://localhost:8080/api/v1/auth/callback/gitlab/web | ||
| ``` | ||
| - **Confidential:** Yes (checked) | ||
| - **Scopes:** Check `api`, `read_user`, and `read_repository` |
There was a problem hiding this comment.
Do we need write_repository to be able to create branches for PR remediations?
There was a problem hiding this comment.
What about read_registry for artifacts? I'm guessing the GitLab provider doesn't yet support the container / artifact provider facet...
There was a problem hiding this comment.
Do we need
write_repositoryto be able to create branches for PR remediations?
Not needed currently — the GitLab provider doesn't yet implement PR remediation or branch creation. I'll leave it out for now and it can be added when that's implemented.
There was a problem hiding this comment.
What about
read_registryfor artifacts? I'm guessing the GitLab provider doesn't yet support the container / artifact provider facet...
Correct — artifact/container registry support isn't implemented in the GitLab provider yet. Leaving it out of the minimum required scopes
| http://localhost:8080/api/v1/auth/callback/gitlab/web | ||
| ``` | ||
| - **Confidential:** Yes (checked) | ||
| - **Scopes:** Check `api`, `read_user`, and `read_repository` |
There was a problem hiding this comment.
Should read_user be openid or profile?
There was a problem hiding this comment.
("profile") worked for me for registering a repository using the OAuth flow. As mentioned, the service account flow seems to be broken for GitLab, so we'll need a separate PR for that (which may also want to add user documentation for registering a GitLab repository, with best practices).
There was a problem hiding this comment.
Good catch — updating to profile as you confirmed it works. read_user gives broader access than needed.
|
I can merge this as-is and we can follow up with adjustments, or you can make changes and I can re-approve -- your choice! |
I'll update the scopes, cleaner to get it right |
… expand known limitations
evankanderson
left a comment
evankanderson
left a comment
There was a problem hiding this comment.
Two notes for coming back to this PR later, but I think this is good to merge. Thanks for exploring and documenting this!
I think next steps would include:
- Fixing the service account thing (should be a simple fix, I can PR that today probably)
- Defining a "pr" provider facet which both GitLab and GitHub can implement, to enable more remediations for GitLab
- Figure out what's needed for datasource provider auth for GitLab, if anything
- Look at the OSPS-Baseline rules and figure out what the GitLab coverage fraction is, and how to increase to 100% of level-1.
- Possibly defining a "gitlab" facet to cover GitLab specific APIs, but I'm not sure what it would contain (so maybe hold off on this)
| ## Access model | ||
|
|
||
| Minder acts as the authenticated GitLab user when managing repositories. This | ||
| means: |
There was a problem hiding this comment.
At some point, we should have per-provider documentation that covers this, but I think this is fine for now.
| - GitLab service account PATs are not currently supported due to a validation | ||
| issue with the `.` character in PAT tokens. |
There was a problem hiding this comment.
PAT is the only mechanism for service accounts, but it should be easy to fix the validation problem.
3 participants
Summary
Adds documentation for setting up and enrolling the GitLab provider on a self-hosted Minder instance. This is the first deliverable toward closing #6435.
What was tested
The full enrollment flow was tested end-to-end on a local Minder instance:
make run-dockergitlab_providerfeature flag viaflags-config.yamlserver-config.yamlwith the GitLab OAuth credentialsminder provider enroll --class gitlabChanges
docs/docs/run_minder_server/config_gitlab_oauth.md— new guide covering:gitlab_providerfeature flagserver-config.yamlNotes
redirect_uriinserver-config.yamlmust be the base path (/api/v1/auth/callback/gitlab) without/clior/web— the server appends the correct suffix. This tripped me up during testing and is now explicitly documented./cliand/webredirect URIs registered, not just one.gitlab_providerfeature flag and is not enabled onapi.custcodian.dev. This is documented as a known limitation.Closes #6435 (partial — this covers the documentation and testing setup portion of the epic)