gitlab 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.