GitLab Connection

The OAuth method provides secure authentication through GitLab's OAuth flow.

Using the GitLab Connection with OAuth on a self-hosted instance of Hanzo KMS requires configuring an OAuth application in GitLab and registering your instance with it.

If you're self-hosting GitLab with custom certificates, you will have to configure your Hanzo KMS instance to trust these certificates. To learn how, please follow this guide.

Prerequisites:

• A GitLab account with existing projects
• Self-hosted Hanzo KMS instance

Navigate to your user Settings > Applications to create a new GitLab application.

Create the application. As part of the form, set the Redirect URI to https://your-domain.com/organization/app-connections/gitlab/oauth/callback.

Depending on your use case, add one or more of the following scopes to your application:

For Secret Syncs, your application will require the api scope:

For Secret Scanning, your application will require the api and read_repository scopes:

The domain you defined in the Redirect URI should be equivalent to the SITE_URL configured in your Hanzo KMS instance.

If you have a GitLab group, you can create an OAuth application under it in your group Settings > Applications.

Obtain the Application ID and Secret for your GitLab OAuth application.

Back in your Hanzo KMS instance, add two new environment variables for the credentials of your GitLab OAuth application:

• INF_APP_CONNECTION_GITLAB_OAUTH_CLIENT_ID: The Application ID of your GitLab OAuth application.
• INF_APP_CONNECTION_GITLAB_OAUTH_CLIENT_SECRET: The Secret of your GitLab OAuth application.

Once added, restart your Hanzo KMS instance and use the GitLab Connection.

Setup GitLab OAuth Connection in Hanzo KMS

Navigate to the Integrations tab in the desired project, then select App Connections.

Select the GitLab Connection option from the connection options modal.

Select the OAuth method and click Connect to GitLab.

You will be redirected to GitLab to grant Hanzo KMS access to your GitLab account. Once granted, you will be redirected back to Hanzo KMS's App Connections page.

Your GitLab Connection is now available for use.

The Access Token method uses a GitLab access token for authentication, providing a straightforward setup process.

Generate GitLab Access Token

Personal access tokens provide access to your GitLab account and all projects you have access to.

Log in to your GitLab account and navigate to User Settings > Access tokens. Click Add new token to create a new personal access token.

Fill in the token details:

• Token name: A descriptive name for the token (e.g., "connection-token")
• Expiration date: Set an appropriate expiration date
• Select scopes: Depending on your use case, add one or more of the following scopes:

For Secret Syncs, your token will require the api scope:

For Secret Scanning, your token will require the api and read_repository scopes:

Personal Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.

Copy the generated token immediately as it won't be shown again.

Keep your access token secure and do not share it. Anyone with access to this token can access your GitLab account and projects.

Project access tokens provide access to a specific GitLab project, offering more granular control.

Go to your GitLab project and navigate to Settings > Access Tokens. Click Add new token to create a new project access token.

Fill in the token details:

• Token name: A descriptive name for the token
• Expiration date: Set an appropriate expiration date
• Select role and scopes: Depending on your use case, add the required role and one or more of the following scopes:

For Secret Syncs, your token will require the api scope and at least the Owner role:

For Secret Scanning, your token will require the api and read_repository scopes and the Maintainer role:

Project Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.

Copy the generated token immediately as it won't be shown again.

Keep your access token secure and do not share it. Anyone with access to this token can access your GitLab account and projects.

Group access tokens provide access to all projects within a GitLab group, offering group-level control.

Go to your GitLab group and navigate to Settings > Access Tokens. Click Add new token to create a new group access token.

Fill in the token details:

• Token name: A descriptive name for the token
• Expiration date: Set an appropriate expiration date
• Select role and scopes: Depending on your use case, add the required role and one or more of the following scopes:

For Secret Syncs, the required role depends on your sync destination:

• Project variables: Requires Maintainer role or higher
• Group variables: Requires Owner role

Your token will require the api scope.

Click Create group access token to create the token.

Use the Owner role if you need to sync to group-level variables. The Maintainer role is sufficient only for project-level variables.

To set up Secret Scanning, the required permissions depend on the data source level:

• Project-level data source: Requires Maintainer role or higher
• Group-level data source: Requires Owner role

Your token will require the api scope.

Click Create group access token to create the token.

Group Access Token connections require manual token rotation when your GitLab access token expires or is regenerated. Monitor your connection status and update the token as needed.

Copy the generated token immediately as it won't be shown again.

Keep your access token secure and do not share it. Anyone with access to this token can access all projects within your GitLab group.

Setup GitLab Access Token Connection in Hanzo KMS

Navigate to the Integrations tab in the desired project, then select App Connections.

Select the GitLab Connection option from the connection options modal.

Select the Access Token method, paste your GitLab access token in the provided field, and select the appropriate token type.

Click Connect to establish the connection.

Your GitLab Connection is now available for use.