Identity as a Service:GitLab SAML SSO

Configure Security Assertion Markup Language (SAML)-based single sign-on (SSO) for a self-managed GitLab instance using Identity as a Service (IDaaS) as the identity provider (IdP). After configuration, users can log in to GitLab through their IDaaS accounts.

Key concepts

Term	Description
Identity provider (IdP)	The service that authenticates users and issues SAML assertions. In this guide, IDaaS acts as the IdP.
Service provider (SP)	The application that accepts SAML assertions to grant access. In this guide, GitLab acts as the SP.
Assertion Consumer Service (ACS) URL	The GitLab endpoint that receives SAML responses from the IdP after authentication.
Issuer	How GitLab identifies itself to IDaaS in SAML requests. Also known as Entity ID.
Certificate fingerprint	A Secure Hash Algorithm (SHA)-1 hash of the IdP's signing certificate. GitLab uses this to verify that SAML responses come from the correct IdP. Also known as certificate thumbprint.
Just-in-time (JIT) provisioning	GitLab automatically creates a user account the first time a user logs in through SSO, if no matching account exists.

Prerequisites

Before you begin, make sure that:

You have administrator access to the IDaaS console
You have administrator access to the GitLab server to modify its configuration file

Step 1: Add the application in IDaaS

Log in to the IDaaS console as an administrator. On the EIAM page, click the target instance.
In the left-side navigation pane, click Applications. On the Applications page, click Add Application to go to the Marketplace tab.
Search for GitLab SAML, click the result, and then click Add Application. Confirm the application name and click Add. After the application is added, the console redirects you to the SSO tab.
On the SSO tab, configure the GitLab Service Address parameter. Enter your GitLab domain. The value must not end with a forward slash (/).
Leave all other parameters at their default values and click Save.
Note
The default Application Username is IDaaS Username, and the default Authorize scope is All Users. To restrict access to specific IDaaS accounts, update the Authorize setting after saving.
On the Sign-In tab, go to the Application Settings section. Note the values shown there — you will need them when configuring GitLab in the next step.

Step 2: Configure SSO in GitLab

Edit the GitLab configuration file on your server. The file path differs by installation method:

Omnibus: /etc/gitlab/gitlab.rb
Self-compiled (source): /home/git/gitlab/config/gitlab.yml

Open the file in a text editor:

# Omnibus installation
sudo editor /etc/gitlab/gitlab.rb

# Self-compiled installation
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml

Add the following configuration. Replace the placeholder values as described in the parameter table below.

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers']=[
  {
    name: 'saml',
    args: {
      name: 'saml',
      assertion_consumer_service_url:'http://gitlab.example.com/users/auth/saml/callback',
      issuer:'http://gitlab.example.com/users/auth/saml',
      idp_cert_fingerprint:'23:f8:77:03:fc:69:4c:da:ac:7e:4a:42:5a:87:5a:b3:ad:a8:d9:df',
      idp_sso_target_url:'https://example.aliyunidaas.com/login/app/app_mivpoqqmz7zrslxcmlyxa25me4/saml2/sso',
      name_identifier_format:'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
      attribute_statements: {
        nickname: ['username'],
      },
    },
    label:'EIAM2.0'
  }
]

Replace only the following parameters. All other parameters can remain at their default values.

`gitlab.rb` parameter	IDaaS console field	Format	Notes
`args.assertion_consumer_service_url`	—	`http://<your-gitlab-domain>/users/auth/saml/callback`	Append `/users/auth/saml/callback` to your GitLab domain
`args.issuer`	—	`http://<your-gitlab-domain>/users/auth/saml`	Append `/users/auth/saml` to your GitLab domain
`args.idp_sso_target_url`	Application Settings section on the Sign-In tab	—	Copy the value directly from the IDaaS console
`args.idp_cert_fingerprint`	IdP certificate (download from IDaaS)	`xx:xx:xx:...:xx` (SHA-1, colon-separated)	After downloading, check the certificate attributes for the SHA-1 fingerprint. Add colons (`:`) between each pair of hex characters if they are absent.

For self-compiled installations, the parameter names and structure differ from the Omnibus format. See SAML OmniAuth in the GitLab documentation for the equivalent YAML configuration.

After editing the file, restart GitLab to apply the changes:

# Omnibus: reload the configuration and restart
sudo gitlab-ctl reconfigure
sudo gitlab-ctl restart

# Self-compiled (systemd)
sudo systemctl restart gitlab.target

# Self-compiled (SysV init)
sudo service gitlab restart

After GitLab restarts, a Login with AliyunIDaaS button appears at the bottom of the GitLab login page.

Step 3: Test SSO

IDaaS supports both IdP-initiated SSO and SP-initiated SSO.

IdP-initiated SSO

Log in to the IDaaS portal using an IDaaS account that has access to the GitLab application. Click the GitLab icon to initiate SSO.

SP-initiated SSO

Open the GitLab login page in a private browser window and click Login with AliyunIDaaS. Log in to IDaaS when prompted. After authentication, GitLab redirects you back and logs you in.

Note

GitLab supports just-in-time provisioning. If the IDaaS account does not have a matching GitLab account, GitLab creates one automatically on first login.

What's next

To learn more about SAML configuration options for self-managed GitLab, see SAML OmniAuth in the GitLab documentation.
To configure application accounts or restrict access to specific users, see the application account settings in the IDaaS console.