GitLab

This guide explains how to set up single sign-on (SSO) between VaultysHub and GitLab. GitLab supports both OpenID Connect and SAML2 - we recommend OpenID Connect for its simplicity.

Prerequisites

• GitLab CE/EE version 11.4+ (for OpenID Connect)
• GitLab CE/EE version 9.0+ (for SAML2)
• Administrator access to GitLab
• Application configured in VaultysHub

Configuration with OpenID Connect (Recommended)

Configuration in VaultysHub

1. Create the application

1. Log in to VaultysHub as an administrator
2. Go to Applications → Add
3. Create a new application:
   • Name: GitLab
   • URL: https://gitlab.example.com
   • Description: GitLab DevOps Platform
   • Icon: Choose the GitLab icon

2. Configure OpenID Connect

1. In the Authentication tab
2. Select OpenID Connect
3. Note the information:
   • Client ID: gitlab-xxxxxx
   • Client Secret: secret-xxxxxx
   • Issuer URL: https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]
   • App ID: [appid] (unique identifier of the application in VaultysHub)

3. Redirect URLs

Add to Allowed redirect URLs:

https://gitlab.example.com/users/auth/openid_connect/callback

4. Required scopes

• openid
• profile
• email

Configuration in GitLab

1. Omnibus configuration (gitlab.rb)

Edit /etc/gitlab/gitlab.rb:

### OpenID Connect configuration with VaultysHub ###

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
gitlab_rails['omniauth_sync_email_from_provider'] = 'openid_connect'
gitlab_rails['omniauth_sync_profile_from_provider'] = ['openid_connect']
gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email']
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'openid_connect'
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "VaultysHub SSO",
    icon: "https://your-vaultyshub.example.com/logo.png",
    args: {
      name: "openid_connect",
      scope: ["openid", "profile", "email"],
      response_type: "code",
      issuer: "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]",
      discovery: true,
      discovery_endpoint: "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration",
      client_auth_method: "query",
      uid_field: "sub",
      send_scope_to_token_endpoint: "false",
      pkce: true,
      client_options: {
        identifier: "gitlab-xxxxxx",
        secret: "secret-xxxxxx",
        redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
      }
    }
  }
]

# Additional options (optional)
gitlab_rails['omniauth_external_providers'] = ['openid_connect']
gitlab_rails['omniauth_allow_bypass_two_factor'] = ['openid_connect']

2. Docker configuration

For GitLab Docker, use environment variables:

version: '3.8'
services:
  gitlab:
    image: gitlab/gitlab-ee:latest
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        gitlab_rails['omniauth_enabled'] = true
        gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
        gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'openid_connect'
        gitlab_rails['omniauth_providers'] = [
          {
            name: "openid_connect",
            label: "VaultysHub SSO",
            args: {
              name: "openid_connect",
              scope: ["openid", "profile", "email"],
              response_type: "code",
              issuer: "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]",
              discovery: true,
              discovery_endpoint: "https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration",
              uid_field: "sub",
              client_options: {
                identifier: "${OIDC_CLIENT_ID}",
                secret: "${OIDC_CLIENT_SECRET}",
                redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
              }
            }
          }
        ]

3. Apply the configuration

# For Omnibus
gitlab-ctl reconfigure
gitlab-ctl restart

# For Docker
docker-compose up -d

Group synchronization

VaultysHub does not transmit user groups (no scope or claim groups). GitLab groups are therefore managed directly in GitLab.

Configuration with SAML2

Configuration in VaultysHub

1. Configure SAML2

1. In the GitLab application
2. Authentication tab → SAML2
3. Configure:
   • Entity ID: https://gitlab.example.com
   • ACS URL: https://gitlab.example.com/users/auth/saml/callback
   • NameID Format: emailAddress

2. Download the metadata

Download or note:

• IdP Metadata: https://your-vaultyshub.link.vaultys.org/api/saml2/metadata/[appid]
• X.509 Certificate
• SSO URL: https://your-vaultyshub.link.vaultys.org/api/saml2/sso/[appid]

Single Logout from VaultysHub is not supported.

Configuration in GitLab

# In /etc/gitlab/gitlab.rb

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "VaultysHub SSO",
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
      idp_sso_target_url: "https://your-vaultyshub.link.vaultys.org/api/saml2/sso/[appid]",
      idp_metadata_url: "https://your-vaultyshub.link.vaultys.org/api/saml2/metadata/[appid]",
      issuer: "https://gitlab.example.com",
      name_identifier_format: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      attribute_statements: {
        email: ['email'],
        first_name: ['firstName'],
        last_name: ['lastName']
      }
    }
  }
]

Permission management

Role mapping

VaultysHub does not transmit user groups or roles. Roles (administrator, external user, auditor…), group and project membership in GitLab, as well as license assignment, are managed directly in GitLab.

User configuration

User profile configuration

# Full profile synchronization
gitlab_rails['omniauth_sync_profile_from_provider'] = ['openid_connect']
gitlab_rails['omniauth_sync_profile_attributes'] = [
  'name',
  'email'
]

Configuration testing

1. Login test

1. Log out of GitLab
2. On the login page, click on VaultysHub SSO
3. Authenticate on VaultysHub
4. Check the redirection to GitLab

2. Permission verification

# Via GitLab API
curl -H "PRIVATE-TOKEN: your_token" \
  "https://gitlab.example.com/api/v4/user"

# Via Rails console
gitlab-rails console
user = User.find_by_email('[email protected]')
user.identities
user.group_members

3. Test with Git

# Clone with SSO
git clone https://gitlab.example.com/group/project.git

# If prompted, use:
# Username: oauth2
# Password: [your personal access token]

Troubleshooting

Error "Could not authenticate you from OpenIDConnect"

Solution:

1. Check GitLab logs:

   gitlab-ctl tail gitlab-rails

2. Test OIDC discovery with your appid:

   curl https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/.well-known/openid-configuration

3. Verify the Client ID and Secret

Groups are not synchronized

Solution: this is the expected behavior. VaultysHub does not transmit groups: manage group membership directly in GitLab.

Error 422 after authentication

Solution:

1. Ensure the email is unique in GitLab
2. Enable auto-link:

   gitlab_rails['omniauth_auto_link_user'] = ['openid_connect']

Users blocked after creation

Solution:

# Disable automatic blocking
gitlab_rails['omniauth_block_auto_created_users'] = false

# Or unblock manually
gitlab-rails console
User.where(state: 'blocked').update_all(state: 'active')

Security

Recommendations

1. HTTPS required on GitLab and VaultysHub
2. Regular secret rotation
3. Audit logs enabled:

   gitlab_rails['audit_events_enabled'] = true

4. 2FA bypass only if VaultysHub manages MFA:

   gitlab_rails['omniauth_allow_bypass_two_factor'] = ['openid_connect']

CSRF Protection

# Protection against CSRF attacks
gitlab_rails['omniauth_providers'] = [
  {
    args: {
      pkce: true,  # Use PKCE for OpenID Connect
      state: true  # Check the state parameter
    }
  }
]

Advanced configuration

Multi-instance GitLab

For multiple GitLab instances with the same VaultysHub:

# Production instance
gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    args: {
      client_options: {
        identifier: "gitlab-prod-xxxxxx",
        redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
      }
    }
  }
]

# Staging instance
gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect", 
    args: {
      client_options: {
        identifier: "gitlab-staging-xxxxxx",
        redirect_uri: "https://gitlab-staging.example.com/users/auth/openid_connect/callback"
      }
    }
  }
]

CI/CD Integration

To use SSO in pipelines:

# .gitlab-ci.yml
variables:
  CI_JOB_TOKEN_SCOPE: "openid_connect"

deploy:
  script:
    - |
      TOKEN=$(curl -X POST https://your-vaultyshub.link.vaultys.org/api/oidc/[appid]/token \
        -d "grant_type=client_credentials" \
        -d "client_id=${CI_CLIENT_ID}" \
        -d "client_secret=${CI_CLIENT_SECRET}")
    - # Use $TOKEN for deployments

Resources

• GitLab OmniAuth Documentation
• GitLab OpenID Connect
• GitLab SAML
• VaultysHub SAML2 Configuration