How to set up GitLab Single Sign-On with Google G Suite

Most companies are using Google G Suite for their business needs, like business email, video conferencing, online storage and file sharing. Ministry of Programming is using it as well. Recently we decided to move from GitHub to GitLab and we wanted to integrate Google G Suite accounts with GitLab and make it easier to access using Single Sign-On (SSO).

Note: It is just a coincidence that we are moving at the same time when Microsoft acquired GitHub.

We are giving life to startups from the first line of code and the reasons for this decision are:

1. Cost: As we are using GitHub business plan, the math is clear here. We are paying ~17.5K dollars per year. This price could be a decent seed investment for a new startup.
2. Migration easiness: It is very easy to import projects from GitHub to GitLab. They already prepared very good documentation on the topic.
3. Free: GitLab CE version is free, can be self-hosted and that is suitable for us. We are using AWS cloud as the hosting option and our projected cost will be ~1.2K dollars per year including backups.

Running GitLab in the container

We are using docker compose to define/spin GitLab in the container with attached EBS volumes. We are doing a backup of EBS volumes every day and GitLab database is running on AWS RDS with Multi-AZ and backups. Below you can find our docker-compose.yaml file.

As you can see we are using SAML as authentication method to connect our Google G Suite accounts. All of our users are automatically logged in as soon as they visit our GitLab website. We are not allowing registration and login without G Suite account. GitLab has a good documentation and you can do further GitLab customization if you need something special.

We will share how we configured our GitLab to act as a SAML 2.0 Service Provider (SP), which allows us to consume assertions from a SAML 2.0 Identity Provider (IdP), such as Google G Suite to authenticate users.

Important: Always keep one/first admin account with MFA, just to avoid possible access issues. Once you login with your G Suite account, add your account as admin and don’t use root account anymore.

Adding GitLab as SAML application in the Google Apps admin console

1. As an administrator of your G Suite account, sign into the Admin Panel.
2. From the Admin console select Apps → SAML apps.

Admin console

Apps

3. Click the plus (+) icon in the bottom corner and then pick SETUP MY OWN CUSTOM APP.

Enable SSO for SAML Application

4. Copy the SSO URL field value and download the X.509 Certificate, paste them into the docker compose file under SAML configuration and then click Next. Later, we will need to get the X.509 Certificate fingerprint.

Google IdP Information

5. In the Basic Information for your Custom App window, add an application name, description and upload a logo if you want.

Basic information for your Custom App

6. In the Service Provider Details window, provide Service Provider details to configure SSO for your Custom App and then click Next.

• ACS URL: The URL should be https://gitlab.example.com/users/auth/saml/callback
• Entity ID: Enter https://gitlab.example.com
• Start URL: Enter https://gitlab.example.com
• Signed Response: Disable
• Name ID: Basic Information — Primary Email
• Name ID Format: EMAIL

Your GitLab Service Provider Details

7. In the Attribute Mapping window, click on ADD NEW MAPPING, enter the application attribute “emailAddress” — Basic Information — Primary Email and then click Finish.

Attribute Mapping

Getting the X.509 Certificate fingerprint

To get X.509 certificate fingerprint, you can use the third-party fingerprint calculator.

1. Go to https://www.samltool.com/fingerprint.php.
2. Open your downloaded certificate in text editor, copy and paste in X.509 cert field.
3. Leave the Algorithm set to sha1.
4. Click the CALCULATE FINGERPRINT button. The formatted fingerprint looks like: XX:DD:90:D2:15:9F:12:78:D5:XX:XX:88:XX:6E:XX:FD:XX:60:XX:B1

Updating GitLab SAML configuration

After setting up Google G Suite, you need to update your GitLab SAML configuration. You will need the X.509 certificate fingerprint and a few pieces of information from previous steps to finish the configuration.

• assertion_consumer_service_url: GitLab URL with PATH
  https://gitlab.example.com/users/auth/saml/callback
• idp_cert_fingerprint: X.509 Certificate fingerprint
  XX:DD:90:D2:15:9F:12:78:D5:XX:XX:88:XX:6E:XX:FD:XX:60:XX:B1
• idp_sso_target_url: SSO URL from your Google G Suite SAML App
  https://accounts.google.com/o/saml2/idp?idpid=XXXXXXXXX
• issuer: Your unique Entitiy ID which you added to your Google G Suite SAML App https://gitlab.example.com
• name_identifier_format: SAML format for email address.
  urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
• attribute_statements: GitLab in SAMLResponse expect email or mail, so we are mapping email to our G Suite configuration where we used “emailAddress”{ ‘email’: [‘emailAddress’] }
• label: Put what you want to write on the button

Enabling G Suite SAML App

When you create a SAML App, it is turned off by default. This means that the app will not be visible to users signed in to your Google domain account.

To turn it on, go to your Google Admin console, click App, and then click SAML Apps. Find your app (gitlab) and select an action from the right side of the screen.

Enabling GitLab SAML App on your G Suite

If you do not want to activate the app for everyone, you can take advantage of G Suite/Google Apps organizational units and activate the app for only a subset of users.

Testing your SSO authentication

After you’ve successfully spinned up the docker container with the above configuration, you should see your button on the login page. If you’ve followed these steps, you should not have any issues to access your GitLab and you are ready to rumble!

If any help required please comment below.