GitLab integration through SAML or OpenID-Connect

Overview

This document explains how to integrate GitLab with the RCDevs OpenOTP Identity Provider (IdP) using either SAML2 or OpenID Connect.
Only one integration method should be configured at a time.
The integration enables Single Sign-On (SSO) for GitLab users via the OpenOTP Authentication Server.

This integration requires:

A running WebADM/OpenOTP server environment.
A configured RCDevs Identity Provider.

GitLab configuration

Example GitLab Omnibus Configuration

Below is the Gitlab configuration which has been used for this documentation.

      GITLAB_OMNIBUS_CONFIG: |
        external_url 'https://gitlab.rcdevsdocs.com/'
        gitlab_rails['trusted_proxies'] = ["172.20.0.2"]
        gitlab_rails['db_adapter'] = "postgresql"
        gitlab_rails['db_encoding'] = "unicode"
        gitlab_rails['db_database'] = "gitlab"
        gitlab_rails['db_username'] = "postgres"
        gitlab_rails['db_password'] = "**********"
        gitlab_rails['db_host'] = "postgresql-postgresql-1"
        gitlab_rails['db_port'] = 5432
        gitlab_rails['gitlab_email_enabled'] = false
        gitlab_rails['time_zone'] = 'Europe/Paris'
        gitlab_rails['initial_root_password'] = "************"
        letsencrypt['enable'] = false
        gitlab_rails['content_security_policy'] = {
            'enabled' => true,
            'report_only' => true,
        }
        nginx['redirect_http_to_https'] = true
        nginx['listen_port'] = 80
        nginx['listen_port'] = 443
        nginx['ssl_certificate'] = "/etc/gitlab/certs/gitlab.crt"
        nginx['ssl_certificate_key'] = "/etc/gitlab/certs/gitlab.key"
        nginx['ssl_client_certificate'] = "/etc/gitlab/certs/ca.crt"
        gitlab_rails['log_level'] = 'debug'
        gitlab_rails['omniauth_logging_enabled'] = true
        gitlab_rails['omniauth_enabled'] = true
        gitlab_rails['omniauth_allow_single_sign_on'] = true
        gitlab_rails['omniauth_block_auto_created_users'] = false

SAML IdP configuration on GitLab

You can obtain the necessary RCDevs IdP information from the SAML metadata page, typically available at:

https://<your-idp-url>/ws/saml

For this documentation, the URL is:

https://sso.rcdevsdocs.com/ws/saml

This page provides an output similar to the following:

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://sso.rcdevsdocs.com">
<IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<KeyDescriptor use="signing">
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<X509Data>
<X509Certificate>
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
</X509Certificate>
<!--
 Cert Fingerprint (SHA1): 32774463a2e892150f46852b3fdcac7f5be924dc 
-->
<!--
 Cert Fingerprint (SHA256): e0bd10584f5c3a554e279b9241619e8fdf9c3bfbe95c90da939f0342546e52ac 
-->
<!--
 Cert Fingerprint (MD5): 639ed5b4241047c8382f897fc459a714 
-->
</X509Data>
</KeyInfo>
</KeyDescriptor>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://sso.rcdevsdocs.com/openid/index.php"/>
<SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sso.rcdevsdocs.com/openid/index.php"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://sso.rcdevsdocs.com/openid/index.php"/>
<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://sso.rcdevsdocs.com/openid/index.php"/>
</IDPSSODescriptor>
</EntityDescriptor>

Locate your GitLab configuration file according to your setup and configure the following section for SAML based authentication:

...
 gitlab_rails['omniauth_providers'] = [
           {
            name: "saml",
            label: "saml", # optional label for login button, defaults to "Saml"
            groups_attribute: 'groups',
            required_groups: ['gitlab'], # Choose your own required group(s). It must be returned in the SAML Assertion
            admin_groups: ['Domain Admins'], # Choose your own admin group(s). It must be returned in the SAML Assertion
            args: {
              assertion_consumer_service_url: "https://gitlab.rcdevsdocs.com/users/auth/saml/callback",
              idp_cert_fingerprint: "32:77:44:63:a2:e8:92:15:0f:46:85:2b:3f:dc:ac:7f:5b:e9:24:dc",
              idp_sso_target_url: "https://sso.rcdevsdocs.com/openid/index.php",
              issuer: "https://gitlab.rcdevsdocs.com/",
              name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
              attribute_statements: { nickname: ['uid'] }
            }
          }

        ]
...

OpenID-Connect IdP configuration on GitLab

You can obtain the necessary RCDevs IdP information from the OpenID metadata page, typically available at:

https://sso.rcdevsdocs.com/ws/openid

https://sso.rcdevsdocs.com/openid/.well-known/openid-configuration

https://sso.rcdevsdocs.com/webapps/openid/.well-known/openid-configuration

This page provides an output similar to the following:

{
    "issuer": "https://sso.rcdevsdocs.com",
    "authorization_endpoint": "https://sso.rcdevsdocs.com/openid/index.php",
    "token_endpoint": "https://sso.rcdevsdocs.com/openid/index.php",
    "userinfo_endpoint": "https://sso.rcdevsdocs.com/openid/index.php",
    "jwks_uri": "https://sso.rcdevsdocs.com/openid/certs.php",
    "subject_types_supported": [
        "public",
        "pairwise"
    ],
    "response_types_supported": [
        "code",
        "token",
        "id_token"
    ],
    "response_modes_supported": [
        "query",
        "fragment",
        "form_post"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "claim_types_supported": [
        "normal"
    ],
    "scopes_supported": [
        "basic",
        "openid",
        "email",
        "phone",
        "profile",
        "groups"
    ],
    "claims_supported": [
        "sub",
        "email",
        "email_verified",
        "phone_number",
        "phone_number_verified",
        "preferred_username",
        "preferred_language",
        "given_name",
        "family_name",
        "name",
        "groups",
        "mfa-policy",
        "amr",
        "acr",
        "RCDevsMfa"
    ]
}

Locate you GitLab configuration file according to your setup and configure the following section for SAML based authentication:

...
 gitlab_rails['omniauth_providers'] = [
          {
            name: "openid_connect", # do not change this parameter
            label: "openid",
            args: {
              scope: ["openid","profile","email", "groups"],
              response_type: "code",
              issuer: "https://sso.rcdevsdocs.com",
              discovery: true,
              client_auth_method: "query",
              uid_field: 'sub',
              client_options: {
                port: 443,
                scheme: "https",
                host: "sso.rcdevs.com",
                identifier: "gitlab",
                secret: "gitlab",
                redirect_uri: "https://gitlab.rcdevsdocs.com/users/auth/openid_connect/callback",
                gitlab: {
                  groups_attribute: 'groups',
                  required_groups: ["gitlab"], # Choose your own required group(s). Groups are returned when the GitLab is calling the UserInfo endpoint of the IdP.
                  admin_groups: ["Domain Admins"] # Choose your own Admin group(s). Groups are returned when the GitLab is calling the UserInfo endpoint of the IdP.
                }
               }
             }
          }
...

GitLab configuration on the IdP (Client Policy)

Configuring GitLab on the RCDevs IdP involves creating a client policy and defining the required Service Provider (SP) parameters.

Additionally, the IdP must return the group attributes expected by GitLab so that user roles can be correctly mapped after authentication and redirection.

Client Policies

Create a new Client Policy for GitLab:

Log in to the WebADM Administrator Portal.
Go to the Admin tab → Client Policies → click Add Client.
Enter a Name for the client policy and optionally add a Description.
Click Proceed, then Create Object to open the policy configurator.

In the configurator:

Set the Default Domain.
Optionally define a Friendly Name.
In Client Name Aliases setting, configure:
- for SAML configuration, configure the external_url of your GitLab global configuration. In this example: https://gitlab.rcdevsdocs.com/

for the OpenID configuration, configure the identifier value configured in the OpenID section on GitLab.

Scroll down to Default Application Settings, enable the Enforced Settings checkbox, and click Edit.
In the Applications section, select OpenID & SAML Provider and configure it as follows:

The Name Identifier configured in the client policy can be set to transient or PrincipalName when authenticating Active Directory users, provided that the UserPrincipalName attribute is available for the user account in WebADM.

For SAML:
You must configure the Assertion Consumer Service (ACS) URL, which can be obtained from the GitLab SAML configuration.

For OpenID:
You must configure the client secret, which can be obtained from the GitHub OpenID configuration. Here we configured "gitlab":

Once these settings are configured you can configure the authentication settings from the Applications box > MFA Authentication Server.

Configure the desired settings, then click the Apply buttons to save the settings and the policy.

Configuration is complete. You can now attempt to log in from your GitLab, using SAML or OpenID-Connect. You should be redirected to your Identity Provider’s login page. After successful authentication, you should be redirected and authenticated to GitLab.