Integrate with GitLab Self-Managed

Integrate JumpCloud and GitLab Self-Managed to provide your users with secure, seamless access while automating user identity management. By leveraging SAML Single Sign-On (SSO), you offer a convenient end-user login experience using a single set of credentials, which strengthens your security posture and boosts user productivity. Simultaneously, the Identity Management (SCIM) integration allows you to centralize the entire user lifecycle—automatically provisioning, updating, and deprovisioning accounts directly from the JumpCloud Admin Portal. This unified approach eliminates manual overhead, improves security by ensuring users always have the correct access, prevents the risk of orphaned accounts, and ensures that user data remains accurate and synchronized across your organization.

Read this article to learn how to integrate with Gitlab Self-Managed, formerly known as Gitlab Instance. If you are using GitLab SaaS, see Integrate with GitLab.

Prerequisites:

• GitLab Self-Managed version 18.0 or newer for group synchronization. Versions older than 18.0 do not support this functionality
• A GitLab Self-Managed instance
• An HTTPS-configured GitLab instance
• Your GitLab domain and Server URL
• Access to the command line to modify your /etc/gitlab/gitlab.rb configuration file
• A JumpCloud administrator account
• JumpCloud SSO Package or higher or SSO add-on feature

Important Considerations:

• SAML SSO is not supported at the subgroup level
• Account takeovers are not supported. For more information on this take a look here
• This integration supports Just-In-Time (JIT) provisioning, which automatically creates user accounts when a user first signs in through SAML. If you are using SCIM, we do not recommend using JIT.
• You can automatically link a SAML sign-in with existing GitLab users if their email addresses match
• Users authenticated with SSO must use personal, project, or group access tokens for Git operations over HTTPS rather than their JumpCloud password
• New users provisioned from JumpCloud will receive an email invitation from GitLab

Attribute Considerations:

• A default set of attributes are managed for users
• GitLab requires a claim containing the user’s email address using email or mail. Jump to Attribute Mappings for more details

Creating a new JumpCloud Application Integration

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications.
3. Click + Add New Application.
4. You can also enter the name of the application in the Search field and select it.
5. You can either select an application from the available list or select Custom Application, and click Next.
6. Select the required options from the Select Options page and click Next. The Enter General Info page is displayed.
7. On the Enter General Info page, you can customize the display label, description and how the application displays:
   • Description - add a description that users will see in their user portal
   • User Portal Image - choose Logo or Color Indicator
   • Show in User Portal - select to ensure the app is visible in the user portal
8. Optionally, expand the Advanced Settings section and customize the IdP URL:
   • Expand Advanced Settings and enter a custom value to replace the default application name in the SSO IdP URL endpoint ( https://sso.jumpcloud.com/saml2/{custom_value})

8. Click Save Application.
9. Next, click:
   • Configure Application and go to the next section
   • Close to configure your new application at a later time

Configuring the SAML SSO Integration for GitLab Self-Managed

To configure JumpCloud:

1. In JumpCloud's SSO Applications page, select the GitLab Instance/GitLab Self-Managed app from the Configured Applications list.
2. Click the SSO tab.
3. Click Save.

Download the JumpCloud metadata file

1. If you've closed the app:
   • Find your app in the Configured Applications list and select its checkbox
   • Click Export Metadata in the top right corner of the window
2. If you are still on the SSO tab of the app:
   • Click Export Metadata
3. The JumpCloud-<applicationname>-metadata.xml will be exported to your local Downloads folder.

To configure GitLab Self-Managed:

1. Log in to your GitLab server terminal.
2. Open the /etc/gitlab/gitlab.rb configuration file.
3. Add the following code block to the file. Replace the bracketed placeholders with your specific JumpCloud values:

Ruby

4. Save the file and reconfigure GitLab by running the following command: sudo gitlab-ctl reconfigure

Authorizing User SSO Access

Users are implicitly denied access to applications. After you connect an application to JumpCloud, you need to authorize user access to that application. You can authorize user access from the Applications, Users List or User Groups page. 

To authorize user access from the Application’s page

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications, then select the application to which you want to authorize user access.
3. Select the User Groups tab. If you need to create a new group of users, see Get Started: User Groups.
4. Select the check box next to the desired group of users to which you want to give access.
5. Click Save. 

To learn how to authorize user access from the Users or User Groups pages, see Authorize Users to an SSO Application.

Validating SSO user authentication workflow(s)

IdP-initiated user workflow

• Access the JumpCloud User Console
• Go to Applications and click an application tile to launch it
• JumpCloud asserts the user's identity to the SP and is authenticated without the user having to log in to the application

SP-initiated user workflow

• Go to the SP application login - generally, there is either a special link or an adaptive username field that detects the user is authenticated through SSO

• Login redirects the user to JumpCloud where the user enters their JumpCloud credentials
• After the user is logged in successfully, they are redirected back to the SP and automatically logged in

Configuring Identity Management

GitLab Self-Managed version 18.0 and newer supports Identity Management via SCIM, including group synchronization.

To configure GitLab Self-Managed:

1. Log in to your GitLab instance as an administrator.
2. Navigate to the group you want to sync and select Settings > SAML SSO.
3. Select Generate a SCIM token.
4. Copy the SCIM API endpoint URL and the SCIM token.

To configure JumpCloud:

1. In the JumpCloud Admin Portal, go to Access > SSO Applications.
2. Select your GitLab Self-Managed application and click the Identity Management tab.
3. Click Configure.
4. In the Base URL field, paste the SCIM API endpoint URL.
5. In the Token Key field, paste the SCIM token.
6. Click Activate and then Save.

Attribute Mappings

The Export Attribute Mapping table lists the Required and Optional Mappings that JumpCloud sends to the Service Provider.Important: It is highly recommended you use all optional mappings. This creates a more complete user profile, enabling better automation and more accurate access management within the application.

Removing the SSO Integration

To deactivate the SSO Integration

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications.
3. Search for the application that you’d like to deactivate and click to open its details panel. 
4. Select the SSO tab.
5. Scroll to the bottom of the configuration.
6. Click Deactivate SSO. 
7. Click Save. 
8. If successful, you will receive a confirmation message.

To delete the application

1. Log in to the JumpCloud Admin Portal.

2. Go to Access > SSO Applications.
3. Search for the application that you’d like to delete.
4. Check the box next to the application to select it.
5. Click Delete.
6. Enter the number of the applications you are deleting
7. Click Delete Application.
8. If successful, you will see an application deletion confirmation notification.