GitLab SAML SSO with Google Workspace

How GitLab SAML SSO with Google Workspace works

Your team wants people to sign in to self-managed GitLab with the Google Workspace accounts they already use, and the question is how much of that setup Google will do for you. GitLab Self-Managed supports SAML, and the Google Workspace integration uses a custom SAML app that you create in the Google Admin console and point at your GitLab instance. GitLab documents SAML as a protocol, not a Google-specific connector, so the same settings you would use for another identity provider apply here. This section explains how the pieces fit together before you touch either side.

The SAML app carries four things across the trust boundary: the assertion consumer service URL that GitLab expects, the entity ID, the certificate fingerprint that GitLab uses to verify Google's signing certificate, and the name ID format that identifies each user. The name ID format and the attribute GitLab matches on must agree, or sign-in will fail or create duplicate accounts. Confirm the exact field names, the fingerprint algorithm and the supported name ID values against the current GitLab authentication documentation for your release, and test with one pilot group before you expand the app to the whole organization.

Be clear about the limit of SAML sign-in on its own. A working SAML app lets users who already exist in GitLab sign in, and it can create accounts on first sign-in, but it does not remove access when someone leaves or move group membership when roles change. Google Workspace cannot push user lifecycle changes to GitLab without SCIM provisioning, which is a separate configuration covered in its own section. Plan for that gap now, decide who owns deprovisioning, and ask your partner or internal team to confirm how deactivated Google accounts will be handled before go-live.

What you need before configuring Google Workspace SAML

Most failed SAML attempts trace back to something confirmed too late: the instance URL, the Google admin rights, or the edition. The cards below cover what to check on the GitLab side and the Google side before anyone opens the Admin console. Work through them in order, since the external URL and TLS settings shape every value you paste into Google later.

A self-managed GitLab instance and URL

Confirm you have a running self-managed GitLab instance and know its exact external URL, because Google Workspace will send SAML responses to a host name derived from it. Check that the host name you plan to use is the one users type into their browsers, and that it does not change during the rollout. A mismatch between the external URL in gitlab.rb and the ACS URL registered in Google is the most common cause of an immediate sign-in failure.

Google Admin console rights

Someone with super administrator or an equivalent role must be able to create a custom SAML app in the Google Admin console and set its SSO settings. Confirm this person can also assign the app to organizational units or groups, since access is controlled there. If the team lacks this role, agree who will act as the Google administrator before the change window opens.

Edition and features in use

Confirm which GitLab edition and tier your instance runs, and whether the features you need are in that tier. SAML sign-in is available in self-managed GitLab, but group-based provisioning and some role mapping depend on the tier you license. Compare the requirements you have against the GitLab pricing page and the authentication documentation before you commit to a design.

GitLab version and upgrade position

Record the exact GitLab version and check the documentation for that version, since SAML settings and the names of options in gitlab.rb can change between releases. Confirm whether the instance is on a supported release and whether an upgrade stop is pending. Schedule SAML changes outside an upgrade window so a failure can be traced to one cause.

TLS on the external URL

Confirm the GitLab external URL is served over TLS with a certificate that Google-hosted users trust, and that the certificate chain is complete. Google sends the SAML response through the user's browser, so an invalid certificate blocks sign-in before GitLab sees the assertion. Check the certificate expiry date and who renews it.

Access to gitlab.rb

Confirm who can edit gitlab.rb on the server, run gitlab-ctl reconfigure and restart services. SAML settings such as the issuer, the IdP certificate fingerprint and the name ID format live in this file, so changes need a reviewed change record and a rollback copy. Also confirm you can read the logs if sign-in fails after the change.

Configuring the custom SAML app in Google Workspace and GitLab

This sequence connects a self-managed GitLab instance to Google Workspace for single sign-on. It produces a custom SAML app in Google, a matching SAML block in gitlab.rb and a tested pilot sign-in before the app is turned on for more users. Each step closes with a check so the team can confirm the fingerprint, identifiers and account match before moving on.

Create the custom SAML app in Google
A Google Workspace super administrator opens the Admin console and adds a custom SAML app from the web and mobile apps section. Give the app a name that users will recognize on the Google app launcher. Google then displays the SSO URL, entity ID and a certificate download on its setup page, so leave that page open for the next step. The step is complete when the app appears in the app list and the setup page shows both an SSO URL and an entity ID.
Record the identity provider values and certificate
Copy the SSO URL and entity ID from the Google setup page into your change record, then download the certificate. Compute the fingerprint locally with openssl x509 -in <certificate-file> -noout -fingerprint -sha256 and compare it with the fingerprint Google displays. Confirm in GitLab's SAML documentation which fingerprint algorithm the idp_cert_fingerprint setting expects, because the value must match that algorithm exactly. The step is complete when the locally computed fingerprint matches Google's value and the algorithm is recorded.
Enter GitLab service provider details
In the Google app settings, set the ACS URL to the SAML callback address on your GitLab external hostname. Confirm the exact callback path in GitLab's authentication documentation, since it must match your hostname precisely. Set the entity ID to the issuer string you plan to use in gitlab.rb, and choose the name ID format, either persistent or email, after checking GitLab's guidance on that option. Changing the format after users have signed in can leave existing accounts unmatched, so decide it before the pilot. The step is complete when Google saves the settings without errors and the entity ID is recorded for reuse.
Map user attributes to GitLab fields
Add attribute mappings in the Google app so the assertion carries the fields GitLab reads, typically the primary email address and the first and last name. Use the name ID value that matches the format chosen in the previous step. Confirm the attribute names against GitLab's SAML settings, because a mismatch produces sign-in errors or accounts with blank names. The step is complete when a sample user's attributes in Google match the names GitLab expects, and the mapping is saved in the app.
Configure the SAML block in gitlab.rb
On the GitLab server, edit /etc/gitlab/gitlab.rb and add the SAML provider under gitlab_rails['omniauth_providers']. Set the identity provider SSO URL, the issuer, the name ID format, the assertion consumer service URL and the idp_cert_fingerprint value from the second step. Keep the file under change control and back it up first. The step is complete when the fingerprint in the file matches the value you verified earlier and the issuer matches the entity ID entered in Google.
Reconfigure and restart GitLab
Run sudo gitlab-ctl reconfigure to apply the change, then run sudo gitlab-ctl restart so every service picks up the new settings. Review the command output for errors that refer to the SAML provider or the configuration file. The step is complete when reconfigure finishes without errors, the services restart cleanly, and the GitLab sign-in page shows the Google sign-in option.
Test sign-in with a pilot group
In Google, turn on the SAML app only for a pilot organizational unit or group. Sign in as a pilot user in a private browser window and confirm the user lands on the intended GitLab account, with the expected email and name, and that no duplicate account appears. Keep a local administrator sign-in available in case the federation fails. Google SAML handles sign-in only, so account creation and deprovisioning still need a separate plan such as SCIM. The step is complete when each pilot user reaches the correct account and the results are recorded before the app is enabled for wider groups.

Mapping Google Workspace attributes to GitLab identities

This table compares each identity attribute Google Workspace can send in the SAML assertion with the GitLab field it feeds and the decision it forces. Read it before you configure the custom SAML app, because the NameID choice is hard to change once users have signed in. The main takeaway is that the NameID should be a value that never changes for a person, while email and admin roles are separate decisions to make on purpose.

Attribute	What GitLab uses it for	Decision and risk
NameID value	Links the SAML identity to a GitLab account through the extern_uid for that provider	Pick a value that stays fixed for each person. Changing it later can leave existing accounts unmatched and create duplicates.
NameID format	Tells GitLab how to read the NameID value when it matches the identity	Confirm the format your Google Workspace app sends and set the matching format in the GitLab SAML settings. A mismatch usually shows as sign-in failures, not partial matches.
Email	Used for account matching, notifications and, depending on settings, linking to an existing account	Email can change through renames or aliases. Decide whether a changed email should block sign-in or be treated as the same person.
Username	Sets the GitLab username for newly created accounts	Usernames are visible across the instance and in commit history. Confirm your naming convention before the first user signs in.
Name	Sets the display name on new accounts	Low risk, but it may come from a Google profile field that users can edit. Decide who owns the value.
Group attributes for admin, auditor and external roles	Controls administrator, auditor and external user status when the settings are in gitlab.rb	Treat this as a separate decision from identity matching. The group attribute mapping and the required gitlab.rb settings are covered in the sibling topic on SAML admin, auditor and external groups.

What Google Workspace SAML cannot provision without SCIM

SAML handles sign-in and nothing else. When a user authenticates through the custom SAML app for GitLab, Google Workspace asserts who they are, and GitLab decides whether to let them in. The SAML exchange does not create, update, suspend or delete GitLab accounts, and it does not keep GitLab group membership in step with your directory. Account creation at first sign-in happens only where the instance allows it, which means a user can exist in GitLab long after they have left the organization, and nothing in the SAML flow will remove them. Plan offboarding, group membership and deprovisioning as a separate workstream from the SAML configuration itself.

SCIM is the mechanism GitLab Self-Managed supports for that lifecycle work, and it is the piece most teams underestimate when they hand over a Google Workspace SSO project. Before you commit to a design, confirm with your Google Workspace edition and your GitLab tier whether SCIM provisioning from Google is available for your setup, because this depends on both sides and should be checked against current vendor documentation rather than assumed. Also confirm how GitLab handles users who are deactivated in the identity provider, since that behavior determines whether an offboarded person keeps an active account. The separate SCIM topic covers the provisioning options, their setup steps and their limits in detail.

Until SCIM or another provisioning method is in place, make the gap explicit in your rollout. Ask who reviews the list of GitLab users against the active Google Workspace directory, how often that review runs, and who is responsible for removing access when a contractor's engagement ends. Decide whether sign-in should be restricted to a defined group so that only intended users can authenticate, and confirm how group-based access will be maintained as people change roles. Writing these answers down before go-live gives your security and identity teams a clear control to audit.

Securing sign-in with Google Workspace SAML

Once GitLab trusts Google Workspace for sign-in, the security of the instance depends on who can reach that sign-in path, how the signing certificate is maintained, and whether a recovery route survives an identity outage. The cards below cover those decisions and the checks to run against your own control framework.

Scope sign-in to the right Google group

Google Workspace can assign the GitLab SAML app to specific organizational units or groups, so only intended staff can start a sign-in. Decide which population should reach GitLab before go-live, then test with one account outside that population to confirm it is refused. Review membership changes as part of joiner and leaver processes, since access at the identity provider is what gates the instance.

Keep the SAML endpoints on HTTPS

The assertion consumer service URL and the GitLab base address should both use HTTPS with a certificate that your team can renew and monitor. Check that the URLs in the Google app match the values in gitlab.rb exactly, including the host name and path. A mismatch is a common cause of failed sign-ins that teams misread as an identity problem.

Plan certificate rotation before expiry

The SAML signing certificate that Google Workspace issues has a validity period, and GitLab stores the fingerprint you copied at setup. Record the expiry date, assign an owner, and schedule a rotation window that updates the fingerprint in GitLab before the old certificate lapses. Confirm the exact rotation steps with Google's current documentation and with GitLab's SAML settings reference.

Document the expiry response

If the certificate expires or the fingerprint is wrong, every SAML user is locked out at once. Write a runbook that names who can download the new certificate, who edits the GitLab configuration, who reconfigures the instance, and how changes are reconfigured and tested. Run the procedure once in a non-production instance so the steps are proven before an incident.

Keep a local administrator path

Retain at least one local administrator account with a strong password and a second factor held outside the identity provider, and test that it can sign in while SAML is enforced. Store its credentials under your privileged access process. Without this path, a broken identity configuration can leave the instance without any administrator who can repair it.

Pair SAML with enforced two-factor

SAML moves the password check to Google, but the GitLab instance still needs a policy on second factors for users who sign in through local accounts or the recovery path. Decide whether two-factor authentication is required instance-wide, for administrators only, or per group, and set a grace period that matches your rollout. Confirm which factors your policy accepts for each group.

Review sign-up and visibility settings

Self-managed GitLab has application settings for sign-up, default project visibility and outbound requests that affect who can join and what they can see, even with SAML in place. Review these against the GitLab hardening guidance and map each setting to a control in your own framework. Roll changes out gradually and record which owner approved each one.

Common Google Workspace SAML failures and fixes

This table lists the sign-in and provisioning failures teams most often hit when pairing self-managed GitLab with a Google Workspace custom SAML app, with the likely cause and fix for each. Read it as a checklist before go-live and as a first stop when users report errors. Exact error text should be matched against the GitLab production log for your installed version, since wording changes between releases.

Failure	Likely cause	Fix
Certificate fingerprint rejected after rotation	Google Workspace issued a new signing certificate and the fingerprint stored in gitlab.rb no longer matches the one Google presents	Download the current certificate from the Google SAML app, recompute the fingerprint, update the identity provider fingerprint setting and reconfigure GitLab before the old certificate expires
Assertion consumer service URL or entity ID typo	The ACS URL or entity ID in the Google app differs by one character or scheme from the values GitLab expects for your external_url	Copy both values from the GitLab SAML configuration into the Google app exactly, including https and the trailing path, then test sign-in again
NameID format mismatch creating duplicate or unlinked accounts	Google sends an email address where GitLab expects a persistent identifier, or the format changed after an earlier test, so existing users are not matched	Agree one NameID format and attribute mapping before onboarding users, check existing identities for the user, and unlink or correct duplicates before re-enabling sign-in
Users blocked by Google group scope	The SAML app is assigned only to some organizational units or groups, so users outside that scope receive an access denied page from Google before reaching GitLab	Confirm the app is turned on for the intended organizational units or groups in the Google admin console, then ask the affected user to sign in again
Clock skew or expired assertions	The GitLab server clock drifts from network time, so Google's assertion timestamps fall outside the accepted window	Confirm NTP is running and synchronized on GitLab nodes, then retry; the assertion window is short, so skew surfaces quickly
Sign-in succeeds but users are not provisioned	SAML only creates or links accounts at sign-in, and Google Workspace has no built-in user push to GitLab without SCIM, so users who never signed in do not exist in GitLab	Plan SCIM provisioning if accounts must exist before first sign-in or be disabled automatically on offboarding, and confirm the tier and steps for your version with GitLab's documentation

Testing sign-in before you open it to everyone

Before GitLab SAML sign-in reaches the whole workforce, run a pilot with a small set of test accounts that covers three kinds of users: a standard non-administrator, an administrator, and a user who should be refused access, such as a Google Workspace account outside the group you restricted the GitLab app to. Confirm that the standard user signs in through the Google Workspace custom SAML app and lands in GitLab as a new or linked account, that the administrator keeps administrator rights only where your gitlab.rb mapping assigns them, and that the blocked user is stopped at the identity provider or at GitLab. Check that the signed-in email address matches the expected GitLab account, so an existing local account is linked to the right person and never silently merged with another.

Next, test what happens to an active session when credentials change. Sign out and back in, change the Google account password in a test account, and confirm how GitLab behaves when the Google session expires or is revoked. Confirm which local GitLab password and two-factor settings still apply to accounts that were created before SAML was enabled, because those accounts may still authenticate without Google. Test the fallback path as well: while Google Workspace is unavailable or you deliberately disable the app for a test account, confirm that a named break-glass administrator can still reach GitLab through a documented local route. Write that route down, store its credentials under your normal privileged access controls, and confirm with GitLab's authentication documentation which sign-in methods remain active in your version.

Finally, write a rollback plan before enabling the setting for everyone: the exact gitlab.rb values to revert, who approves the revert, and how users are told to sign in with their previous method. Record each test case with its date, tester, account type, expected result, actual result and any defect, then attach that record to the change ticket. Auditors and your change board will want to see the evidence that the controls worked, so keep the record in the system of record you use for change management. Confirm the test scope and sign-off criteria with your security and compliance leads before the pilot starts, because a pilot that does not cover the fallback and rollback paths will not support a production decision.

Questions buyers ask about Google Workspace SAML for GitLab

How much effort does GitLab SAML setup with Google Workspace take?

The Google side is usually a single custom SAML app, but the effort depends on how many GitLab instances, groups and attribute mappings are involved. Effort rises when you must map group attributes for administrator or auditor roles, when several Google organizational units need different access, or when the GitLab instance runs behind a load balancer or in a multi-node layout that needs careful callback URL and certificate handling. Ask any partner to break the work into Google configuration, gitlab.rb changes, a test plan and a cutover plan, so you can see where the hours go.

Can our internal team set up Google Workspace SAML for GitLab without a partner?

Often yes, if you have a Google Workspace super administrator, a GitLab administrator with access to gitlab.rb and a test environment to try changes before production. The risks are less about the first sign-in and more about edge cases: users locked out after a certificate rotation, accounts with mismatched name IDs, and admin roles that were not mapped. Teams that lack recent SAML experience often use a partner for the design review and the cutover rehearsal while keeping day-to-day ownership in-house.

What access and information do we need from Google Workspace and GitLab administrators?

Expect to need the following from each side before work starts:

On Google Workspace: a super administrator or delegated admin who can create and configure a custom SAML app, plus the ability to download the IdP certificate and copy the SSO URL.
On GitLab: an administrator who can edit gitlab.rb, run reconfigure and read the logs, and a decision on the default sign-in method.
From both: a list of users and groups that should be allowed in, and a named owner for the cutover window.

Confirm these with your own identity team, since Google's admin roles and console labels can change.

Does Google Workspace SAML need SCIM, and what does SCIM change?

SAML handles sign-in, but it does not create or remove GitLab accounts by itself. Without SCIM, a user usually gets a GitLab account at first sign-in, and an account stays active until an administrator blocks it manually. SCIM provisioning automates account creation, updates and deprovisioning from the identity provider. Confirm with your own team which parts of Google Workspace are available for provisioning to GitLab and how deprovisioned users keep their identity, because this is the area most often assumed to work but not checked.

How does cost depend on scope, and what should a quote include?

Cost depends on the work scope and the GitLab edition you run, not on Google Workspace licensing alone. GitLab's pricing page lists Premium at 29 US dollars per user per month billed annually, and Ultimate is custom priced. SAML group mapping and SCIM are features you should verify against the edition you choose. A quote should separate one-time design, configuration and testing from any recurring support or retainer, and it should state which environments, which groups and which cutover rehearsals are included.

Which GitLab edition do we need for Google Workspace SAML and group features?

Check the feature list for your chosen tier before you design the solution. The pricing page lists advanced CI/CD and priority support for Premium, and application security testing, software supply chain security, vulnerability management and compliance features for Ultimate. Group sync and SCIM features are tied to paid tiers in GitLab's documentation, so confirm the exact tier for each capability against the authentication documentation before you commit to a design. Making that decision early avoids a redesign after procurement.

How long do testing and cutover take for a SAML sign-in change?

Duration depends on how many user populations you must test, whether a staging GitLab exists, and how much you rely on a parallel sign-in path during cutover. A typical plan covers a test group of named users, a check of admin and auditor roles, a rollback procedure that keeps a local administrator able to sign in, and a scheduled change window. Ask for the test matrix and the rollback steps in writing. The exact durations should come from the scope agreed with your team, not from a generic estimate.

Who runs this work in-house and who needs a partner

The identity team owns the Google Workspace side of the trust: the custom SAML app, its attribute mapping, the group membership that decides who can reach GitLab, and the signing certificate that GitLab must trust. They are the people who can see which users are in scope and which Google organizational units they belong to. Before any build starts, they should confirm which Google Workspace edition and admin roles are in place, who can change the SAML app, and how certificate renewal will be announced to the GitLab team.

App ownership: Confirm who creates and edits the custom SAML app and who approves changes to its settings.
Name ID and attributes: Agree the name ID format and the email attribute with the platform team before the first test sign-in.
Group scoping: Decide which Google groups grant access and document who maintains them.
Certificate renewal: Set a named owner and a notice period for rotating the signing certificate and its fingerprint in GitLab.
Offboarding path: Clarify what happens to existing GitLab accounts when a user leaves, since Google Workspace SAML alone does not deprovision them.

An outside partner can add value here by drafting the attribute and group mapping as a reviewed specification, with test accounts for each case. Ask whether the partner will hand over the Google-side configuration as exported, documented steps your admins can repeat.

The GitLab platform team owns the gitlab.rb configuration, the restart and reconfigure procedure, and the consequences of a mistake on the instance. They translate the Google values into the SAML block, decide how the provider is named, and verify sign-in on a staging instance before production. They also own the rollback plan, because a broken SAML setting can block administrators as well as ordinary users. Confirm the GitLab version and install method first, since the configuration location and reconfigure steps depend on them.

Configuration change control: Keep the SAML settings in version-controlled configuration and record each reconfigure.
Staging parity: Test on an instance that matches production's authentication path, including any reverse proxy or load balancer.
Break-glass access: Keep a local administrator account working outside SAML and test that it still signs in.
Upgrade interaction: Check the SAML settings after each planned upgrade, using the upgrade stops for your version.
Support boundaries: Decide who responds when sign-in fails at 2 a.m. and what logs they check first.

A partner adds the most value by producing a runbook covering sign-in failure triage, a tested break-glass procedure and a documented cutover with a rollback step. Ask for the test cases they ran and the evidence each one produced, not only a statement that sign-in works.

How DeployOpen scopes and delivers GitLab SSO work

DeployOpen plans, implements, tests and documents self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For GitLab SAML SSO with Google Workspace, we agree the scope in writing before work starts, then hand over a configuration your team can operate and audit.

How we scope

Confirm your GitLab edition and whether SAML sign-in alone or SAML with SCIM provisioning is in the written scope
Record your Google Workspace admin roles, the custom SAML app owner and the organizational units that will receive access
Agree which groups, if any, control administrator, auditor or external user status before any configuration begins

How we build

Create the custom SAML app in Google Workspace and map the attributes GitLab expects, including the name ID format
Set the certificate fingerprint and SAML settings in gitlab.rb, then reconfigure GitLab and verify the change took effect
Test sign-in with pilot users, including denied access for accounts outside the permitted groups and the fallback admin path

How we hand over

Deliver a runbook covering each configuration key, its source value in Google Workspace and the steps for certificate rotation
Document what Google Workspace cannot provision without SCIM, so your team plans account lifecycle and offboarding accordingly
Walk your identity and platform engineers through the test results and the rollback procedure

How we support

Fixed-scope engagements end with written acceptance of the agreed deliverables, not an open-ended hand-off
Ongoing support, upgrades and continuous testing are available as a retainer, scoped in writing
Ask any partner to confirm how changes to the SAML app will be reviewed, tested and recorded in your change process