The ultimate guide to enabling SAML and SSO on GitLab.com

As a follow-on to the recent blog, The ultimate guide to securing your code on
GitLab.com,
we recommended enabling SAML (Security Assertion Markup Language) and SSO (single
sign-on) to enable tighter control over code access. Let’s take a deep dive into
how to enable SAML and SSO on GitLab.com.

What are SAML and SSO?

SAML is an open standard, which service providers (like GitLab.com) and
identity providers (commonly referred to as IdPs) use to communicate
authentication data. SSO is provided by IdPs, such as Okta and Entra ID
(formerly Azure AD), and enables users to log into multiple systems or service
providers through a single interface with a single set of credentials.

As with any configuration, there should be thoughtful and careful planning when
enabling SSO.

What are the benefits of SSO?

In general, enabling SSO streamlines the user experience by unifying the login
process and reducing the account and password bloat required for multiple
enterprise applications. Enabling SSO also adds an extra layer of security and
management efficiency for identity management teams by providing a single
source of truth for authentication. Below, you’ll learn how SAML SSO applies
specifically to GitLab.com.

Configuring SSO and SAML for GitLab.com

Premium and Ultimate tiers can enable SSO in the settings available at the
namespace or top level group.

Enabling SSO at the group level

Before getting started, you’ll need a few key
pieces of information from your chosen IdP:

• The IdP SSO URL
• The certificate fingerprint provided by the IdP application

Once these key pieces are entered, check the “Enable SAML
authentication for this group” box.

How user accounts are linked

Before we proceed further into configuration, let’s take a look at how GitLab
authenticates against the IdP.

For GitLab.com, each user who requires access to
the system must have an account on GitLab.com. By default, when a user first
attempts logging into GitLab via SSO, GitLab will receive the SAML assertion
and validate if the identity (specifically the email address) is linked to a
GitLab.com account. If not, GitLab will request the user either login to an
existing account or create a new account. In most instances, this may not be
desired behavior; however, we will address this later in the process. We’ve
provided a flowchart below to help you navigate the provisioning flow.

Enforcing SSO

To further increase security, there are two options available for enforcing
SSO. Assuming neither are checked, users with access to the namespace can log
in with either the SSO credentials or the GitLab.com credentials.

Here is a working example that we can use to follow along as we discuss how the
configuration options affect our baseline. Let’s consider a user in the IdP
where the username is idpusername and contains a super secret password:
idppassword (apologies, security professionals). Taking into account the
information we just learned about account linking, let us also assume our demo
user created a new account following the prompt from an SSO login with a
username of gitlabusername and gitlabpassword as an even more secure
password.

Enforcing SSO only for web

When enabling the “Enforce SSO-only authentication for web activity for this
group” setting, all members must now access all groups and projects under the
hierarchy using the configured SSO login regardless of whether they have an
existing SAML identity. As we mentioned prior, with this flag disabled, our
idpusername user will be able to log into the GitLab namespace with either
the idpusername or gitlabusername credential sets. When we enable this
setting for web-based activity (further details in
docs),
our group is now only accessible by the idpusername credential set.

Enforcing SSO only for Git proxy

Very similar to enforcing SSO for web, when the “Enforce SSO-only
authentication for Git and Dependency Proxy” activity for this group option is
enabled, a few things happen:

• Calling an API endpoint that involves Git activity requires SSO.
• For Git activity over SSH and HTTPS, users must have at least one active session signed-in through SSO before they can push to or pull.

There is a strong recommendation to enable both of these settings to take full
advantage of the benefits of SSO for users and administrators through
centralized authentication.

Enterprise user support

Now that we know how some of the configuration options can help secure access,
let’s take a deeper dive into user management. Consider the following scenario:
Our idpusername user has decided to pursue another opportunity outside of the
domain. Based on what we have configured now, once the account has been
deprovisioned from the IdP, it should no longer have access to anything secured
behind it on GitLab.com. However, while the user will not have access, the
associated user ID and roles still remain until manually removed. This is where
Enterprise users come in.

What are Enterprise users in GitLab?

If you look closely, any user that has a linked SSO account will carry a SAML
badge in the member list. GitLab also has an associated Enterprise badge
that grants additional management functionality through SSO. For a user to
carry the Enterprise badge, the user must either have the initial GitLab.com account creation initiated by a SAML SSO login or have the initial GitLab.com account created by SCIM.

What is SCIM?

SCIM, or System for Cross-domain Identity Management, is another standard
used in conjunction with SAML, primarily for provisioning and deprovisioning
across multiple systems. By enabling SCIM for your GitLab.com group (which is
currently supported with Entra ID and Okta), you can enable automatic
provisioning and deprovisioning of accounts.

If we look back at some of our scenarios, without SCIM, our idpusername user
was prompted to create or link a GitLab.com account on first login. With SCIM
enabled, this process is handled automatically based on information provided
and managed by the IdP and is completely transparent to the end user. The
second half of our scenario, where our idpusername user is deprovisioned from
the IdP, also is solved with automation via SCIM. In this instance, when the
user is removed on the IdP side, SCIM automatically disconnects the SAML
identity from the GitLab.com account and removes the user from the GitLab.com
group.

Protecting your intellectual property

Another important feature of Enterprise users is the ability to control two
very important user settings that are not accessible to group administrators on
GitLab.com. Since all users require an account on GitLab.com, they are also
granted access to a personal user namespace. For example, our idpusername will have access to our Acme Corp. group at .com/acmecorp, and will also have
access to their own personal space at .com/idpusername. One common concern with this is the ability for users to take code out of the organization
namespace and commit to their own personal namespace.

With Enterprise users, we have two settings that we can control based on attributes received in the SAML
response. These keys are projects_limit and can_create_groups. The
projects_limit is an integer value that sets the amount of projects a user
can create in their personal namespace. When set to 0, this effectively
disables project creation in that space. Similarly, can_create_group is a
boolean true or false value that indicates whether a user can create new
groups.

Managing roles with SAML

Now that we know the ins and outs of creating and removing users with SAML and
SCIM, how can we leverage our work to help manage our active users? In this
final section, we’ll take a look at why we recommend setting default membership
to "Minimal Access" and how to leverage group memberships in the IdP.

Why Minimal Access?

In the Ultimate guide to securing your code on GitLab,
we recommend setting the default membership role to Minimal Access, and
operating with the concept of least privilege. Roles can be elevated as needed
in subgroups or individual projects while preventing visibility to projects or
subgroups where the user is not explicitly granted another role. By default,
this option is set to Guest, which will allow all provisioned users guest
access to the repositories. Default membership controls are available at the
top-level group, along with the SAML and SSO settings. For automation at the
subgroup level, we can leverage SAML Group Sync.

Configuring SAML Group Sync with SAML Group Links

Before we dive into the configuration, there is one very important step we need
to take. The configured SAML assertion that is sent MUST include an attribute
named Groups or groups. If SAML Group Links are present without the
attribute in the assertion, users may be removed from the group or reverted to
Minimal Access.

After we ensure our assertions contain the necessary information, we can start
using SAML Group Links to automatically assign membership roles to GitLab
groups based on group membership in the IdP. Let’s build on our demo user
idpusername by considering the following:

• idpusername is a maintainer on the acme-web project.
• The acme-web project exists under the acme-corp namespace, under subgroup acme-com.
• The full path to the project would be .com/acme-corp/acme-com/acme-web.
• idpusername should also be granted developer access for the acme-db project, which is also under the acme-com group.
• In our IdP, idpusername is a member of the IdP group idp-acme-com.

SAML group links allow us to map IdP group memberships to role assignments at
the GitLab group level. In this scenario, we can create a group link at the
acme-com group in GitLab that maps the IdP group idp-acme-com to the
developer role to the acme-com group.

Due to inheritance, our idpusername
user will be granted developer access and associated visibility to every
project and group that falls under the GitLab acme-com group automatically by
virtue of the IdP group membership, because we’re working under the concept of
least privilege for the acme-web project.

The idpusername user’s role can
be elevated to maintainer directly in the project. From a user perspective,
idpusername would still carry the Minimal Access role at the acme-corp
group as well. This allows a separation of access management between
engineering and identity management teams and allows role management to be
flexible with guardrails.

With this approach, it’s important to find that balance between what is managed
in the IdP and what is managed in GitLab. It’s possible to have hundreds of
group mappings to roles in the IdP and almost completely remove role management
within GitLab and vice versa. The flexibility that GitLab allows enables you to
find the best solution that works for you. Building on our example, if we hire
another engineer for the acme-com project, they can be added to the GitLab
application in the IdP, and added to the idp-acme-com group. This
automatically assigns them the developer role at the acme-com group and for
all projects under it, while limiting access to any other groups outside of
acme-com in the namespace.

Learn more

We’ve covered how to get started with enabling SAML and SSO on your GitLab.com
group, along with how to leverage the features to programmatically manage users
and roles with real examples. For more information, see the full SAML SSO for
GitLab.com groups
documentation.

Cover image by Towfiqu barbhuiya on Unsplash