How to set up GitLab SAML SSO with Google Workspace

Single sign-on (SSO) simplifies user authentication and improves security by allowing employees to access multiple applications with one set of credentials. For organizations using both GitLab and Google Workspace, integrating SAML-based SSO streamlines access management and ensures your teams can collaborate seamlessly.In this guide, we'll walk through configuring SAML authentication between Google Workspace and GitLab.com, including automatic group synchronization that maps Google Workspace groups to GitLab roles. By the end, your users will be able to sign in to GitLab using their Google credentials, and their permissions will automatically reflect their Google group memberships.Note: This guide focuses on GitLab.com (SaaS). If you're using GitLab Self-Managed, the setup process differs slightly. Refer to the official GitLab SAML documentation for self-managed instances for detailed instructions.What you'll needBefore getting started, make sure you have:Google Workspace with Super Admin accessGitLab.com with a Premium or Ultimate tier subscriptionOwner role on a GitLab top-level groupUsers already existing in Google Workspace (they'll be created in GitLab automatically on first login)Understanding the architectureWhen you configure SAML SSO with group synchronization, here's what happens:Authentication flow: Users navigate to GitLab's SSO URL and are redirected to Google Workspace to authenticate.SAML assertion: After successful authentication, Google sends a SAML response containing user details and group memberships.Automatic provisioning: GitLab creates the user account (if needed) and assigns them to groups based on their Google group memberships.Permission sync: Each time users sign in, GitLab updates their group memberships and roles to match their current Google groups.This setup provides several benefits:Centralized access control: You can manage user access through Google Workspace groups.Automatic provisioning: New users gain GitLab access on their first login.Dynamic permissions: User roles update automatically based on group membership changes.Enhanced security: You can leverage Google's authentication security features.Reduced administrative overhead: There is no need to manually manage GitLab group memberships.Part 1: Get your GitLab SAML configuration valuesFirst, you'll need to gather some information from GitLab that you'll use when creating the SAML application in Google Workspace. Here are the steps to take:Step 1: Navigate to your GitLab group SAML settingsSign in to GitLab.com.Navigate to your top-level group (Note: SAML SSO can only be configured at the top-level group, not in subgroups).In the left sidebar, select Settings SAML SSO.Step 2: Copy the required URLsOn the SAML SSO settings page, you'll see three important URLs. Copy and save these somewhere accessible — you'll need them shortly:Assertion consumer service URL: This is where Google will send SAML responses.Format: https://gitlab.com/groups/your-group/-/saml/callbackIdentifier: Also called the Entity ID, this uniquely identifies your GitLab group.Format: https://gitlab.com/groups/your-groupGitLab SSO URL: This is the URL your users will use to sign in.Format: https://gitlab.com/groups/your-group/-/saml/sso

GitLab SAML single sign-on settingsNow you'll create a custom SAML application in Google Workspace that connects to your GitLab group.Step 3: Access the Google Admin ConsoleOpen a new browser tab and sign in to the Google Admin Console with a Super Administrator account.Click the Menu icon (☰) in the top-left.Navigate to Apps Web and mobile apps.Click Add App Add custom SAML app.

Google custom SAML appStep 4: Configure the application nameIn the App name field, enter GitLab (or your preferred name).Optionally upload a GitLab logo as the app icon for easy recognition.Click Continue.Step 5: Download Google identity provider detailsOn the Google Identity Provider details page, you'll need to capture two pieces of information:SSO URL: Copy this URL. It tells GitLab where to send authentication requests.Example format: https://accounts.google.com/o/saml2/idp?idpid=C1234abcdCertificate: Click the Download button to save the certificate file.The file will be named something like: GoogleIDPCertificate-gitlab.pemSave this file somewhere you can easily find it. You'll need it in the next sectionClick Continue.Step 6: Configure service provider detailsThis is where you'll use the GitLab URLs you copied in Step 2. Enter the following:FieldValueDescriptionACS URLYour GitLab Assertion consumer service URLWhere Google sends SAML responsesEntity IDYour GitLab IdentifierUnique identifier for your GitLab groupStart URLLeave blankNot required for this setupName ID formatSelect EMAILThe format for the user identifierName IDSelect Basic Information Primary EmailThe user's primary email will be used as their identifierSigned responseLeave uncheckedGitLab doesn't require signed responses by default

GitLab SAML app detailsClick Continue when complete.Step 7: Configure attribute mappingAttribute mapping tells Google which user information to send to GitLab. You'll configure both basic user attributes and group membership.Basic attributesAdd these three attribute mappings by clicking Add mapping for each:Google Directory attributeApp attributePrimary emailemailFirst namefirst_nameLast namelast_nameGroup membership configurationThis is the critical configuration that enables automatic group synchronization:Scroll down to the "Group membership (optional)" section.Under "Google groups", click "Search for a group".Search for and select each Google Workspace group you want to synchronize with GitLab.You can select up to 75 groupsExamples: Engineering, DevOps, Platform-Team, Security-TeamUnder "App attribute", enter exactly: groups.Click Finish.

GitLab SAML app attribute mappingCritical: The app attribute name MUST be exactly groups (lowercase). This is what GitLab expects to receive in the SAML response. Any other value or capitalization will prevent group synchronization from working.Step 8: Enable the application for usersYour SAML app is created but not yet enabled. To make it available to users:In the Google Admin Console, find your GitLab app in the Web and mobile apps list.Click on the app to open its details.In the left sidebar, click User access.Select one of the following:ON for everyone - Enables the app for all users in your organizationON for some organizational units - Select specific organizational unitsClick Save.Note: Changes can take up to 24 hours to propagate, but typically take effect within a few minutes.Part 3: Convert the certificate to SHA-1 fingerprint formatGitLab requires a SHA-1 certificate fingerprint, but Google's certificate download doesn't include this format directly. You'll need to convert it.Step 9: Convert your certificateYou have two options for converting the certificate to the required format.Option 1: Online conversion toolThis is a viable method if you're comfortable using a third-party tool:Locate the certificate file you downloaded in Step 5:Check your Downloads folderThe file name will be something like: GoogleIDPCertificate-gitlab.pemOpen the file in a text editor:Mac: Right-click Open With TextEditWindows: Right-click Open With NotepadLinux: Use your preferred text editorCopy ALL contents of the file, including the header and footer:-----BEGIN CERTIFICATE-----
MIIDdDCCAlygAwIBAgIGAXqD...
(multiple lines of encoded text)
...kE7RnF6yQ==
-----END CERTIFICATE-----
Navigate to: A SHA-1 fingerprint conversion tool. This one is a good example.Paste the certificate content into the text box.Select "SHA-1" from the algorithm dropdown (not SHA-256!).Click "Calculate Fingerprint".Copy the resulting fingerprint - it will be in the format: XX:XX:XX:XX:XX:....Option 2: Command-line conversionIf you prefer using the command line:For Mac, Linux, or Windows with WSL:cd ~/Downloads
openssl x509 -noout -fingerprint -sha1 -inform pem -in "GoogleIDPCertificate-gitlab.pem"
The output will show:SHA1 Fingerprint=XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX
Copy everything after SHA1 Fingerprint=.Part 4: Complete your GitLab SAML configurationNow that you have the Google SSO URL and certificate fingerprint, you can complete the GitLab side of the configuration.Step 10: Enter Google identity provider detailsReturn to your GitLab browser tab (Settings SAML SSO) and do the following:Identity provider SSO URL:Paste the SSO URL you copied from Google in Step 5Certificate fingerprint:Paste the SHA-1 fingerprint you generated in Step 9Verify the format is correct: 59 characters with colons (XX:XX:XX:...)Enable SAML authentication for this group:Check this box to activate SAML SSO

GitLab SAML Configuration with Google SAML valuesStep 11: Configure security settings (recommended)For enhanced security, consider enabling these additional options:"Enforce SAML authentication for web activity for this group"Requires users to authenticate via SAML to access the GitLab web interface"Enforce SAML authentication for Git and Dependency Proxy activity for this group"Requires SAML authentication for Git operations and dependency proxy accessClick Save changes to apply your configuration.Step 12: Test your SAML configurationBefore proceeding with group synchronization, verify that basic SAML authentication works:Open an incognito or private browsing window.Navigate to your GitLab SSO URL.Format: https://gitlab.com/groups/your-group/-/saml/ssoYou should be redirected to the Google sign-in page.Sign in with a Google Workspace account that has access to the GitLab app.After successful authentication, you should be redirected back to GitLab.If the test succeeds, you can proceed to configure group synchronization.If the test fails, check the following:Verify the certificate fingerprint is SHA-1 format (not SHA-256).Confirm the SSO URL is correct.Ensure the user has access to the GitLab SAML app in Google Admin Console.Check that the ACS URL and Entity ID match exactly.Part 5: Set up SAML group synchronizationNow it's time to map your Google Workspace groups to GitLab roles so that permissions are automatically managed based on group membership.Step 13: Configure default membership roleAs a security best practice, set a minimal default role for users who log in but don't belong to any mapped groups:In your GitLab group, navigate to Settings General.Expand the Permissions and group features section.Under Default membership role, select Minimal Access or Guest.Click Save changes.

GitLab SAML Default membership settingStep 14: Create SAML group linksSAML Group Links are the mappings between Google Workspace groups and GitLab roles. Here's how to create them:In your GitLab group, navigate to Settings SAML Group Links.Click "Add new SAML Group Link".For each Google Workspace group you want to sync:SAML Group Name:Enter the exact name of your Google Workspace groupThis is case-sensitive and must match perfectlyExample: Engineering (not engineering)To find the exact name: Google Admin Console Directory GroupsAccess Level: Select the appropriate GitLab role:Minimal Access - Can see that the group existsGuest - Can view issues and leave commentsReporter - Can pull code, view issues, and create new issuesDeveloper - Can push code, create merge requests, and manage issuesMaintainer - Can manage project settings and membersOwner - Full administrative control over the groupClick Save.Repeat this process for each Google Workspace group you want to map.Note: SAML group sync rules are enforced every time a user signs in. If a user's Google group membership matches a sync rule, their GitLab role will be automatically set to the configured access level, even if you've manually changed it to something different. For example, if you set up a sync rule that grants "Maintainer" access and then manually promote a user to "Owner," they'll be automatically downgraded back to "Maintainer" on their next SAML sign-in.Best practices: To maintain custom access levels for specific users, do one of the following:Use SAML group sync only on your top-level group and manually manage permissions in subgroupsCreate separate Google groups for users who need elevated permissionsAvoid setting up sync rules that would conflict with manual role assignments

GitLab SAML Group Links setupHere's a practical example of how you might structure your group mappings:Google Workspace GroupGitLab RolePurposeGitLab-AdminsOwnerFull administrative accessEngineering-TeamMaintainerCan manage projects and settingsDeveloper-TeamDeveloperCan write and push codeQA-TeamDeveloperCan test and manage issuesContractorsReporterRead-only access to codeAll-EmployeesMinimal AccessBasic visibilityStep 15: Verify your group linksAfter creating all your group links:Review the complete list of SAML Group Links in Settings SAML Group Links.Verify each SAML Group Name exactly matches the corresponding Google Workspace group.Verify each Access Level is appropriate for the intended purpose.Check for any typos or extra spaces.Part 6: Test the complete configurationNow it's time to test the entire setup including group synchronization.Step 16: Test with a real userChoose a test user who meets these criteria:Has a Google Workspace accountIs a member of at least one Google Workspace group you configuredHas the GitLab SAML app enabled in Google Admin ConsoleIdeally is not you (to ensure a realistic test)To perform the test:Open an incognito or private browsing windowNavigate to your GitLab SSO URL:https://gitlab.com/groups/your-group/-/saml/ssoSign in with the test user's Google Workspace credentialsThe user should be:Authenticated successfullyRedirected to GitLabAutomatically added to the GitLab groupAssigned the appropriate role based on their Google group membershipStep 17: Verify group membership and role assignmentUsing your GitLab administrator account:Navigate to your group in GitLab.Select Manage Members from the left sidebar.Find the test user in the members list.Verify the following:
User appears in the members listUser has the correct Max role based on their Google group(s)Source column shows a SAML indicator

Verified SAML user addedPart 7: Configure subgroup access (optional)For larger organizations, you may want to provide more granular access control using GitLab subgroups. SAML Group Links can be configured at any level of your group hierarchy, allowing you to map different Google Workspace groups to specific teams or projects.Understanding GitLab's subgroup structureGitLab supports nested group hierarchies that can mirror your organizational structure:acme-corp/ ← Top-level group (SAML configured here)
├── engineering/ ← Subgroup
│ ├── backend/ ← Nested subgroup
│ └── frontend/ ← Nested subgroup
├── marketing/ ← Subgroup
└── operations/ ← Subgroup
Creating subgroupsIf you need to create additional subgroups:Navigate to your parent group (e.g., acme-corp).Click the New subgroup button.Configure the subgroup:Subgroup name: Display name (e.g., Engineering)Subgroup URL: URL slug (e.g., engineering)Visibility level: Choose Private, Internal, or PublicClick Create subgroup.Repeat for other subgroups as needed.Configuring SAML group links for subgroupsHere are the steps to configure SAML group links for subgroups.Add new Google groups to the SAML app (if needed)If you're introducing new Google Workspace groups for subgroup access:Go to Google Admin Console Apps Web and mobile apps GitLab.Click SAML attribute mapping.Scroll to "Group membership (optional)".Add your new groups (e.g., Backend-Team, Frontend-Team).Verify the "App attribute" is still groups.Click Save.Map Google groups to subgroupsNavigate to the specific subgroup in GitLabExample: acme-corp/engineering/backendGo to Settings SAML Group Links.Click "Add new SAML Group Link".Configure the mapping:SAML Group Name: Backend-Team (exact Google Workspace group name)Access Level: Developer (or your desired role)Click Save.
Repeat this process for all subgroups and their corresponding Google groups.Multi-level access exampleHere's how permissions might work across different levels:Top-level group: acme-corpSAML Group Links:"Company-Admins" → Owner"All-Employees" → Minimal AccessSubgroup: acme-corp/engineeringSAML Group Links:"Engineering-Leads" → Owner"Engineering-Team" → MaintainerNested subgroup: acme-corp/engineering/backendSAML Group Links:"Backend-Leads" → Maintainer"Backend-Team" → DeveloperHow permissions inherit and combineUnderstanding permission behavior is important:Role calculation: At each level, users receive the highest role from all their Google groups.Inheritance: Higher permissions at parent levels flow down to child subgroups.Independence: Each level calculates permissions based on its own group links plus inherited permissions.No limitation: Lower permissions at parent levels do NOT restrict higher permissions at child levels.Example scenarios:User A (member of Backend-Team only):acme-corp: Minimal Access (from "All-Employees" default)acme-corp/engineering: Minimal Access (inherited from parent)acme-corp/engineering/backend: Developer (from "Backend-Team" mapping)User B (member of Engineering-Leads and Backend-Team):acme-corp: Minimal Access (from "All-Employees" default)acme-corp/engineering: Owner (from "Engineering-Leads" mapping)acme-corp/engineering/backend: Owner (inherited from parent, which is higher than Developer)How the synchronization worksUnderstanding the mechanics of SAML group synchronization helps you manage the system effectively.Synchronization timingWhen sync occurs: Group memberships update every time a user signs in via SAML.Frequency: Changes are not continuous — they only happen at login.Direction: Synchronization is one-way from Google Workspace to GitLab.First login: User account is created automatically and groups are assigned.Subsequent logins: Existing group memberships are updated to match current Google groups.Role priority and combinationWhen a user belongs to multiple Google Workspace groups:GitLab evaluates all the user's groups at each level of the hierarchy.The user receives the highest role from any of their groups.This calculation happens independently at each level (top-level group, subgroups, etc.).Example:User in "Developers" (Developer role) + "Tech-Leads" (Maintainer role) → Gets MaintainerAutomatic role changesThe system automatically handles membership changes:User added to a Google group: Role upgraded on next login.User removed from a Google group: Role recalculated based on remaining groups on next login.User removed from all mapped groups: Reverts to default membership role on next login.User added to additional groups: Gets highest role from all groups on next login.Propagation timingBe aware of these timing considerations:Google Workspace changes: Can take up to 24 hours to propagate, though usually take only a few minutes.GitLab sync: Happens immediately when the user logs in after Google changes are live.Testing: Have users log out and log back in to test permission changes.Understanding user lifecycle and edge casesWhat happens when you remove a user from GitLab?Removing permissions only: If you remove a user from GitLab projects but leave their account active and they're still in the authorized Google groups:They keep their same account (same user ID and username)When they log in via SAML, their group memberships are automatically restoredThey regain permissions based on their current Google group membershipsBlocking the account:Account exists but is lockedUser cannot log in even if in Google groupsCan be unblocked later, preserving all historyDeleting the account:Account is permanently removedIf user logs in again (while still in Google groups), GitLab creates a completely new accountNew account has different user ID with no connection to the old oneProper offboarding processTo permanently revoke access, follow this order:Remove from Google Workspace groups - Prevents authenticationBlock in GitLab - Prevents account recreation and preserves audit trailsDelete account (optional) - Only if you're certain they won't returnCritical: Removing a user only from GitLab without removing them from Google groups means they can simply log back in and regain access.Google group membership propagationAccording to Google's documentation, group membership changes can take up to 24 hours to propagate, though typically occur within minutes.Account recreation scenariosScenarioUser still in Google groups?What happens on loginPermissions removedYesSame account, group memberships restoredAccount blockedYesLogin failsAccount deletedYesNew account created with new user IDRemoved from Google groupsNoLogin fails at GoogleTroubleshooting common issuesEven with careful configuration, you might encounter issues. Here are solutions to the most common problems.Users not being added to groupsSymptom: User successfully logs in via SAML but doesn't appear in any GitLab groups, or appears with only the default role.Possible causes and solutions:Group names don't match exactlyCheck spelling and capitalization in both Google Workspace and GitLabLook for extra spaces before or after group namesVerify the exact name in Google Admin Console Directory GroupsUser not actually in the Google groupVerify membership: Google Admin Console Directory Groups Group MembersRemember that nested group membership might not be includedGroups not configured in SAML appVerify the groups are selected in Google SAML attribute mappingConfirm "App attribute" is set to groups (lowercase)Use "Test SAML Login" to inspect the SAML responseTiming or cache issueWait 24 hours for Google changes to fully propagateHave the user log out of GitLab and Google completelyClear browser cache and try againUser must log in via the SAML SSO URL, not regular GitLab loginUser has incorrect roleSymptom: User has access but with the wrong permission level.Possible causes and solutions:User belongs to multiple groupsRemember: Users get the highest role from all their groupsCheck all Google groups the user belongs toReview all SAML Group Link configurations at all levelsSAML Group Link misconfiguredVerify the Access Level setting in Settings SAML Group LinksCheck for duplicate group mappings that might conflictUser hasn't logged in since changesRoles only update when users log in via SAMLHave the user log out completely and log back in via the SSO URLInherited permissions from parent groupsCheck SAML Group Links in parent groupsRemember that higher roles at parent levels flow down to childrenSAML authentication fails completelySymptom: Users cannot log in at all, or receive error messages during authentication.Possible causes and solutions:Incorrect certificate fingerprintVerify you used SHA-1 format, not SHA-256Check the fingerprint has the correct format with colonsRegenerate using the online tool or OpenSSL commandWrong SSO URLDouble-check the SSO URL copied from GoogleEnsure there are no extra spaces or charactersACS URL or Entity ID mismatchVerify the ACS URL in Google Admin Console matches GitLab exactlyConfirm the Entity ID matches between both systemsUser doesn't have app accessCheck User Access settings in Google Admin ConsoleVerify the user's organizational unit has the app enabledConfirm the app is "ON" for the appropriate usersCertificate expiredCheck certificate validity datesDownload a fresh certificate if neededGroups attribute missing from SAML responseSymptom: Users can log in but group synchronization doesn't work at all.Possible causes and solutions:Groups not selected in Google configurationReturn to Google Admin Apps GitLab Attribute mappingVerify groups are selected under "Group membership"Confirm "App attribute" is exactly groups (lowercase)User not in any configured groupsOnly groups the user belongs to are sent in the SAML responseAdd the user to at least one selected group to testConfiguration hasn't propagatedWait up to 24 hours for changes to take effectTry logging out of Google Admin Console and back inTypo in app attribute nameThe attribute name must be exactly groups (lowercase)Even a capital letter or extra space will break functionalityBest practices for managing SAML group syncFollow these recommendations to maintain a secure and efficient setup.Security best practicesMaintain emergency accessKeep at least one Owner account that uses password authentication (not SAML)This provides emergency access if SAML configuration breaksStore these credentials securelyUse least privilege principleSet default membership to Minimal AccessOnly grant higher permissions through explicit group mappingsRegularly review and audit group membershipsEnable enforcement optionsTurn on "Enforce SAML authentication" optionsThis prevents users from bypassing SSOExceptions should be rare and well-documentedRegular security auditsQuarterly review of Google Workspace group membershipsAnnual review of SAML Group Link mappingsMonitor GitLab audit logs for unusual access patternsSummary and next stepsCongratulations! You've successfully configured SAML SSO and automatic group synchronization between Google Workspace and GitLab. Your setup now provides:Seamless authentication - Users sign in with their familiar Google Workspace credentials.Automatic provisioning - User accounts are created on first login without manual intervention.Dynamic permissions - Group memberships and roles update automatically based on Google Workspace groups.Centralized access control - Manage all access through your existing Google Workspace groups.Enhanced security - Leverage Google's authentication infrastructure and enforce consistent policies.Reduced administrative overhead - Eliminate manual user and permission management in GitLab.What happens nowWhen users access GitLab:They navigate to your GitLab SSO URL.Authenticate using their Google Workspace credentials.Get automatically added to appropriate GitLab groups.Receive permissions based on their Google group memberships.Their permissions update every time they sign in.Additional resourcesGitLab SAML SSO DocumentationGitLab SAML Group Sync DocumentationGoogle Workspace SAML App SetupSAML Certificate Fingerprint ToolRelated articleHow-to: GitLab Single Sign-on with SAML, SCIM, and Azure's Entra ID

Source: https://about.gitlab.com/blog/how-to-set-up-gitlab-saml-sso-with-google-workspace/