debian-mirror-gitlab/doc/integration/google_workspace_saml.md
2021-03-11 19:13:27 +05:30

7 KiB

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