GitLab

GitLab's SAML implementation links a user's external IdP identity to their personal GitLab account. Members continue to log in to their personal accounts on github.com, and GitLab links each account to the 1Kosmos identity during the first SAML authentication. GitLab recommends using a persistent NameID that uniquely identifies each user, rather than an email address, to ensure stable account linkage over time.

SSO enforcement can be enabled after configuration, requiring all group members to authenticate through 1Kosmos before accessing group resources. Before enabling enforcement, save GitLab recovery codes to maintain admin access if the identity provider is unavailable.

Prerequisites

• Active 1Kosmos tenant: Administrator access to the AdminX portal. Contact 1kosmos.com/contact if not yet provisioned.

• GitLab.com Premium or Ultimate, or GitLab Self-Managed: Group Owner access to configure SAML SSO on the group settings page. SAML SSO is only configurable at the top-level group on GitLab.com.

• GitLab Self-Managed: Shell access or Rails console access to edit gitlab.rb for instance-wide SAML configuration.

• 1Kosmos mobile app installed: Users must have the app on iOS or Android with biometrics enrolled before testing.

Configuration values

Values to collect from 1Kosmos AdminX (IdP) for GitLab:

GitLab SP values to enter in AdminX:

Integration steps

Step 1: Collect SP values from GitLab

• Navigate to your top-level group on GitLab.com and go to Settings → SAML SSO. The Assertion consumer service URL, Identifier, and GitLab single sign-on URL are shown on this page. Copy the ACS URL and Identifier for use in AdminX.

• For GitLab Self-Managed, the SP metadata is available at https://HOSTNAME/users/auth/saml/metadata.

Step 2: Add GitLab as a SAML application in AdminX

• Log in to the AdminX portal and navigate to Applications → Add Application.

• Select SAML 2.0 Generic and click Add integration. Enter "GitLab" as the Application Name and your GitLab group or instance URL as the Application Access URL.

• Set NameID Format to urn:oasis:names:tc:SAML:2.0:nameid-format:persistent and NameID Value to a persistent user identifier (recommended: a unique user ID rather than email, since email can change). Add claims for email, first name, and last name.

• Enter the GitLab SP Entity ID and ACS URL. Enable Assertion signing and click Save.

Step 3: Enable SAML SSO in GitLab (GitLab.com groups)

• Navigate to your group → Settings → SAML SSO.

• Enter the 1Kosmos Identity provider single sign-on URL and paste the certificate fingerprint or certificate content.

• Select the Enable SAML authentication for this group checkbox and click Save changes.

• Set a Default membership role (Minimal Access recommended for new SSO members).

Step 4: Configure GitLab Self-Managed (if applicable)

• Edit /etc/gitlab/gitlab.rb and add the SAML OmniAuth provider configuration:

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    args: {
      assertion_consumer_service_url: "https://HOSTNAME/users/auth/saml/callback",
      idp_cert_fingerprint: "YOUR_1KOSMOS_CERT_SHA1_FINGERPRINT",
      idp_sso_target_url: "YOUR_1KOSMOS_SSO_URL",
      issuer: "https://HOSTNAME",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    args: {
      assertion_consumer_service_url: "https://HOSTNAME/users/auth/saml/callback",
      idp_cert_fingerprint: "YOUR_1KOSMOS_CERT_SHA1_FINGERPRINT",
      idp_sso_target_url: "YOUR_1KOSMOS_SSO_URL",
      issuer: "https://HOSTNAME",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    args: {
      assertion_consumer_service_url: "https://HOSTNAME/users/auth/saml/callback",
      idp_cert_fingerprint: "YOUR_1KOSMOS_CERT_SHA1_FINGERPRINT",
      idp_sso_target_url: "YOUR_1KOSMOS_SSO_URL",
      issuer: "https://HOSTNAME",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

• Run sudo gitlab-ctl reconfigure after saving the file.

Step 5: Test and enforce SSO

• Use the Verify SAML Configuration button on the group SAML SSO page to test the integration before enforcing.

• Once verified, enable Enforce SSO-only authentication for web activity if you want to require 1Kosmos for all group members.

Attribute mappings

Integration notes

GitLab SAML SSO on GitLab.com operates at the group level, not at the individual user account level. This means the integration protects resources within that group but does not prevent members from logging in to other GitLab groups or their personal profiles using their standard GitLab credentials.

Using a persistent, random NameID (rather than email address) reduces the risk of users being locked out when their email changes. GitLab provides metadata XML for the group via the SAML SSO settings page, which can be imported into AdminX to simplify configuration.