debian-mirror-gitlab/doc/integration/google_workspace_saml.md

type	stage	group	info
reference	Manage	Access	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Google Workspace SSO provider

Google Workspace (formerly G Suite) is a Single Sign-on provider that can be used to authenticate with GitLab.

The following documentation enables Google Workspace as a SAML provider for GitLab.

Configure the Google Workspace SAML app

The following guidance is based on this Google Workspace article, on how to Set up your own custom SAML application:

Make sure you have access to a Google Workspace Super Admin account. Follow the instructions in the linked Google Workspace article, where you'll need the following information:

	Typical value	Description
Name of SAML App	GitLab	Other names OK.
ACS URL	https://<GITLAB_DOMAIN>/users/auth/saml/callback	ACS is short for Assertion Consumer Service.
GITLAB_DOMAIN	gitlab.example.com	Set to the domain of your GitLab instance.
Entity ID	https://gitlab.example.com	A value unique to your SAML app, you'll set it to the issuer in your GitLab configuration.
Name ID format	EMAIL	Required value. Also known as name_identifier_format
Name ID	Primary email address	Make sure someone receives content sent to that address
First name	first_name	Required value to communicate with GitLab.
Last name	last_name	Required value to communicate with GitLab.

You will also need to setup the following SAML attribute mappings:

Google Directory attributes	App attributes
Basic information > Email	email
Basic Information > First name	first_name
Basic Information > Last name	last_name

You may also use some of this information when you Configure GitLab.

When configuring the Google Workspace SAML app, be sure to record the following information:

	Value	Description
SSO URL	Depends	Google Identity Provider details. Set to the GitLab idp_sso_target_url setting.
Certificate	Downloadable	Run openssl x509 -in <your_certificate.crt> -noout -fingerprint to generate the SHA1 fingerprint that can be used in the idp_cert_fingerprint setting.

While the Google Workspace Admin provides IDP metadata, Entity ID and SHA-256 fingerprint, GitLab does not need that information to connect to the Google Workspace SAML app.

---

Now that the Google Workspace SAML app is configured, it's time to enable it in GitLab.

Configure GitLab

1. See Initial OmniAuth Configuration for initial settings.

2. To allow people to register for GitLab, through their Google accounts, add the following values to your configuration:

   For Omnibus GitLab installations

   Edit /etc/gitlab/gitlab.rb:

   gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
   gitlab_rails['omniauth_block_auto_created_users'] = false
   

   ---

   For installations from source

   Edit config/gitlab.yml:

   allow_single_sign_on: ["saml"]
   block_auto_created_users: false
   

3. If an existing GitLab user has the same email address as a Google Workspace user, the registration process automatically links their accounts, if you add the following setting: their email addresses match by adding the following setting:

   For Omnibus GitLab installations

   Edit /etc/gitlab/gitlab.rb:

   gitlab_rails['omniauth_auto_link_saml_user'] = true
   

   ---

   For installations from source

   Edit config/gitlab.yml:

   auto_link_saml_user: true
   

4. Add the provider configuration.

For guidance on how to set up these values, see the SAML General Setup steps. Pay particular attention to the values for:

• assertion_consumer_service_url

• idp_cert_fingerprint

• idp_sso_target_url

• issuer

• name_identifier_format

  For Omnibus GitLab installations

  gitlab_rails['omniauth_providers'] = [
    {
      name: 'saml',
      args: {
               assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback',
               idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00',
               idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000',
               issuer: 'https://<GITLAB_DOMAIN>',
               name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress'
             },
      label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml"
    }
  ]
  

  For installations from source

  - {
      name: 'saml',
      args: {
             assertion_consumer_service_url: 'https://<GITLAB_DOMAIN>/users/auth/saml/callback',
             idp_cert_fingerprint: '00:00:00:00:00:00:0:00:00:00:00:00:00:00:00:00',
             idp_sso_target_url: 'https://accounts.google.com/o/saml2/idp?idpid=00000000',
             issuer: 'https://<GITLAB_DOMAIN>',
             name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress'
           },
      label: 'Google Workspace' # optional label for SAML log in button, defaults to "Saml"
    }
  

1. Reconfigure or restart GitLab for Omnibus and installations from source respectively for the changes to take effect.

To avoid caching issues, test the result on an incognito or private browser window.

Troubleshooting

The Google Workspace documentation on SAML app error messages is helpful for debugging if you are seeing an error from Google while signing in. Pay particular attention to the following 403 errors:

• app_not_configured
• app_not_configured_for_user