How to set up GitLab SAML SSO with Google Workspace (opens in new tab)

Organizations using GitLab.com SaaS can streamline access control by integrating SAML-based Single Sign-On (SSO) with Google Workspace. This setup enables automated user provisioning and dynamic permission management by mapping Google Workspace groups directly to GitLab roles. The result is a centralized security model that reduces manual administrative tasks while ensuring users have immediate, secure access to the platform.

Prerequisites and Architectural Benefits

• The integration requires a GitLab Premium or Ultimate subscription and Super Admin access to Google Workspace.
• Once configured, the authentication flow redirects users to Google for credentials, after which Google sends a SAML assertion to GitLab containing user details and group memberships.
• The system supports "Just-in-Time" provisioning, meaning GitLab accounts are created automatically upon a user's first successful login.
• Permissions are dynamic; GitLab updates group memberships and roles every time a user signs in to reflect their current status in Google Workspace.

Gathering GitLab Configuration Details

• Configuration must be performed at the GitLab top-level group rather than within individual subgroups.
• Administrators need to retrieve the Assertion Consumer Service (ACS) URL, which typically follows the format https://gitlab.com/groups/[your-group]/-/saml/callback.
• The Identifier (Entity ID) must be copied to uniquely identify the GitLab group within the Google identity provider settings.
• The GitLab SSO URL is the specific entry point users will utilize to initiate the authentication process.

Configuring the Google Workspace SAML Application

• Within the Google Admin Console, administrators must create a "Custom SAML app" to house the integration settings.
• The setup process provides a Google SSO URL and a certificate file (typically a .pem format) that must be saved for the GitLab-side configuration.
• The previously gathered GitLab ACS URL and Entity ID are entered into the Service Provider details section of the Google app configuration.

Mapping User Attributes and Synchronizing Groups

• Specific attribute mapping is required to ensure user data flows correctly: Google’s "Primary Email" should map to the "NameID," "First Name" to "firstName," and "Last Name" to "lastName."
• For group synchronization to function, administrators must map selected Google Groups to an app attribute named exactly groups (lowercase).
• Google allows for the synchronization of up to 75 groups, which GitLab uses to determine and update user permissions upon login.
• The application must be explicitly turned "ON" for specific organizational units or the entire domain within the Google Admin Console to allow user access.

Finalizing the Identity Provider Connection

• GitLab requires a SHA-1 certificate fingerprint for security verification rather than the raw certificate file provided by Google.
• Administrators must convert the downloaded Google .pem certificate into a SHA-1 fingerprint using an online conversion tool or a command-line utility.
• This fingerprint, along with the Google SSO URL, is entered into GitLab’s SAML SSO settings to establish the trusted connection between the two platforms.

To ensure a smooth rollout, it is recommended to test the integration with a small group of users before enforcing SAML for the entire organization. This allows administrators to verify that group-based permissions are mapping correctly to GitLab roles without disrupting existing workflows.