- Glossary of common terms
- General Setup
- SAML Groups
- Group Sync
- Bypass two factor authentication
- Customization
- Response signature validation (required)
- Assertion Encryption (optional)
- Request signing (optional)
- Security
- Passwords for users created via SAML
- Link SAML identity for an existing user
- Configuring Group SAML on a self-managed GitLab instance
- Providers
-
Troubleshooting
- SAML Response
- GitLab+SAML Testing Environments
- 500 error after login
- 422 error after login
- Redirect back to the login screen with no evident error
- Invalid audience
- Missing claims, or
Email can't be blank
errors - Key validation error, Digest mismatch or Fingerprint mismatch
- User is blocked when signing in through SAML
- Google workspace troubleshooting tips
SAML OmniAuth Provider
This page describes instance-wide SAML for self-managed GitLab instances. For SAML on GitLab.com, see SAML SSO for GitLab.com groups.
You should also reference the OmniAuth documentation for general settings that apply to all OmniAuth providers.
Glossary of common terms
Term | Description |
---|---|
Identity provider (IdP) | The service which manages your user identities, such as Okta or OneLogin. |
Service provider (SP) | GitLab can be configured as a SAML 2.0 SP. |
Assertion | A piece of information about a user’s identity, such as their name or role. Also known as claims or attributes. |
Single Sign-On (SSO) | Name of authentication scheme. |
Assertion consumer service URL | The callback on GitLab where users are redirected after successfully authenticating with the identity provider. |
Issuer | How GitLab identifies itself to the identity provider. Also known as a “Relying party trust identifier”. |
Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. |
General Setup
GitLab can be configured to act as a SAML 2.0 Service Provider (SP). This allows GitLab to consume assertions from a SAML 2.0 Identity Provider (IdP), such as Okta to authenticate users.
First configure SAML 2.0 support in GitLab, then register the GitLab application in your SAML IdP:
-
Make sure GitLab is configured with HTTPS. See Using HTTPS for instructions.
-
On your GitLab server, open the configuration file.
For Omnibus package:
sudo editor /etc/gitlab/gitlab.rb
For installations from source:
cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml
- See Configure initial settings for initial settings.
-
To allow your users to use SAML to sign up without having to manually create an account first, add the following values to your configuration:
For Omnibus package:
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml'] gitlab_rails['omniauth_block_auto_created_users'] = false
For installations from source:
omniauth: enabled: true allow_single_sign_on: ["saml"] block_auto_created_users: false
-
You can also automatically link SAML users with existing GitLab users if their email addresses match by adding the following setting:
For Omnibus package:
gitlab_rails['omniauth_auto_link_saml_user'] = true
For installations from source:
auto_link_saml_user: true
-
Ensure that the SAML
NameID
and email address are fixed for each user, as described in the section on Security. Otherwise, your users are able to sign in as other authorized users. -
Add the provider configuration:
For Omnibus package:
gitlab_rails['omniauth_providers'] = [ { name: "saml", label: "Provider name", # optional label for login button, defaults to "Saml" args: { assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback", idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8", idp_sso_target_url: "https://login.example.com/idp", issuer: "https://gitlab.example.com", name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" } } ]
For installations from source:
omniauth: providers: - { name: 'saml', label: 'Provider name', # optional label for login button, defaults to "Saml" args: { assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback', idp_cert_fingerprint: '43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8', idp_sso_target_url: 'https://login.example.com/idp', issuer: 'https://gitlab.example.com', name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent' } }
-
Change the value for
assertion_consumer_service_url
to match the HTTPS endpoint of GitLab (appendusers/auth/saml/callback
to the HTTPS URL of your GitLab installation to generate the correct value). -
Change the values of
idp_cert_fingerprint
,idp_sso_target_url
,name_identifier_format
to match your IdP. If a fingerprint is used it must be a SHA1 fingerprint; check the OmniAuth SAML documentation for more details on these options. See the notes on configuring your identity provider for more information. -
Change the value of
issuer
to a unique name, which identifies the application to the IdP. -
For the changes to take effect, you must reconfigure GitLab if you installed via Omnibus or restart GitLab if you installed from source.
- Register the GitLab SP in your SAML 2.0 IdP, using the application name specified
in
issuer
.
To ease configuration, most IdP accept a metadata URL for the application to provide
configuration information to the IdP. To build the metadata URL for GitLab, append
users/auth/saml/metadata
to the HTTPS URL of your GitLab installation, for instance:
https://gitlab.example.com/users/auth/saml/metadata
At a minimum the IdP must provide a claim containing the user’s email address using email
or mail
.
See the assertions list for other available claims.
On the sign in page there should now be a SAML button below the regular sign in form. Select the icon to begin the authentication process. If everything goes well the user is returned to GitLab and signed in.
Use multiple SAML identity providers
Introduced in GitLab 14.6.
You can configure GitLab to use multiple SAML identity providers if:
- Each provider has a unique name set that matches a name set in
args
. - The providers’ names are:
- Used in OmniAuth configuration for properties based on the provider name. For example,
allowBypassTwoFactor
,allowSingleSignOn
, andsyncProfileFromProvider
. - Used for association to each existing user as an additional identity.
- Used in OmniAuth configuration for properties based on the provider name. For example,
- The
assertion_consumer_service_url
matches the provider name. - The
strategy_class
is explicitly set because it cannot be inferred from provider name.
Example multiple providers configuration for Omnibus GitLab:
gitlab_rails['omniauth_providers'] = [
{
name: 'saml_1',
args: {
name: 'saml_1', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
},
{
name: 'saml_2',
args: {
name: 'saml_2', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
}
]
Example providers configuration for installations from source:
omniauth:
providers:
- {
name: 'saml_1',
args: {
name: 'saml_1', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_1/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 1' # Differentiate the two buttons and providers in the UI
}
- {
name: 'saml_2',
args: {
name: 'saml_2', # This is mandatory and must match the provider name
strategy_class: 'OmniAuth::Strategies::SAML',
assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml_2/callback', # URL must match the name of the provider
... # Put here all the required arguments similar to a single provider
},
label: 'Provider 2' # Differentiate the two buttons and providers in the UI
}