GitLab SAML SSO with Okta

How GitLab SAML SSO with Okta works for self-managed instances

If your identity team wants Okta to control who can sign in to a self-managed GitLab instance, the integration has four parts: a SAML app in Okta, the SAML settings in GitLab, group rules that decide who may sign in, and optional SCIM provisioning for account lifecycle. GitLab Self-Managed supports SAML according to the GitLab authentication documentation, so Okta acts as the identity provider and GitLab trusts the assertions it issues. The sign-in flow is the part to design first: a user authenticates in Okta, Okta posts a signed SAML response to GitLab, and GitLab matches that identity to a local account. Each step is a place where a misconfigured attribute or certificate can block access, so the team should map the flow on paper before touching either console.

This page helps you make the decisions that are specific to Okta: which Okta groups are allowed to reach the GitLab app, which SAML attribute carries group membership, and whether administrator and auditor status will come from Okta groups or stay managed inside GitLab. It also covers when SCIM is worth the added work, since SCIM handles account creation and deprovisioning while SAML handles sign-in. The group assignment on the Okta app is the main access control, so decide it before users are assigned. Confirm in the GitLab documentation which settings belong in gitlab.rb and which can be changed in the admin area, because a change in the wrong place can be overwritten at the next reconfigure.

Some decisions stay with your own security policy and are not settled by the integration itself. These include session lifetime, whether SAML sign-in is enforced for all users or only for some groups, how long a departed employee keeps access after Okta deactivates them, whether a local break-glass administrator account exists, and how multi-factor authentication is enforced in Okta compared with GitLab. Ask your security and compliance owners to set those rules first, then use the rest of this page to implement them. Where your environment has network restrictions or a private Okta tenant, confirm each endpoint and certificate path with Okta and your GitLab administrators before rollout.

What you need before configuring Okta and GitLab

Most SAML failures trace back to decisions made before anyone opens the Okta admin console. Confirm the GitLab version, the external URL, the server access, the Okta roles and a working local administrator first, then configure both sides against that baseline.

GitLab version and upgrade path

Record the exact GitLab version running today and the version you plan to reach. GitLab requires upgrades to pass through required upgrade stops, so a jump across one can block the work before SSO is touched. Check the upgrade paths documentation for the stops between your current and target version. Confirm the SAML and SCIM settings you need exist in the release you will run, and plan the upgrade as its own change window.

Tier matched to the feature set

Do not assume the tier. SAML group-based roles, SCIM and several admin controls sit in paid tiers, so list the features your rollout needs and compare them against the GitLab pricing page for self-managed installations. Ask whether the features you need are included in Premium or only in Ultimate, and confirm the answer in writing before you build the Okta design around it.

Stable HTTPS external URL

The SAML assertion consumer service URL and the audience values are built from the external URL in your configuration. Pick the hostname that users will type, issue a valid certificate for it, and make sure it resolves inside the network path users actually use. Changing the hostname later means updating the Okta app and the GitLab settings together, so settle it before the first test sign-in.

Administrative access to gitlab.rb

SAML settings, group role mappings and the admin and auditor group names live in the Omnibus configuration file, /etc/gitlab/gitlab.rb, and take effect after gitlab-ctl reconfigure. Confirm that a named engineer can edit that file and run the reconfigure command on every node that serves sign-in. Keep the file under version control with restricted access, because a typo in it can stop GitLab from starting cleanly.

Okta role for app and group work

Creating the SAML app, assigning groups and configuring SCIM requires an Okta administrator role that can manage applications and groups. Confirm who holds that role, whether a change requires a second approver under your own process, and whether the same people can also edit the GitLab configuration. Separating those duties makes changes easier to audit and makes a sign-in outage easier to diagnose.

Tested break-glass administrator

Before enforcing SSO, keep at least one local GitLab administrator account with a strong password and a hardware or software second factor that sits outside Okta. Sign in with it once to prove it works, and record where its credentials are stored. If the Okta app is misconfigured, this account is the only way back in without a database edit, so test it before the first SAML change.

Certificate expiry and time sync

SAML signing certificates expire, and assertions carry timestamps that must line up with the clocks on your GitLab servers and Okta. Confirm that every GitLab node synchronizes time with a trusted source, record the certificate expiry date in your renewal calendar, and decide who receives the Okta notification before a certificate rotates. Clock drift and an expired certificate both appear to users as a generic sign-in failure.

Configuring the Okta app and GitLab in the right order

This sequence connects Okta and self-managed GitLab in an order that avoids the most common sign-in failures. Okta is configured first so its certificate, SSO URL and assertion settings exist before GitLab trusts them, and GitLab is reconfigured only after those values are in place. The sequence ends with a sign-in test from an ordinary user, which shows that the Okta assignment and the SAML trust work together.

Create the SAML app in Okta
In the Okta admin console, create a new SAML 2.0 app integration and enter the settings that the GitLab authentication documentation lists for a SAML provider, including the application name and the name ID format the documentation specifies. Leave the certificate download for a later step, because it comes from the saved app. This step is done when the app appears in your application list with its sign-on settings saved and no validation errors. If Okta's labels differ from the documentation, confirm the current wording with the documentation before you substitute a value.
Set the callback URL and audience
Enter the assertion consumer service URL for your GitLab instance. It is the external URL set in gitlab.rb followed by the SAML callback path the documentation names. Set the audience URI to the value GitLab expects for the SAML issuer. Both values must match your external URL exactly, including the https scheme and any trailing slash behavior, because a mismatch causes the assertion to fail. Check: reopen the app's SAML settings after saving and confirm the stored callback URL and audience match the documented values for your external URL. A mismatch typically appears as an error page after Okta sign-in, with no clear message.
Assign the restriction group
Choose or create the Okta group whose members should be allowed to sign in to GitLab, then assign that group to the GitLab app under the app's assignments. Assign only that group so sign-in is limited to its members, and leave admin and auditor roles for a later configuration pass. Add one test user who belongs to the group. Check: the test user's Okta dashboard shows the GitLab tile, and a user outside the group does not see the tile when signed in to the same dashboard.
Copy the certificate and SSO URL
From the app's sign-on settings, download the identity provider signing certificate and copy the identity provider single sign-on URL. Store the certificate in the same controlled location where you keep gitlab.rb changes, since GitLab uses it to verify every assertion Okta issues. Okta certificates have an expiry date, so record it for renewal planning. Check: open the certificate in a viewer and confirm it is a complete, readable certificate with the expected expiry date, and confirm the SSO URL uses your Okta domain.
Add the SAML block to gitlab.rb
On the GitLab server, open gitlab.rb and add or update the SAML provider block with the SSO URL and certificate values from the previous step. Keep the issuer and name identifier settings exactly as the authentication documentation lists them, and use the key names from that documentation, since GitLab will not read a renamed key. Preserve the file's existing ownership and permissions. Check: read the block back against the documentation and confirm the certificate text was not altered by line wrapping or copy and paste.
Run reconfigure and confirm the change
Run sudo gitlab-ctl reconfigure on the instance so GitLab applies the gitlab.rb changes, and restart services if the output asks for it. Watch the output for errors in the authentication sections, which usually indicate a malformed value or a missing key. Check: the reconfigure run finishes without errors, and the GitLab sign-in page shows an option for the Okta provider. If the option is missing, review the reconfigure output and the application logs for the provider name before changing any other setting.
Test sign-in with a non-administrator account
Sign out of any active GitLab session, then sign in through the Okta option using the test user from the assignment step. Use an account that is not a GitLab administrator, so a failure cannot be hidden by existing admin access. Confirm the user lands in GitLab with the expected identity. For a deeper check, use a SAML tracer browser extension to inspect the response from Okta and confirm the name ID and attributes match what GitLab expects. Check: sign-in completes for the assigned user, and a user outside the restriction group is stopped at Okta. Record the results in your change record before testing administrator access.

Mapping Okta attributes and groups to GitLab identity fields

This table maps each Okta value that GitLab reads during SAML sign-in to the GitLab field it fills, what happens when the value is empty, and who should confirm it. Attribute and configuration key names can change between GitLab releases, so check each one against the current GitLab SAML documentation before you copy it into gitlab.rb. The main takeaway is that the NameID and email values decide how accounts are matched, so test them with one user before you assign the full group.

GitLab field	Okta source	If the value is missing	Who confirms
NameID	Name ID format and value set in the Okta SAML app, usually the user's email or Okta username	GitLab cannot reliably link the Okta identity to a GitLab account, and sign-in may fail or match the wrong user	Okta administrator and GitLab administrator, using a test account
Email attribute	User profile email, mapped in the app's attribute statements	Account creation or matching fails, and existing accounts may not link to the SAML identity	GitLab administrator, after a test sign-in
Username attribute	Okta login or a custom profile field mapped to the GitLab username	GitLab may derive a username from the email address, which can collide with existing accounts	GitLab administrator, by checking the created account
Name attributes (first and last name)	firstName and lastName from the Okta user profile	The account may show a blank or partial display name, though confirm whether sign-in is still allowed	Okta administrator and GitLab administrator
Groups attribute statement	Okta group filter added to the app's SAML attribute statements under a named attribute	Admin, auditor and external group logic has no input, so role assignments silently fail to apply	Okta administrator, using the SAML tracer output
Admin groups setting (admin_groups in gitlab.rb)	The Okta group whose members should become GitLab administrators, passed through the groups attribute	No SAML user receives administrator rights from this path, so admin access stays with existing accounts	GitLab administrator, after reconfigure and a test sign-in
Auditor groups setting (auditor_groups in gitlab.rb)	The Okta group whose members should receive auditor access, passed through the groups attribute	No SAML user is granted auditor status, so audit access must come from another route	GitLab administrator and the compliance owner

Choosing groups for sign-in, administrators and auditors

The first decision is which Okta users may reach the GitLab sign-in page at all. Okta's app assignment is the first gate, and any group filter you configure on the GitLab side should match it, so that a user removed in Okta cannot start a new session. Treat the sign-in group as the list of people you would accept as employees or contractors with a documented reason to reach your source code.

Assignment scope: Assigning the app to a broad group such as Everyone lets any Okta user with a login attempt a GitLab account, which is rarely what a regulated team intends.
Contractors and partners: Decide whether they belong in the same group or a separate one, and confirm how their access ends when their engagement does.
Nested groups: Confirm whether group claims include only direct membership or nested membership, because this changes who a filter actually matches.
Session behavior: Confirm with the vendor and your own testing how long existing GitLab sessions survive after a user is removed from the group.
Assertion contents: A group filter has nothing to match unless the group attribute is included in the SAML assertion, so test with a known user before relying on it.

Before enabling the mapping, confirm with your security team which populations may hold a GitLab account, the maximum acceptable session lifetime after removal and who approves changes to the sign-in group.

How to test sign-in before users depend on it

Write the test matrix before you change anything in GitLab or Okta. A fixed list of cases, each with an expected result and an owner, is what separates a controlled cutover from an outage. Decide the acceptance criteria before the first login, while nobody is under pressure to call a half-working setup good enough. For each case, record who runs it, the account used, the expected outcome and where the evidence is kept, such as a screenshot or the GitLab audit event. Agree in advance what counts as a pass for every row, and what stops the cutover if one fails.

Start with a pilot group of named users, assigned to the Okta application through a dedicated group and tested while local sign-in stays enabled for everyone else. Include at least one user who should be an administrator, one who should be an auditor if you use that role, and one ordinary developer. Then test the negative case: a user who is active in Okta but outside the assigned groups must be refused at the GitLab sign-in page. Confirm that refusal in the Okta system log as well as in GitLab. Also check that a user who is removed from the group loses access on their next sign-in, because that behavior depends on the group assignment you configured, not on GitLab alone.

Verify role attributes by reading the resulting account, not the Okta configuration screen. Check the administrator, auditor and external flags on each pilot account in the GitLab Admin Area after a fresh sign-in, and confirm that a missing groups attribute leaves those flags unchanged or unset as your configuration intends. Keep the local administrator account working throughout, and test that it can sign in with its password and two-factor method before the cutover begins. Document the rollback path as specific steps: which setting is reverted in gitlab.rb, how GitLab is reconfigured, who authorizes the change and who tells users. Confirm the exact steps against the GitLab authentication and authorization documentation and your own environment before you rely on them.

Security settings to decide before users sign in with Okta

Most of the risk in a GitLab SAML rollout sits in a handful of settings: how administrators get in when the identity provider is down, who is allowed to sign in at all, and how long a session lives. These cards cover the decisions to make before the first user signs in, and each one should be recorded and reviewed under your own change process.

Keep a local break-glass administrator

Before you enforce SAML, keep at least one local GitLab administrator account with a strong, stored password and a hardware-backed second factor that is not tied to Okta. If Okta has an outage, a misconfigured certificate or a bad attribute mapping, this account is the only route back into the instance to fix SAML settings. Test that it signs in, then store its credentials under your privileged access controls and review them on a schedule. Do not disable password sign-in until this account is verified.

Restrict sign-in to assigned groups

Okta can assign an app to everyone in a directory unless you limit it, so decide which Okta groups may reach the GitLab application and enforce that assignment in Okta. Check that the group attribute GitLab receives matches what you expect, and confirm how users outside those groups are handled in your GitLab configuration. Treat the assignment list as an access control with an owner, not a default that someone can widen later.

Plan signed assertions and certificate rotation

Decide whether Okta signs assertions, the signing algorithm you accept, and who owns the signing certificate's expiry date. Store the certificate fingerprint and expiry in your change calendar, because an expired or replaced certificate will stop sign-in for every user at once. Confirm the current options and the fingerprint format against the GitLab SAML documentation for your installed version before you change them.

Align session lifetime with Okta policy

GitLab keeps its own session, so an Okta session timeout does not end a GitLab session by itself. Agree the session length, re-authentication rules and sign-out behavior with your identity team, then set GitLab's values to match your policy. Also decide how Okta sign-out and deprovisioning affect active GitLab sessions, and test both paths with a non-production user before rollout.

Put gitlab.rb under change control

Many SAML settings live in the Omnibus configuration file, so every change to the identity provider, certificate or group mapping should go through the same review and version control as other infrastructure code. Record who changed which key, when, and why, and run a reconfigure followed by a sign-in test in a non-production instance first. Changes that look small, such as a certificate update, have caused lockouts when made directly on the server.

Roll out hardening gradually

The GitLab hardening guidance covers application settings, the operating system and configuration files, and the documentation describes it as a work in progress to be rolled out gradually. Pick the settings that affect sign-in and session security first, apply them in a staged way, and log each one with its owner. Your own security policies decide the final values, so review each setting against them rather than copying defaults from a guide.

Why GitLab SAML sign-in fails and how to fix it

This table lists the sign-in failures most often seen when Okta SAML is connected to self-managed GitLab, with the likely cause, the check to run and the fix for each. Work through the symptom column against the GitLab production log and the Okta System Log for each case before changing settings, because exact error text varies by GitLab version and configuration. Treat the first match in your logs as the diagnosis, not the first guess.

Symptom	Likely cause	Check	Fix
Okta reports an error after sign-in and GitLab shows no session	External URL in gitlab.rb does not match the Single sign-on URL or Audience URI configured in the Okta app	Compare the external_url value with the URLs in the Okta app, and confirm the GitLab log entry for the rejected SAML response	Align external_url, the assertion consumer service URL and the audience value exactly, then run a reconfigure and retest
GitLab rejects the login with a NameID or user matching error	NameID format in Okta does not match the nameid_format set in GitLab, or the NameID value is not the expected user identifier	Inspect the SAML response in the Okta System Log and compare the NameID format and value with the GitLab SAML settings	Set the NameID format and source attribute in Okta to match the GitLab configuration, then ask affected users to sign in again
Sign-in suddenly fails for every user after a period of normal operation	Okta signing certificate expired or was rotated, and the new certificate was not copied into gitlab.rb	Check the certificate expiry date in the Okta app and the idp_cert_fingerprint or certificate value in gitlab.rb	Copy the current certificate or fingerprint into gitlab.rb, run gitlab-ctl reconfigure, and set a calendar reminder before the next expiry
Users sign in to Okta but lose administrator or auditor access	The groups attribute is missing from the SAML assertion, so GitLab cannot map admin or auditor roles	Confirm the groups attribute statement in the Okta app and review the assertion in the Okta System Log for the user	Add the groups attribute statement with a filter that matches the admin and auditor groups, and confirm the groups attribute name matches the gitlab.rb setting
Okta user is refused access even though the password and MFA succeed	The user is not a member of the Okta group assigned to the GitLab app, so Okta or GitLab restricts sign-in	Check the user's group membership and the app assignment in Okta, then review the denial in the Okta System Log	Assign the user to the restriction group or the app, or confirm that the restriction group in the GitLab configuration is the intended one
Changes to gitlab.rb have no effect on sign-in behavior	The configuration was edited but gitlab-ctl reconfigure was not run, or it failed partway through	Run gitlab-ctl reconfigure and review its output for errors, then check the GitLab configuration file timestamp	Run gitlab-ctl reconfigure, resolve any reported errors, restart if the output recommends it, and retest with a test account
Login loops back to the Okta page without an error	Clock skew between servers, or a relay state or redirect URL that does not match the instance	Check system time on the GitLab host against a trusted time source and review the SAML response timestamps in the logs	Correct NTP configuration on the GitLab host, confirm the instance URL is consistent, then retest

Questions teams ask before setting up Okta SSO for GitLab

Can our own team set up Okta SAML for self-managed GitLab without a partner?

Yes, a team with administrator access to both Okta and the GitLab server can configure SAML sign-in using the app settings GitLab documents, provided someone owns the work end to end. The configuration itself is short: an Okta SAML app, the assertion consumer service URL and audience values, a certificate, and matching settings in the GitLab configuration file. The harder part is the decisions around it, such as which Okta groups may sign in, how roles map to groups, and how the change is tested and rolled back. Teams that have not run an identity change on a production GitLab instance often find that testing and the cutover plan take more time than the configuration.

What drives the effort of an Okta SSO setup for GitLab?

The main drivers are how many groups you need, how many roles you map from identity attributes, and whether SCIM provisioning is included. Each group that controls sign-in, administrator status, auditor status or external status adds a design decision and a test case. Scale matters less for the SAML configuration itself than for the user base you must migrate and verify. Other factors include how many GitLab instances or groups are involved, whether you run a single node or a multi-node installation, and whether you already use Okta for other applications with a standard naming scheme. Ask any provider to break the quote into design, configuration, testing and handover so you can see which drivers apply to your environment.

What do we need from our Okta and GitLab administrators?

You need an Okta administrator who can create and assign a SAML application, define group membership and attribute statements, and, if SCIM is in scope, configure provisioning. On the GitLab side, you need someone who can edit the server configuration, run reconfigure and restart services, and review sign-in logs. Both sides should agree on a named owner for the certificate, the group names and the rollback steps. Security or compliance staff should review the attribute and group design before go-live. Plan a test group of accounts that can sign in without affecting the rest of the organization, and confirm with your change board how the change will be recorded.

How long does an Okta SSO setup take, and what can change the timeline?

The duration depends on your environment and your approval process, so confirm it against your own change calendar rather than a generic figure. Typical timing is driven by approvals for identity and production changes, the number of groups and roles to agree, availability of a maintenance window, testing with real users, and whether a separate staging GitLab instance exists. Delays often come from waiting for group ownership decisions in Okta or security review of the certificate and attribute handling. Ask any provider for a written schedule tied to milestones and dependencies, and make sure your own approvals are on that schedule.

Do we need SCIM provisioning if SAML sign-in already works?

SAML handles sign-in, but it does not by itself create or deactivate GitLab accounts in advance, so SCIM is the piece that automates account lifecycle. Without SCIM, someone must still be created or blocked on the GitLab side when people join, change roles or leave. Whether you need SCIM depends on your joiner, mover and leaver process, how many accounts change each quarter, and your audit expectations for timely removal of access. SCIM also brings its own design work, including group sync rules and how deprovisioned users are handled. Confirm the exact SCIM behavior for your GitLab edition and tier in the vendor documentation before you commit to it.

What changes after go-live, such as upgrades and certificate renewal?

After go-live, the SAML certificate, the Okta app settings and the GitLab configuration must be kept in step, and any GitLab upgrade should be checked against sign-in before users rely on it. Certificates expire, so record the expiry date, the owner and the renewal steps, and test the new certificate in staging first. Upgrades follow GitLab's required upgrade stops, so plan a sign-in check after each one. Group names in Okta are often renamed over time, which can silently remove access, so changes should go through the same review as the original design. Operations staff should also know where sign-in failures appear in logs and who responds to them.

Does DeployOpen handle the Okta and GitLab work for us?

DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, so the GitLab side of an Okta SSO setup can be part of a written, fixed-scope engagement. Scope, deliverables and timelines are agreed in writing before work starts, and a quote follows from that scope. The work you would expect to see in scope includes group and role design, configuration, testing, handover and documentation. Ongoing support, upgrades and testing are available as retainers. Your Okta administrators still own the Okta tenant, and DeployOpen does not issue audit reports or certifications, which remain the job of independent auditors.

How DeployOpen works on this

DeployOpen scopes, builds, tests and hands over Okta SAML sign-in for self-managed GitLab inside your own infrastructure. The work covers the Okta app, the gitlab.rb settings, group-based sign-in restrictions, role attributes and SCIM provisioning, documented so your team can run it after handover.

How we scope

Written scope listing the GitLab instance, Okta org, groups and roles that sign-in must cover
Agreed list of Okta groups allowed to sign in and who approves each one
Decision on whether SCIM provisioning is in scope, with the GitLab tier required confirmed in writing
Engagements are fixed-scope, with deliverables and timelines agreed before work starts

How we build

Okta SAML app configured to the settings GitLab documents, with the certificate and sign-in URL recorded
gitlab.rb changes applied in a staging instance first, then promoted to production after review
Admin and auditor role attributes mapped and tested with named test accounts from each group
Sign-in tested with allowed and disallowed Okta users, including a deprovisioned account

How we hand over

Configuration record covering Okta app settings, GitLab keys, group mappings and certificate renewal dates
Runbook for adding a group, rotating the SAML certificate and recovering from a failed sign-in
Test evidence showing which groups can sign in and which roles they receive
Knowledge transfer session with the administrators who will own the configuration

How we support

Ongoing support and upgrade work for the SSO configuration available as a retainer
Review of SSO settings whenever GitLab moves to a new release on the upgrade path
Re-testing of sign-in and role mapping after Okta tenant or group changes
Retainer scope agreed in writing, with the frequency of reviews set in that agreement