Set up GitLab

Configuring GitLab to authenticate with SAML2 enterprise authentication using Ipsilon.

This guide describes how to set up GitLab to authenticate against Ipsilon as a SAML2 SP, with automatic account creation on login.

This guide has been tested with:

• Fedora 23
• FreeIPA 4.2.3
• Ipsilon 1.1.1
• GitLab CE 8.3.2 (CentOS 7 omnibus RPM)

but is known to work with older versions.

Prerequisites:

• FreeIPA installed and configured
• Ipsilon installed and configured on an IPA client host

Generate certificate

Generate a new certificate and key to be used for the SAML SP side (for the Common Name of the certificate you can enter anything, as only the key part is used):

openssl genrsa -out server.key 4096
openssl req -new -key server.key -out server.csr
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Install Gitlab

• Download and install the gitlab-ce omnibus RPM.
• Run "gitlab-ctl reconfigure" to do the initial set up of GitLab
• Set up SSL. In brief:
  • Edit /etc/gitlab/gitlab.rb
  • Change the external_url setting url to https
  • Create /etc/gitlab/ssl as root:root 700
  • Create /etc/gitlab/ssl/hostname.{crt,key} with the SSL cert and key in (creation of the these is outside the scope of this guide)
  • Re-run "gitlab-ctl reconfigure"
• Log into Gitlab and reset the admin user password
• Optionally disable the login page user sign-up form, so users can't be created without going through Ipsilon:
  • Navigate to Admin Area -> Settings
  • Untick Sign-up enabled
  • Click Save
• If you want to force SAML2 logins, you can also turn off "Sign-in enabled" in the same place, but do this after you've got an admin user who can log in via SAML2
• Add the SAML auth stanza to the gitlab.rb file and re-run "gitlab-ce reconfigure"

The auth stanza is as follows:

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = true
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
  {
    "name" => "saml",
    "args" => {
      "label" => "Log in via SAML",
      "assertion_consumer_service_url" => "https://gitlab.example.com/users/auth/saml/callback",
      "idp_cert" => "< PEM format ipsilon IdP certificate >",
      "idp_sso_target_url" => "https://ipsilon.example.com/idp/saml2/SSO/Redirect",
      "issuer" => "https://gitlab.example.com",
      "name_identifier_format" => "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "certificate" => "< PEM format gitlab SP client cert >",
      "private_key" => "< PEM format gitlab SP client key >",
      "security" => {
        "authn_requests_signed" => "true",
        "digest_method" => "XMLSecurity::Document::SHA1",
        "signature_method" => "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
      }
    }
  }
]

Change the assertion_consumer_service_url, idp_sso_target_url, issuer, and cert and key entries appropriately. This should end up looking something like:

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = true
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
  {
    "name" => "saml",
    "args" => {
      "label" => "Log in via SAML",
      "assertion_consumer_service_url" => "https://gitlab.example.com/users/auth/saml/callback",
      "idp_cert" => "-----BEGIN CERTIFICATE-----
MIID...
-----END CERTIFICATE-----",
      "idp_sso_target_url" => "https://ipsilon.example.com/idp/saml2/SSO/Redirect",
      "issuer" => "https://gitlab.example.com",
      "name_identifier_format" => "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
      "certificate" => "-----BEGIN CERTIFICATE-----
MIIDG...
-----END CERTIFICATE-----",
      "private_key" => "-----BEGIN PRIVATE KEY-----
MIIE...
-----END PRIVATE KEY-----",
      "security" => {
        "authn_requests_signed" => "true",
        "digest_method" => "XMLSecurity::Document::SHA1",
        "signature_method" => "http://www.w3.org/2000/09/xmldsig#rsa-sha1"
      }
    }
  }
]

After this configuration, there should be a "Sign in with SAML" button on the GitLab login page, but this won't work until the SP configuration is done.

SP Configuration in Ipsilon

You'll need to the metadata XML file for GitLab to upload to Ipsilon. This can be found at https://gitlab.example.com/users/auth/saml/metadata

In the Ipsilon admin UI, select Identity Providers -> saml2 -> Manage -> Add New. Fill in the following values, at a minimum:

• Name
• Link to Service Provider
• Metadata (either uploading a file, pasting the text or supplying the metadata URL) Click Save.

In addition to the above config, the following attribute mappings need to be configured in the SP configuration. These are needed to provide enough information to GitLab to allow new accounts to be created.

Attribute Mappings:

• surname -> last_name
• firstname -> first_name
• fullname -> name
• email -> email

Debugging account creation and login

If login or account creation fails, you should receive a 422 error page. The error may be embedded in the url of the page. Also check /var/log/gitlab/gitlab-rails/application.log and /var/log/gitlab/unicorn/unicorn_stdout.log.

Further Info

• GitLab SAML2 integration docs
• GitLab uses OmniAuth SAML for SAML2 auth, so those docs may also be of use.