Comprehensive GitLab SSO Configuration Guide

This comprehensive guide covers Single Sign-On (SSO) setup for both GitLab.com and GitLab Self-Managed instances using SAML authentication with multiple identity providers including Okta, Microsoft Entra ID (Azure AD), and Google Workspace.

Overview

GitLab supports SSO through SAML (Security Assertion Markup Language) protocol, enabling users to authenticate using their organization's identity provider. This guide covers:

• GitLab.com Group SAML SSO - For GitLab SaaS groups (Premium/Ultimate tiers)
• GitLab Self-Managed SAML - For on-premises GitLab instances
• Identity Provider Setup - Detailed configuration for Okta, Microsoft Entra ID, and Google Workspace

Prerequisites

Before starting, ensure you have:

• GitLab Premium or Ultimate subscription (for GitLab.com groups)
• Administrative access to your identity provider (Okta, Microsoft Entra ID, or Google Workspace)
• Group Owner permissions in GitLab (for GitLab.com)
• Administrative access to GitLab instance (for self-managed)
• Basic understanding of SAML, OAuth 2.0, and identity management concepts

Part 1: GitLab.com Group SAML SSO

GitLab.com Group SAML SSO allows users to sign in through their organization's identity provider for accessing specific groups and projects.

Key Features

• Group-level SSO - Configure SSO for top-level groups only
• SCIM synchronization - Automatically sync users with groups
• SSO enforcement - Control access through identity provider
• Multiple identity providers - Support for various SAML 2.0 compliant providers

Basic Setup Process

1. Configure your identity provider (detailed in Part 3)
2. Set up GitLab Group SAML SSO
3. Test and verify configuration
4. Configure user access and permissions

GitLab.com SAML Configuration

Step 1: Access Group SAML Settings

1. Navigate to your GitLab group
2. Go to Settings > SAML SSO
3. Note the GitLab-provided URLs and identifiers

Step 2: Configure SAML Settings

GitLab Setting	Description	Usage
Identifier	Entity ID for your GitLab group	Used in IdP configuration
Assertion Consumer Service URL	Callback URL for SAML responses	Configure in your IdP
GitLab single sign-on URL	URL users visit to initiate SSO	Share with users
Identity provider single sign-on URL	SSO URL from your IdP	Obtain from IdP configuration
Certificate fingerprint	X.509 certificate fingerprint	Obtain from IdP

Step 3: Identity Provider Configuration

Configure the following in your identity provider:

Required Attributes:

• Name ID: Unique user identifier
• Email: User's email address
• First Name: User's given name
• Last Name: User's family name

Optional Attributes:

• Groups: For group synchronization
• Role: For role-based access control

SSO Enforcement Options

Transparent SSO Enforcement

• Automatically enabled when SAML SSO is configured
• 24-hour session timeout - Users prompted to re-authenticate after 24 hours
• Applies to users with SAML identity - Only affects users who have signed in via SSO

SSO-Only Authentication Enforcement

Enable "Enforce SSO-only authentication for web activity" to:

• Require all group members to use SSO
• Prevent manual user additions
• Block access without valid SSO session

Git and Dependency Proxy Enforcement

Enable "Enforce SSO-only authentication for Git and Dependency Proxy activity" to:

• Require SSO for Git operations (push/pull)
• Require SSO for Dependency Proxy usage
• Apply to all Git activity over SSH and HTTPS

User Management

Adding Users

Users can be added through:

1. SAML SSO sign-in - Automatic addition during first sign-in
2. SCIM provisioning - Automatic synchronization from IdP
3. Manual invitation - If SSO enforcement is not enabled

Removing Users

To remove user access:

1. Remove from IdP - Remove user from identity provider
2. Remove from GitLab group - Remove user from GitLab group
3. Use Group Sync - Automatic removal with SCIM

Account Unlinking

Users can unlink SAML accounts from their profile:

1. Go to Profile > Account
2. Find Service sign-in section
3. Click Disconnect next to the connected account

⚠️ Note: Unlinking removes all group roles. Roles must be reassigned if the user re-links.

Group Sync and SCIM

SCIM Benefits

• Automatic user provisioning - Add users to GitLab when added to IdP
• Automatic deprovisioning - Remove users from GitLab when removed from IdP
• Group synchronization - Sync group memberships
• Attribute synchronization - Keep user attributes updated

Setting up SCIM

1. Enable SCIM in GitLab:

   • Go to Settings > SAML SSO
   • Note the SCIM endpoint URL and token

2. Configure SCIM in your IdP:

   • Use the SCIM endpoint URL
   • Configure authentication with the provided token
   • Map user attributes correctly

Part 2: GitLab Self-Managed SAML SSO

GitLab Self-Managed instances support instance-wide SAML configuration, allowing all users to authenticate through your organization's identity provider.

Configuration Overview

Self-managed GitLab SAML configuration involves:

1. Editing GitLab configuration file (gitlab.rb or gitlab.yml)
2. Configuring identity provider
3. Restarting GitLab services
4. Testing and verification

GitLab Configuration File Setup

For Omnibus GitLab (gitlab.rb)

Add the following configuration to /etc/gitlab/gitlab.rb:

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

gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
      idp_cert_fingerprint: 'YOUR_IDP_CERT_FINGERPRINT',
      idp_sso_target_url: 'https://your-idp.com/sso/saml',
      issuer: 'https://gitlab.example.com',
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
      attribute_statements: {
        email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'],
        first_name: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'],
        last_name: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'],
        username: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name']
      }
    },
    label: 'Company SSO'
  }
]

For Source Installation (gitlab.yml)

Add the following to config/gitlab.yml:

production: &base
  omniauth:
    enabled: true
    allow_single_sign_on: ["saml"]
    block_auto_created_users: false
    auto_link_ldap_user: false
    auto_link_saml_user: true
    providers:
      - {
          name: 'saml',
          args: {
            assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
            idp_cert_fingerprint: 'YOUR_IDP_CERT_FINGERPRINT',
            idp_sso_target_url: 'https://your-idp.com/sso/saml',
            issuer: 'https://gitlab.example.com',
            name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
            attribute_statements: {
              email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'],
              first_name: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname'],
              last_name: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname'],
              username: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name']
            }
          },
          label: 'Company SSO'
        }

Configuration Parameters

Parameter	Description	Example
assertion_consumer_service_url	GitLab callback URL	https://gitlab.example.com/users/auth/saml/callback
idp_cert_fingerprint	IdP certificate fingerprint	AA:BB:CC:DD:...
idp_sso_target_url	IdP SSO endpoint	https://idp.example.com/sso/saml
issuer	GitLab entity ID	https://gitlab.example.com
name_identifier_format	SAML NameID format	urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Advanced Configuration Options

Additional Settings

# Auto-sign in with SAML (skip GitLab login page)
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'

# Allow users to bypass two-factor authentication
gitlab_rails['omniauth_saml_no_multi_factor_auth'] = true

# Custom button text
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    label: 'Single Sign-On', # Custom button text
    # ... other configuration
  }
]

# Group membership mapping
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      # ... other configuration
      groups_attribute: 'Groups',
      external_groups: ['Contractors', 'Vendors'],
      required_groups: ['GitLab-Users']
    }
  }
]

Security Settings

# Require HTTPS for SAML
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      # ... other configuration
      security: {
        want_assertions_signed: true,
        want_assertions_encrypted: true,
        want_name_id_encrypted: false,
        metadata_signed: false,
        embed_sign: true,
        digest_method: XMLSecurity::Document::SHA256,
        signature_method: XMLSecurity::Document::RSA_SHA256
      }
    }
  }
]

Apply Configuration

For Omnibus GitLab

sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

For Source Installation

sudo service gitlab restart

User Account Linking

Automatic Account Linking

Set auto_link_saml_user: true to automatically link existing GitLab accounts with SAML identities based on email address.

Manual Account Linking

Users can manually link accounts by:

1. Signing in to GitLab with existing credentials
2. Going to Profile Settings > Account
3. Clicking Connect next to SAML provider

Part 3: Identity Provider Configuration

This section provides detailed configuration instructions for popular identity providers. These configurations work for both GitLab.com and self-managed instances.

Okta Configuration

Based on our existing Okta SSO documentation, here's how to configure Okta for GitLab:

Create Okta Application

1. Access Okta Admin Console:

   • Navigate to https://[your-domain].okta.com
   • Click Admin in the top right corner
   • Sign in with administrator credentials

2. Create SAML Application:

   • Go to Applications > Applications
   • Click Create App Integration
   • Select SAML 2.0
   • Click Next

Configure SAML Settings

General Settings:

• App name: GitLab
• App logo: Upload GitLab logo (optional)

SAML Settings:

Okta Field	GitLab.com Value	Self-Managed Value
Single sign on URL	https://gitlab.com/groups/YOUR_GROUP/-/saml/acs	https://gitlab.example.com/users/auth/saml/callback
Audience URI (SP Entity ID)	https://gitlab.com/groups/YOUR_GROUP	https://gitlab.example.com
Name ID format	Persistent	Persistent
Application username	Custom: user.getInternalProperty("id")	Email or custom

Attribute Statements:

Name	Name format	Value
email	Basic	user.email
first_name	Basic	user.firstName
last_name	Basic	user.lastName
username	Basic	user.login

Group Attribute Statements (Optional):

Name	Name format	Filter	Value
Groups	Basic	Matches regex: .*	getFilteredGroups({"00g0x0x0x0x0x0x0": "Developers"}, "group.name", 40)

Complete Configuration

1. Finish Application Setup:

   • Click Next
   • Select I'm an Okta customer adding an internal app
   • Click Finish

2. Assign Users and Groups:

   • Go to Assignments tab
   • Click Assign > Assign to People or Assign to Groups
   • Select appropriate users/groups
   • Click Done

3. Get Identity Provider Details:

   • Go to Sign On tab
   • Click View Setup Instructions
   • Copy the following for GitLab configuration:
     • Identity Provider Single Sign-On URL
     • Identity Provider Issuer
     • X.509 Certificate (download and calculate fingerprint)

Calculate Certificate Fingerprint

# Extract certificate from Okta and calculate SHA1 fingerprint
openssl x509 -noout -fingerprint -sha1 -inform PEM -in okta-certificate.crt

Microsoft Entra ID (Azure AD) Configuration

Based on our existing Microsoft Entra documentation, here's how to configure Microsoft Entra ID:

Create Enterprise Application

1. Access Azure Portal:

   • Navigate to Azure Portal
   • Search for Microsoft Entra ID
   • Select Enterprise applications

2. Create New Application:

   • Click + New application
   • Click + Create your own application
   • Choose Integrate any other application you don't find in the gallery
   • Name: GitLab
   • Click Create

Configure Single Sign-On

1. Setup SAML:

   • In the application, go to Single sign-on
   • Select SAML
   • Click Edit in Basic SAML Configuration

2. Basic SAML Configuration:

Azure Field	GitLab.com Value	Self-Managed Value
Identifier (Entity ID)	https://gitlab.com/groups/YOUR_GROUP	https://gitlab.example.com
Reply URL (Assertion Consumer Service URL)	https://gitlab.com/groups/YOUR_GROUP/-/saml/acs	https://gitlab.example.com/users/auth/saml/callback
Sign on URL	https://gitlab.com/groups/YOUR_GROUP/-/saml/sso	https://gitlab.example.com/users/auth/saml
Logout URL	(optional)	https://gitlab.example.com/users/sign_out

3. User Attributes & Claims:
   • Edit the default claims:

Claim name	Source	Source attribute
Unique User Identifier (Name ID)	Attribute	user.objectid (GitLab.com) or user.userprincipalname (Self-managed)
email	Attribute	user.mail
first_name	Attribute	user.givenname
last_name	Attribute	user.surname

Get SAML Metadata

1. Download Certificate and URLs:

   • In SAML Signing Certificate section:
     • Download Certificate (Base64)
     • Copy App Federation Metadata Url

2. Get Login URL:

   • Copy Login URL from Set up GitLab section

Configure Users and Groups

1. Assign Users:

   • Go to Users and groups
   • Click + Add user/group
   • Select users or groups
   • Click Assign

2. Optional - Configure Groups Claim:

   • Go back to Single sign-on > User Attributes & Claims
   • Add new claim:
     • Name: Groups
     • Source: Attribute
     • Source attribute: user.groups

Google Workspace Configuration

Based on our existing Google Workspace documentation, here's how to configure Google Workspace:

Setup Custom SAML Application

1. Access Google Admin Console:

   • Navigate to admin.google.com
   • Sign in with super administrator account

2. Create SAML App:

   • Go to Apps > Web and mobile apps
   • Click Add app > Add custom SAML app

3. App Details:

   • App name: GitLab
   • Description: GitLab SSO Integration
   • App icon: Upload GitLab logo (optional)
   • Click Continue

Configure Google IdP Details

1. Download IdP Information:
   • SSO URL: Copy for GitLab configuration
   • Entity ID: Copy for GitLab configuration
   • Certificate: Download for GitLab configuration
   • Click Continue

Configure Service Provider Details

For GitLab.com:

Google Field	Value
ACS URL	https://gitlab.com/groups/YOUR_GROUP/-/saml/acs
Entity ID	https://gitlab.com/groups/YOUR_GROUP
Start URL	https://gitlab.com/groups/YOUR_GROUP/-/saml/sso
Name ID format	EMAIL
Name ID	Basic Information > Primary email

For Self-Managed:

Google Field	Value
ACS URL	https://gitlab.example.com/users/auth/saml/callback
Entity ID	https://gitlab.example.com
Start URL	https://gitlab.example.com/users/auth/saml
Name ID format	EMAIL
Name ID	Basic Information > Primary email

Configure Attribute Mapping

1. Add Attributes:

   • Primary email: email
   • First name: first_name
   • Last name: last_name

2. Optional Group Mapping:

   • Add custom attribute for groups if needed
   • Map organizational units to GitLab groups

Enable Application

1. User Access:

   • Choose ON for everyone or ON for some organizational units
   • Select appropriate organizational units if using selective access
   • Click Save

2. Test Configuration:

   • Use Test SAML login to verify setup

Part 4: Testing and Verification

Pre-Flight Checklist

Before testing, verify:

• Identity Provider configured with correct URLs and certificates
• GitLab SAML settings match IdP configuration
• User assignments completed in IdP
• Attribute mappings configured correctly
• Certificate fingerprints match between systems

GitLab.com Testing

1. Access SSO URL:

   • Navigate to your group's SSO URL: https://gitlab.com/groups/YOUR_GROUP/-/saml/sso
   • Should redirect to your identity provider

2. Complete Authentication:

   • Sign in with your IdP credentials
   • Should redirect back to GitLab
   • Verify account linking or creation

3. Verify Group Access:

   • Check group membership
   • Verify project access
   • Test various GitLab features

Self-Managed Testing

1. Access GitLab Sign-In:

   • Navigate to your GitLab instance
   • Click on your configured SAML provider button
   • Should redirect to your identity provider

2. Complete Authentication:

   • Sign in with your IdP credentials
   • Should redirect back to GitLab
   • Verify account creation or linking

3. Verify Instance Access:

   • Check user profile information
   • Verify group memberships (if configured)
   • Test Git operations

Common Test Scenarios

User Flows

1. New User Sign-In:

   • User who doesn't exist in GitLab
   • Should create new account automatically
   • Should have correct profile information

2. Existing User Linking:

   • User with existing GitLab account
   • Should link SAML identity to existing account
   • Should maintain existing permissions

3. Group Sync (if configured):

   • User's group membership changes in IdP
   • Should reflect in GitLab after next sign-in
   • Should update project access accordingly

Error Scenarios

1. User Not Assigned:

   • User not assigned to GitLab app in IdP
   • Should receive appropriate error message

2. Invalid Certificate:

   • Mismatched certificate fingerprint
   • Should receive SAML validation error

3. Missing Attributes:

   • Required attributes not sent by IdP
   • Should handle gracefully or show helpful error

Part 5: Troubleshooting

Common Issues and Solutions

SAML Response Issues

Problem: SAML authentication failed: Invalid SAML response

Solutions:

• Verify certificate fingerprint matches exactly
• Check clock synchronization between GitLab and IdP
• Validate SAML response XML format
• Ensure correct NameID format configuration

Problem: User email is missing, please update your identity provider

Solutions:

• Verify email attribute is configured in IdP
• Check attribute mapping in GitLab configuration
• Ensure user has email address in IdP profile

URL and Configuration Issues

Problem: The redirect URI included is not valid

Solutions:

• Verify exact URL match in IdP configuration
• Check for trailing slashes or case sensitivity
• Ensure HTTPS is used in production environments

Problem: Invalid audience restriction

Solutions:

• Verify Entity ID/Issuer matches between GitLab and IdP
• Check audience restriction settings in IdP
• Ensure correct GitLab URL format

User Access Issues

Problem: User not authorized to access this application

Solutions:

• Verify user is assigned to GitLab application in IdP
• Check group assignments if using group-based access
• Verify organizational unit access in Google Workspace

Problem: Account linking failed

Solutions:

• Ensure email addresses match between accounts
• Check auto-linking configuration
• Manually link accounts if automatic linking fails

Debug Tools and Techniques

SAML Response Debugging

1. Browser Developer Tools:

   • Monitor network requests during SAML flow
   • Check for redirects and response codes
   • Examine SAML response in POST requests

2. SAML Tracer (Browser Extension):

   • Install SAML Tracer for Firefox or Chrome
   • Capture SAML requests and responses
   • Analyze assertion content and attributes

3. GitLab Logs:

   # For Omnibus GitLab
   sudo gitlab-ctl tail
   
   # Specific log files
   sudo tail -f /var/log/gitlab/gitlab-rails/production.log
   sudo tail -f /var/log/gitlab/gitlab-rails/auth.log

Identity Provider Debugging

Okta:

• Check System Log in Okta Admin Console
• Look for authentication events and errors
• Verify application assignments and policies

Microsoft Entra ID:

• Use Sign-ins logs in Azure Portal
• Check Audit logs for configuration changes
• Review Enterprise applications activity

Google Workspace:

• Access Reports > Audit log in Admin Console
• Check SAML authentication events
• Review application-specific logs

Performance Optimization

Caching Configuration

# Omnibus GitLab - optimize SAML performance
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      # ... other configuration
      idp_cert: 'CERTIFICATE_CONTENT', # Use certificate content instead of fingerprint
      compress_request: true,
      compress_response: true
    }
  }
]

Session Management

# Configure session timeout
gitlab_rails['session_expire_delay'] = 10080 # 7 days in minutes

# Configure remember me functionality
gitlab_rails['remember_me_enabled'] = true

Security Hardening

Additional Security Measures

1. Certificate Validation:

   gitlab_rails['omniauth_providers'] = [
     {
       name: 'saml',
       args: {
         # ... other configuration
         security: {
           want_assertions_signed: true,
           want_name_id_encrypted: true,
           want_assertions_encrypted: true,
           signature_method: XMLSecurity::Document::RSA_SHA256,
           digest_method: XMLSecurity::Document::SHA256
         }
       }
     }
   ]

2. IP Restrictions (IdP Level):

   • Configure IP allowlists in your identity provider
   • Restrict access to specific networks or locations

3. Multi-Factor Authentication:

   • Enable MFA in your identity provider
   • Configure conditional access policies

Monitoring and Alerting

1. Failed Authentication Monitoring:

   # Configure failed login tracking
   gitlab_rails['rack_attack_git_basic_auth'] = {
     'enabled' => true,
     'maxretry' => 10,
     'findtime' => 60,
     'bantime' => 3600
   }

2. Log Analysis:

   • Set up log aggregation (ELK stack, Splunk, etc.)
   • Create alerts for authentication failures
   • Monitor for suspicious patterns

Part 6: Best Practices and Recommendations

Security Best Practices

Identity Provider Configuration

1. Use Strong Certificates:

   • Use SHA-256 or higher for signing algorithms
   • Rotate certificates regularly (annually or bi-annually)
   • Store certificates securely

2. Attribute Mapping:

   • Map only necessary attributes to GitLab
   • Use persistent NameID format for stable user identification
   • Validate attribute sources and formats

3. Access Control:

   • Implement least privilege access
   • Use group-based access management
   • Regular access reviews and cleanup

GitLab Configuration

1. Auto-User Creation:

   # Recommended settings for new deployments
   gitlab_rails['omniauth_block_auto_created_users'] = false
   gitlab_rails['omniauth_auto_link_saml_user'] = true
   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']

2. User Account Management:

   • Enable automatic account linking based on email
   • Consider blocking auto-created users for security review
   • Implement user provisioning workflows

Operational Best Practices

Deployment Strategy

1. Phased Rollout:

   • Start with pilot group of users
   • Test all critical workflows
   • Gradually expand to all users
   • Maintain fallback authentication method

2. Communication Plan:

   • Notify users of SSO implementation
   • Provide clear instructions for account linking
   • Document troubleshooting steps for users

Maintenance and Monitoring

1. Regular Reviews:

   • Quarterly review of user access
   • Annual review of configuration
   • Certificate expiration monitoring
   • Performance monitoring

2. Backup Plans:

   • Maintain admin access outside of SSO
   • Document emergency access procedures
   • Test disaster recovery scenarios

Multi-Environment Setup

Development and Staging

# Development environment configuration
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      assertion_consumer_service_url: 'https://gitlab-dev.example.com/users/auth/saml/callback',
      idp_sso_target_url: 'https://idp-dev.example.com/sso/saml',
      # ... other dev-specific configuration
    },
    label: 'Company SSO (Dev)'
  }
]

Production Deployment

1. Pre-Production Validation:

   • Test identical configuration in staging
   • Validate certificate chain
   • Verify all user flows
   • Performance testing under load

2. Production Deployment:

   • Schedule maintenance window
   • Deploy during low-usage periods
   • Monitor authentication success rates
   • Have rollback plan ready

Part 7: Advanced Configuration

Group Synchronization

Automatic Group Assignment

# GitLab Self-Managed group sync configuration
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      # ... other configuration
      groups_attribute: 'Groups',
      external_groups: ['Contractors', 'External'],
      required_groups: ['GitLab-Users'],
      admin_groups: ['GitLab-Admins']
    }
  }
]

Custom Group Mapping

# Advanced group mapping
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      # ... other configuration
      attribute_statements: {
        groups: ['Groups'],
        # Custom mappings
        team: ['Department'],
        role: ['JobTitle']
      }
    }
  }
]

Custom User Provisioning

API-Based Provisioning

# Hook for custom user provisioning
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    args: {
      # ... other configuration
      provisioning_enabled: true,
      provisioning_url: 'https://provisioning-api.example.com/webhook'
    }
  }
]

Integration with LDAP

Hybrid LDAP/SAML Setup

# Configure both LDAP and SAML
gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = {
  'main' => {
    'label' => 'LDAP',
    'host' => 'ldap.example.com',
    'port' => 389,
    'uid' => 'sAMAccountName',
    'base' => 'dc=example,dc=com'
  }
}

gitlab_rails['omniauth_auto_link_ldap_user'] = true

Conclusion

This comprehensive guide covers the complete setup and configuration of GitLab SSO for both GitLab.com and self-managed instances. Key takeaways:

1. Choose the Right Approach: GitLab.com groups for SaaS, self-managed for on-premises control
2. Plan Your Identity Provider: Consider your existing infrastructure and security requirements
3. Test Thoroughly: Validate all user flows before production deployment
4. Implement Security Best Practices: Use strong certificates, proper access controls, and monitoring
5. Plan for Maintenance: Regular reviews, certificate rotation, and user access audits

Quick Reference

GitLab.com URLs

• Group SSO Setup: https://gitlab.com/groups/YOUR_GROUP/-/settings/saml_sso
• SSO Sign-In: https://gitlab.com/groups/YOUR_GROUP/-/saml/sso
• Callback URL: https://gitlab.com/groups/YOUR_GROUP/-/saml/acs

Self-Managed URLs

• SAML Sign-In: https://gitlab.example.com/users/auth/saml
• Callback URL: https://gitlab.example.com/users/auth/saml/callback
• Metadata URL: https://gitlab.example.com/users/auth/saml/metadata

Support Resources

• GitLab SAML SSO Documentation
• GitLab Self-Managed SAML
• SAML Troubleshooting Guide
• GitLab Support

For additional help with specific identity provider configurations, refer to the dedicated documentation sections above or contact your identity provider's support team.