GitLab SAML SSO with Microsoft Entra ID

How GitLab SAML SSO with Microsoft Entra ID works in a self-managed instance

Your identity team wants employees to sign in to self-managed GitLab with their Entra ID credentials, and the supported way to do that is SAML. You configure GitLab Self-Managed through its authentication settings in gitlab.rb, and you register GitLab in Entra ID as an enterprise application. GitLab's authentication documentation lists SAML among the protocols GitLab Self-Managed supports, alongside LDAP, generic OAuth 2.0, Kerberos, JWT, smart card authentication and SCIM, so confirm that the SAML settings you plan to use match the version you are running before you start.

When a user signs in, Entra ID authenticates them against the tenant's policies, including any conditional access and multifactor requirements, and then sends GitLab a signed SAML assertion. That assertion carries a name identifier, which GitLab uses to match the user to an account, plus optional attributes such as email, username and group memberships. The name identifier format and the attribute names must agree between the Entra ID app and GitLab, so decide them with your identity team before the first test. Group claims are the part most often misconfigured, because the group values GitLab reads for administrator, auditor and external status must arrive in the assertion exactly as expected.

SAML sign-in and SCIM provisioning are separate mechanisms. SAML answers the question of who is signing in at a given moment and whether they may enter. SCIM is a provisioning protocol that creates, updates and deactivates accounts ahead of sign-in and keeps group membership current. A working SAML setup does not remove a leaver's account on its own, and an account created through SAML sign-in may not reflect later changes in Entra ID. Plan both from the start, and confirm with your GitLab edition and tier which provisioning features your instance includes.

What you need in place before configuring Entra ID and GitLab

Most SAML failures trace back to prerequisites that were assumed rather than confirmed. Each item below is something to verify on the GitLab side, the Entra ID side, or in your own change process before anyone opens the enterprise application wizard. Work through them in order, because the certificate and group decisions affect the GitLab configuration you write.

A stable GitLab external URL

The external URL in gitlab.rb becomes the Assertion Consumer Service address that Entra ID posts sign-in responses to, so it must match exactly what users type in their browsers. Changing the hostname later means re-registering the Entra application and updating every SAML setting that embeds it. Confirm the hostname, DNS record and valid HTTPS certificate on the instance before you start, and confirm that the certificate chain is trusted by the browsers your users run.

Administrative access to gitlab.rb

Most SAML settings live in gitlab.rb, and changes take effect only after a reconfigure run. Confirm that the people doing the work have root access to the GitLab host, a tested path to run gitlab-ctl reconfigure, and a current backup of the configuration files. Also confirm who approves configuration changes in your change process, because a typo in a SAML key can lock administrators out of the sign-in page.

Entra ID rights for enterprise applications

Registering a SAML enterprise application and assigning users or groups to it requires an Entra role with permission to manage enterprise applications, typically Application Administrator or Cloud Application Administrator. Confirm with your identity team which role the implementer will use, whether conditional access policies will apply to the new app, and who can grant admin consent if any API permissions are later required for SCIM.

Group structure for admin and external roles

GitLab can read group claims from the SAML response to grant administrator, auditor or external user status, but only groups that exist in Entra and are included in the claim can do so. Decide which Entra groups map to GitLab administrators, which map to auditors, and which users are treated as external. Ask for the group object IDs and the claim name in writing, and confirm whether nested groups or dynamic groups will be used, since those can change what appears in the token.

A named owner for certificate expiry

The SAML signing certificate that Entra ID issues expires, and when it does, sign-in stops for every user. Record the expiry date, the thumbprint GitLab will trust, and the name of the person and mailbox that receive renewal notices. Agree in advance how the renewed certificate will be rolled out to GitLab, including who edits gitlab.rb, when the reconfigure runs, and how the change is tested before users are affected.

GitLab version and upgrade stops

Before you configure anything, confirm the GitLab version you run against the current maintenance policy, including which releases are maintained and which patch level you are on. If an upgrade is pending, check the required upgrade stops first, because SAML settings that work on one release may need different key names after a stop. Confirm the SAML settings against the current GitLab authentication documentation, since key names can change between releases.

Configuration sequence for the Entra ID SAML application

This sequence builds the trust between a Microsoft Entra ID enterprise application and your self-managed GitLab instance, so that assigned users can sign in through Entra ID and GitLab receives the identity, group and certificate data it needs. Each step closes with a check you can run before moving on.

Create the enterprise application with SAML
An Entra ID administrator creates a non-gallery enterprise application in the Entra admin center, then opens its single sign-on settings and selects SAML. The SAML configuration panel should appear with the Basic SAML configuration section ready to edit. Confirm that the application is listed under enterprise applications in the tenant where your users are managed before you continue.
Set the identifier and reply URL
Copy the Entity ID (issuer) and the assertion consumer service URL from GitLab's SAML documentation for your instance's external URL, and enter them as the identifier and reply URL in Basic SAML configuration. Both values must match your external URL exactly, including protocol and path, because GitLab rejects responses addressed to a different endpoint. The check is a saved Basic SAML configuration with no validation errors shown in the blade.
Configure the NameID and user attribute claims
Set the NameID source and format so that it matches the name_identifier_format value you plan to use in gitlab.rb, typically a stable identifier or email address that will not change for a user. Map the attribute claims GitLab reads, such as email and name, to the matching Entra user properties. Test with an assigned user, then open the browser developer tools during sign-in, find the SAML response in the network trace, and confirm the NameID and attribute values are present.
Create groups and assign users to the application
Create or identify the Entra security groups that will control GitLab access, such as a group for users, one for administrators and one for auditors, and add a group claim to the token configuration if you plan to map roles from SAML attributes. Assign those groups or individual test users under Users and groups for the application. The check is that an assigned test user sees the application in their My Apps portal and an unassigned user does not. Confirm the exact claim format with your GitLab version's SAML documentation.
Download the signing certificate and record its fingerprint
In the SAML signing certificate section, download the certificate in Base64 format or the federation metadata XML, and note the App Federation Metadata URL for reference. Calculate the certificate fingerprint from that file and record it with the Entra application's identifier and the sign-on URL, since GitLab uses the fingerprint to verify responses. Confirm the fingerprint against the value Entra displays for the active signing certificate. A mismatch does not appear during configuration. It appears as an error when a user tries to sign in.
Add the SAML block to gitlab.rb
On the GitLab server, edit the SAML provider block in /etc/gitlab/gitlab.rb under the omniauth provider settings. Enter the issuer, the Entra sign-on URL as idp_sso_target_url, the recorded idp_cert_fingerprint, the name_identifier_format and any attribute_statements you mapped in Entra. Keep admin, auditor and external group settings in the same file if you plan to use them. Check that the file is saved and that the values match the Entra configuration exactly, since small typos are the most common cause of sign-in failure.
Run reconfigure to apply the settings
Run sudo gitlab-ctl reconfigure on the GitLab server so that the new SAML settings are written into the running configuration. Watch the output for errors in the configuration step, since a malformed gitlab.rb entry stops the run before changes apply. The check is that the command completes without errors, and that GitLab services restart cleanly. If the command fails, fix the reported setting and run it again before testing sign-in.
Confirm the Entra ID button and test sign-in
Open the GitLab sign-in page in a private browser window and confirm that the Entra ID button is shown. Sign in as an assigned test user and check that GitLab creates or matches the account. If sign-in fails, inspect the SAML response in the browser developer tools and the GitLab production log in the gitlab-rails log directory, where fingerprint, issuer and NameID errors are recorded. Keep the test user and log entries as evidence before you plan SCIM provisioning.

Which Entra ID fields map to which GitLab settings and roles

This table compares each Entra ID attribute or claim with the GitLab setting it feeds and what that mapping controls at sign-in. Read it before you touch the enterprise application, then confirm the exact attribute names and the group mapping key in the current GitLab authentication documentation. The main takeaway is that the group claim must be present in the SAML assertion, or admin, auditor and external roles will not apply.

Entra ID source	GitLab setting or behavior	What it drives in GitLab
User principal name or email (NameID)	NameID value and format in the SAML identity block	Matches the SAML identity to a GitLab account on first sign-in and on later sign-ins; a changed value can create a duplicate account
Email address claim	Email attribute used by GitLab for account matching and notifications	Links an existing local or LDAP account to the SAML identity when the email matches; confirm whether automatic linking is enabled in your version
Username or alias claim	Username attribute mapping	Sets the username GitLab assigns on account creation; confirm the attribute name and whether it can change after creation
Given name and surname claims	Full name attribute mapping	Populates the display name on the user profile; it does not affect authorization
Group claim (group object IDs or names)	Groups attribute in the SAML configuration and the admin, auditor and external group mappings	Grants administrator or auditor status and marks users as external; without this claim in the assertion, role mapping does not apply
Group claim absent or empty	Groups attribute missing from the assertion	Users sign in with default roles, and administrators can lose access if roles were previously granted by group; test with a known admin account first
Entra user assignment and group filters	Access control applied before the SAML response is sent	Only assigned users can sign in; this sits outside GitLab, so confirm assignment rules before rollout

Security settings that protect the Entra ID sign-in path

The Entra ID application is the front door to GitLab, so its assignment rules, certificates, transport and privilege mapping decide who can sign in and what they can do. Each control below narrows that path, and each should be changed one at a time and reviewed before the next.

Restrict assignment to named users and groups

In Entra ID, turn on assignment required for the GitLab enterprise application and assign only the groups that need GitLab access. An overly broad assigned-users list widens the set of accounts that can reach GitLab's sign-in page, including staff who no longer need source control access. After each change to assignments, review the enterprise application's user and group list and compare it with the people who should have a GitLab account.

Plan signing certificate renewal

The SAML signing certificate in the Entra ID application expires, and GitLab rejects sign-ins once the certificate it trusts no longer matches. Record the expiry date, the thumbprint configured in gitlab.rb, and the owner responsible for renewal. Before the date, add the new certificate in Entra ID, update the fingerprint in GitLab, and test a sign-in with a non-administrator account.

Require HTTPS on the external URL

SAML assertions carry identity data and the browser redirects that deliver them depend on the external URL in gitlab.rb being correct. Confirm that the external URL uses https, that the certificate for that hostname is valid and trusted by users' browsers, and that the assertion consumer service URL registered in Entra ID matches it exactly. A mismatch here causes failed sign-ins that often look like identity problems.

Decide on two-factor for SAML accounts

Entra ID may enforce its own multifactor policy, but GitLab can still hold local two-factor settings for accounts that sign in through SAML. Decide whether those accounts must also meet GitLab's two-factor rules, and confirm with your identity team which layer is the authority. Document the decision so administrators do not assume that Entra ID's policy covers every GitLab path, including the local root account.

Limit administrator status to a narrow group

Administrator status in GitLab should come from a small, separately owned Entra ID group rather than from general GitLab access. Map that group to the admin setting in gitlab.rb and keep its membership under change control. Check the current list of GitLab administrators after each change to group claims, because a claim that is missing or misnamed can silently remove or grant elevated access.

Roll out hardening gradually

GitLab's hardening guidance covers application settings, configuration files such as gitlab.rb, and the operating system, and it states that the guidance is a work in progress to be rolled out gradually. Apply SSO controls in a staging instance first, record which settings changed, and confirm sign-in, administrator access and blocked-user behavior before the next change. Treat the hardening guide as a checklist to adapt rather than a one-time script.

Who does what when SAML and SCIM run together

SAML handles authentication at the moment someone signs in. When a user opens GitLab, GitLab redirects them to Entra ID, Entra ID checks the user's current state and credentials, and it returns a signed assertion that GitLab accepts to establish a session. SAML does not hold a standing list of accounts that GitLab maintains, so it answers only whether this person can sign in right now. Group claims in the assertion can also set administrator, auditor or external status, but only when the attribute mapping is configured in gitlab.rb as your environment requires.

Who can sign in: Users assigned to the Entra ID enterprise application and able to pass Entra ID sign-in conditions.
Session establishment: GitLab validates the signed response against the certificate you registered, then creates or links the session.
Attribute mapping: The NameID and email attributes must match what GitLab expects, or sign-in fails or links the wrong account.
Group claims: Admin and external roles depend on the groups attribute being sent. If it is missing, role decisions fall back to defaults you should test.
What SAML does not do: It does not disable a GitLab account when a person leaves unless their Entra ID sign-in is blocked.

Confirm the exact attribute names and claim configuration against the current GitLab SAML documentation before you write the Entra ID mapping.

Common Entra ID SAML failures in GitLab and how to fix them

This table pairs each common Entra ID SAML failure with its likely cause, the first place to look and the fix. Start with the Entra ID sign-in logs for assertion and assignment errors, then the GitLab production log for validation errors on the GitLab side. Most failures trace back to a mismatch between the two configurations, so compare values before changing anything.

Failure	Likely cause	Where to look first	Fix
Certificate fingerprint rejected	Entra ID rotated the SAML signing certificate, but gitlab.rb still holds the old idp_cert_fingerprint, or the fingerprint was copied with the wrong algorithm.	Entra ID sign-in logs show a signature validation error; the GitLab production log shows a SAML response signature failure.	Copy the current SHA-256 thumbprint from the enterprise application's SAML certificate section, update the setting in gitlab.rb, then run a reconfigure.
Identifier or reply URL mismatch	The Identifier (Entity ID) or Reply URL in Entra ID does not exactly match the values GitLab sends, often because of a trailing slash, http instead of https, or a changed external URL.	Entra ID sign-in logs report an AADSTS error about an invalid reply address; the SAML request URL in the browser shows the value GitLab sent.	Set the Identifier and Assertion Consumer Service URL in Entra ID to the exact values in gitlab.rb, matching scheme, host and path character for character.
NameID format mismatch	The claim Entra ID sends as NameID does not match the name_id_format GitLab expects, so GitLab cannot match the account and either creates a duplicate or rejects the user.	The GitLab production log shows a SAML user lookup failure; the user's identities in the GitLab admin area show an unexpected external UID.	Align the NameID format and source attribute in Entra ID with the GitLab identifier setting. Confirm the mapping with a test user before changing existing accounts.
Group claim missing for admin or external status	The groups claim is not included in the token, or the group object IDs in gitlab.rb do not match the IDs Entra ID emits, so admin or external roles are not applied.	Decode a test SAML response in the Entra ID sign-in log details and check the attribute statement for the groups claim.	Add the groups claim in the Entra ID token configuration, then update admin_groups or external_groups in gitlab.rb with the matching object IDs and reconfigure.
Clock skew or expired assertion	The server clock on the GitLab host drifts from Entra ID time, so the assertion's validity window appears expired or not yet valid.	The GitLab production log reports an assertion timing error; compare the host time with a reliable time source.	Confirm NTP or chrony is running on the GitLab nodes, correct the drift, then retry the sign-in with a fresh session.
User not assigned to the enterprise application	The user or their group is not assigned to the Entra ID enterprise application, or assignment required is enabled and the user falls outside it.	Entra ID sign-in logs show a failure with a status indicating the user is not assigned to the application.	Assign the user or a security group to the enterprise application under Users and groups, and confirm the group is the one GitLab uses for access.
gitlab.rb change not applied	The configuration was edited but gitlab-ctl reconfigure was not run, or the reconfigure failed on another node in a multi-node setup, so the running configuration is out of date.	Run gitlab-ctl reconfigure and review its output; check the saved configuration timestamp against the edit time.	Run gitlab-ctl reconfigure on every node that serves GitLab, confirm it completes without errors, and retest sign-in. Keep a change record of each edit.

Questions buyers ask before setting up Entra ID SSO for GitLab

What drives the effort, and can an internal team set up Entra ID SSO alone?

An internal team with Entra ID administration and GitLab administration skills can complete a single-group SAML setup, but the effort rises with the number of groups, the environments involved and how many people must test sign-in. The main drivers are the Entra enterprise application configuration, the mapping of Entra attributes to the settings in gitlab.rb, the group claims used for administrator and external user status, and the pairing with SCIM if you want automated account creation and blocking. Most teams underestimate testing, especially for users who already have local GitLab accounts with the same email address. Ask any partner to break the work into configuration, testing, rollout and handover, and confirm which of those your own staff will carry out.

Does the GitLab license tier change what this integration can do?

Yes, the tier decides which provisioning and group features you can use. The GitLab pricing page lists Premium at 29 US dollars per user per month billed annually for self-managed installations, and Free and Ultimate are also available for self-managed installations. SAML sign-in itself is part of the GitLab Self-Managed authentication options, but SCIM provisioning and group-based features are tied to paid tiers, so confirm exactly which features your chosen tier includes before you design the integration. Ask the quote to state the tier, the number of users and whether the price is billed annually, and ask for the tier comparison that applies to your deployment.

How long does the Entra ID SSO work take?

The duration depends on how many groups must map to GitLab roles, how many GitLab instances or environments need the same setup, and how many identity reviews are required before go-live. A single production instance with one group and a small test pilot is a much smaller task than a multi-environment rollout with administrator, auditor and external user mappings and a change approval step. No fixed duration applies to every organization, so ask for a timeline built from the written scope, with separate milestones for the test environment, pilot users, production cutover and post-cutover checks. Any partner should state which of those milestones depends on your own change calendar.

What does the work need from our team before it starts?

You need someone with Entra ID tenant rights to register an enterprise application, assign users and groups and manage claims, plus a GitLab administrator who can edit gitlab.rb and run reconfigure on the instance. Prepare a test group of users, including at least one person who is not an administrator, so sign-in can be checked against real accounts. Agree a change window for the production cutover, because the reconfigure and the first sign-ins affect every user. Confirm who approves the group names, the attribute names and the certificate handling before work begins, since these are hard to change later without another review.

What happens when the Entra ID signing certificate renews?

Entra ID signing certificates have an expiry date, and when the certificate changes, the fingerprint or certificate value that GitLab trusts must change with it. If the new value is not applied before the old certificate expires, users will fail to sign in with SAML. Plan a renewal date, record the certificate thumbprint in your change log and check how your team receives expiry warnings. The renewal steps should be tested in a non-production environment before they are applied in production, and the person who performs them should know where the setting lives in gitlab.rb. Ask any partner to document this renewal procedure as part of the handover.

Does DeployOpen issue an audit report or attestation for the Entra ID integration?

No. DeployOpen does not issue audit reports, attestations or certifications. For an integration like this, DeployOpen can plan and configure the identity settings, document the configuration, collect the evidence that the controls operate and prepare your systems for a compliance assessment. Independent auditors and certification bodies perform the assessment and issue any report. If your compliance program needs a particular assessment, ask your auditor which evidence they expect for SSO, provisioning and access reviews before the work is scoped, so the handover includes the records they will request.

Should we set up SCIM at the same time as SAML?

Many teams configure SAML first to prove sign-in works, then add SCIM so that Entra ID can create, update and block GitLab accounts. Doing both in one change is possible, but it makes troubleshooting harder when a sign-in or provisioning problem appears. Decide early whether deprovisioned users must keep their SAML identity for reactivation, because that choice affects how you test blocking and restoring accounts. Ask for the sequence and the test cases for each stage in the written scope so that you can confirm the work before it reaches production users.

How DeployOpen works on this

DeployOpen, a Chainscore Labs company, plans, implements, hardens and documents self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For GitLab SAML SSO with Microsoft Entra ID, we work from a written scope that covers the Entra app registration, the gitlab.rb settings, group claim behavior and the SCIM pairing before any configuration begins.

How we scope

Confirm your GitLab edition and tier, since SAML group sync and SCIM depend on the features your tier includes.
Map Entra ID user attributes, NameID format and group claims to the GitLab settings each one feeds.
Agree which Entra groups grant administrator, auditor or external status, and who approves those mappings.
Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts.

How we build

Create and configure the Entra enterprise application in a test tenant or staging environment first.
Set certificate handling, including the thumbprint and rotation process, and record where each value is stored.
Apply and validate the gitlab.rb changes on a non-production instance before any production change.
Test sign-in with a defined set of accounts covering regular, administrator and external users.

How we hand over

Deliver a runbook covering the Entra settings, gitlab.rb keys, group mappings and rollback steps.
Document certificate expiry dates, owners and the procedure for replacing the signing certificate.
Walk your identity and GitLab administrators through sign-in, group changes and troubleshooting.
Provide a test record showing each scenario checked and the result, for your own audit file.

How we support

Ongoing support, upgrades and continuous testing are available as retainers after handover.
Review SSO configuration when you upgrade GitLab, since required upgrade stops can affect integrations.
Coordinate SSO changes with your Entra ID and GitLab owners through a named change process.
Ask any partner for written confirmation of which Entra and GitLab behaviors they have tested in your environment.