[MVC] Beyond Identity integration
Summary
Utilizing GitLab’s existing functionality of allowing users to add GPG keys to their profile to sign commits, we will add an option to validate those GPG keys with a third-party system. After the option is set, any new key uploaded to a user’s profile will be validated against the third-party system. Any key that does not pass validation will be rejected and the user will be required to upload a new key.
When users push commits to the GitLab instance, a pre-receive check will be performed that will validate the signed commits against the GPG key stored in the user’s profile. If the key does not match for any of the commits, the push will be rejected and the user informed that the key used to sign the commits does not match the validated key in their profile. Any commit that is signed with the validated key in the user’s profile will be accepted.
This document is focused on the initial minimally viable change to support GPG validation with Beyond Identity. In this phase, machine accounts could be provisioned with GPG keys to push validated commits. Additional exploration is required for allowlisting of users or GPG keys to skip the validation.
Configuration options
- Admin area settings
- In the Repository section, add new checkbox option for Validate user GPG key against a third party-system
- Initially, the only third-party integration will be with Beyond Identity. When the new option is enabled, we will add a pre-selected radio button option for Beyond Identity
- When Validate user GPG key against a third-party system is enabled, add a required field for users to add an API token for authentication to the Beyond Identity API
- In the Repository section, add new checkbox option for Validate user GPG key against a third party-system
- Top-group settings
- Add an option labeled Reject unverified commits to the group Settings -> Repository -> Pre-defined push rules.
- The subtext should read: Users can only push commits to this repository if the commits are signed by a verified key in the user’s profile.
- Add a sub-setting to allow project owners to override this pre-receive scan for their project.
- This setting should be disabled by default
- Add an option labeled Reject unverified commits to the group Settings -> Repository -> Pre-defined push rules.
- Project settings
- Add an option labeled Reject unverified commits to the group Settings -> Repository -> Push rules section
- The subtext should read: Users can only push commits to this repository if the commits are signed by a verified key in the user’s profile.
- If project owner override is disabled, this setting will be checked and unchangeable.
- If project owner override is enabled, this setting will be checked and allow project owners to disable it.
- Add an option labeled Reject unverified commits to the group Settings -> Repository -> Push rules section
Gitaly implementation
No changes are expected to be required within Gitaly.
Gitaly already utilizes the Rails /internal/allowed
endpoint which Gitaly contacts prior to accepting changes on a push command. This would be the appropriate place to insert a secret scanning mechanism. Additionally, Gitaly already has the means to enumerate new blobs only. This has the added benefit that any such scanning would only scale with the size of the change and not with the size of the repository.
Rails implementation
GPG key added to user profile
- When a user navigates to the User Settings -> GPG Keys area, they are able to add a new GPG key.
- If Validate user GPG key against a third party-system is enabled, every key that is added to a user profile will be sent to Beyond Identity to be validated.
When the user clicks Add key, a call will be made to the Beyond Identity KeyManagement API endpoint.
- The token added in the Admin area will be used to authenticate with the API.
- The GitLab user’s email address and the key id will be sent to Beyond Identity for verification.
- NOTE: The user’s email address in GitLab must match the user’s email address in the Beyond Identity system.
- The Beyond Identity API will return one of the following status codes:
- 200
- Description: The GPG key was found with the given Key ID. Authorization status must be checked by inspecting the "authorized" field in the response.
- 400
- Description: Any required fields are missing, or formatted incorrectly.
- 401
- Description: The Authorization header provided in the request is invalid.
- 404
- Description: A GPG key was not found with the given Key ID.
- 500
- Description: Internal server error.
- 200
- If the status code is 200, the authorization status will be checked. If the key is authorized, the GPG key will be added to the user’s profile.
- If the key is not authorized, the user will be informed that they are not authorized to add this GPG key to their profile and the key will not be saved.
- If the status code is anything other than 200, the user will be informed of the error and the GPG key will not be saved.
New built-in push rule
- We will introduce a new built-in push rule to GitLab, similar to the existing rule which validates that commits are signed.
- This push rule would trigger a new push check using the /internal/allowed API: https://docs.gitlab.com/ee/development/internal_api/internal_api_allowed.html#push-checks
- The check will validate the key used to sign the commits in the push against the key added to the user profile.
- If the key does not match or any commit is not signed, the push will be rejected and the user will be informed why it was rejected.
- If all commits are signed with the verified key in the user’s profile, the push will be accepted.
This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.