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