doc/user/group/saml_sso/_index.md
{{< details >}}
{{< /details >}}
[!note] For GitLab Self-Managed, see SAML SSO for GitLab Self-Managed.
Users can sign in to GitLab through their SAML identity provider.
SCIM synchronizes users with the group on GitLab.com.
You can configure SAML SSO for the top-level group only.
The SAML standard means that you can use a wide range of identity providers with GitLab. Your identity provider might have relevant documentation. It can be generic SAML documentation or specifically targeted for GitLab.
When setting up your identity provider, use the following provider-specific documentation to help avoid common issues and as a guide for terminology used.
For identity providers not listed, you can refer to the instance SAML notes on configuring an identity provider for additional guidance on information your provider may require.
GitLab provides the following information for guidance only. If you have any questions on configuring the SAML app, contact your provider's support.
If you are having issues setting up your identity provider, see the troubleshooting documentation.
To set up SSO with Azure as your identity provider:
In the top bar, select Search or go to and find your group.
Select Settings > SAML SSO.
Note the information on this page.
Go to Azure, create a non-gallery application, and configure SSO for an application. The following GitLab settings correspond to the Azure fields.
| GitLab setting | Azure field |
|---|---|
| Identifier | Identifier (Entity ID) |
| Assertion consumer service URL | Reply URL (Assertion Consumer Service URL) |
| GitLab single sign-on URL | Sign on URL |
| Identity provider single sign-on URL | Login URL |
| Certificate fingerprint | Thumbprint |
You should set the following attributes:
user.objectID.
persistent. For more information, see how to manage user SAML identity.Make sure the identity provider is set to have provider-initiated calls to link existing GitLab accounts.
Optional. If you use Group Sync, customize the name of the group claim to match the required attribute.
<i class="fa-youtube-play" aria-hidden="true"></i>
View a demo of SCIM provisioning on Azure using SAML SSO for groups. The objectID mapping is outdated in this video. Follow the SCIM documentation instead.
For more information, see the Azure configuration example.
To set up Google Workspace as your identity provider:
In the top bar, select Search or go to and find your group.
Select Settings > SAML SSO.
Note the information on this page.
Follow the instructions for setting up SSO with Google as your identity provider. The following GitLab settings correspond to the Google Workspace fields.
| GitLab setting | Google Workspace field |
|---|---|
| Identifier | Entity ID |
| Assertion consumer service URL | ACS URL |
| GitLab single sign-on URL | Start URL |
| Identity provider single sign-on URL | SSO URL |
Google Workspace displays a SHA256 fingerprint when you retrieve the certificate. If you need to generate the SHA256 fingerprint later, see calculate the fingerprint.
Set these values:
email.first_name.last_name.EMAIL.Basic Information > Primary email.
For more information, see supported attributes.Make sure the identity provider is set to have provider-initiated calls to link existing GitLab accounts.
On the GitLab SAML SSO page, when you select Verify SAML Configuration, disregard
the warning that recommends setting the NameID format to persistent.
For more information, see the Google Workspace configuration example.
<i class="fa-youtube-play" aria-hidden="true"></i> View a demo of how to configure SAML with Google Workspaces and set up Group Sync.
To set up SSO with Okta as your identity provider:
In the top bar, select Search or go to and find your group.
Select Settings > SAML SSO.
Note the information on this page.
Follow the instructions for setting up a SAML application in Okta.
The following GitLab settings correspond to the Okta fields.
| GitLab setting | Okta field |
|---|---|
| Identifier | Audience URI |
| Assertion consumer service URL | Single sign-on URL |
| GitLab single sign-on URL | Login page URL (under Application Login Page settings) |
| Identity provider single sign-on URL | Identity Provider Single Sign-On URL |
Under the Okta Single sign-on URL field, select the Use this for Recipient URL and Destination URL checkbox.
Set these values:
user.getInternalProperty("id").Persistent. For more information, see manage user SAML identity.user.email or similar.Make sure the identity provider is set to have provider-initiated calls to link existing GitLab accounts.
The Okta GitLab application available in the App Catalog only supports SCIM. Support for SAML is proposed in issue 216173.
<i class="fa-youtube-play" aria-hidden="true"></i> For a demo of the Okta SAML setup including SCIM, see Demo: Okta Group SAML & SCIM setup.
For more information, see the Okta configuration example.
OneLogin supports its own GitLab.com application.
To set up OneLogin as your identity provider:
In the top bar, select Search or go to and find your group.
Select Settings > SAML SSO.
Note the information on this page.
If you use the OneLogin generic SAML Test Connector (Advanced), you should use the OneLogin SAML Test Connector. The following GitLab settings correspond to the OneLogin fields:
| GitLab setting | OneLogin field |
|---|---|
| Identifier | Audience |
| Assertion consumer service URL | Recipient |
| Assertion consumer service URL | ACS (Consumer) URL |
| Assertion consumer service URL (escaped version) | ACS (Consumer) URL Validator |
| GitLab single sign-on URL | Login URL |
| Identity provider single sign-on URL | SAML 2.0 Endpoint |
For NameID, use OneLogin ID. For more information, see manage user SAML identity.
Configure required and supported attributes.
Make sure the identity provider is set to have provider-initiated calls to link existing GitLab accounts.
For more information, see the OneLogin configuration example.
To set up Keycloak as your identity provider:
The following GitLab settings correspond to the Keycloak fields.
| GitLab setting | Keycloak field |
|---|---|
| Identifier | Client ID |
| Assertion consumer service URL | Valid redirect URIs |
| Assertion consumer service URL | Assertion Consumer Service POST Binding URL |
| GitLab single sign-on URL | Home URL |
persistent.https://gitlab.com/groups/your-group-name-dedicated.email.idp-metadata.xml.<md:SingleSignOnService> tag.Location attribute.<ds:X509Certificate> tag.-----BEGIN CERTIFICATE----- at the beginning of the file and -----END CERTIFICATE----- at the end of the file as new lines.[!note] AWS IAM Identity Center (formerly AWS Single Sign-On) is not a GitLab-tested identity provider. GitLab provides the following information based on customer-reported configurations. If you have questions about configuring the SAML integration in AWS IAM Identity Center, contact AWS Support.
AWS IAM Identity Center defaults to IdP-initiated login. To link your existing GitLab account, you must configure SP-initiated login. For more information, see SP-initiated login.
To set up SSO with AWS IAM Identity Center as your identity provider:
On the top bar, select Search or go to and find your group.
Select Settings > SAML SSO, and note the values on this page.
In the AWS IAM Identity Center console, set up a custom SAML 2.0 application. When prompted for metadata values, enter the following:
| GitLab setting | AWS IAM Identity Center field |
|---|---|
| Assertion consumer service URL | Application ACS URL |
| Identifier | Application SAML audience |
To enable SP-initiated sign-in, set the Application start URL to your GitLab single sign-on URL (on the GitLab SAML SSO settings page).
Under Attribute mappings, configure the following:
| Attribute | Value | Format |
|---|---|---|
| Subject | ${user:email} | unspecified |
${user:email} | unspecified | |
| first_name | ${user:givenName} | unspecified |
| last_name | ${user:familyName} | unspecified |
[!warning] You must set the Subject (NameID) format to
unspecified. Setting the format topersistentortransientcauses authentication errors for existing GitLab users attempting to link their accounts.
Under IAM Identity Center SAML metadata, copy the IAM Identity Center sign-in URL and download the certificate.
On your terminal, generate a SHA1 fingerprint from the downloaded certificate:
openssl x509 -noout -fingerprint -sha1 -inform pem -in <path-to-downloaded-cert.pem>
In GitLab, on the group SAML SSO settings page, complete the following fields:
In AWS IAM Identity Center, assign users to the GitLab application. To link existing GitLab accounts, users must sign in from the GitLab single sign-on URL or the Application start URL.
For more information, see the AWS IAM Identity Center configuration example.
When a user signs in through their identity provider dashboard (IdP-initiated login), the SAML
response does not include an InResponseTo attribute. GitLab requires this attribute to link
a SAML identity to an existing account.
AWS IAM Identity Center defaults to IdP-initiated login. If the Application start URL is not
configured, existing users see the error Request to link SAML account must be authorized
when they try to sign in.
To avoid this, set the Application start URL to your GitLab single sign-on URL.
This ensures users start the login flow from GitLab, so the InResponseTo attribute is
present in the SAML response.
[!note] These attributes are case-insensitive.
At minimum, you must configure the following assertions:
Optionally, you can pass user information to GitLab as attributes in the SAML assertion.
For more information on available attributes, see SAML SSO for GitLab Self-Managed.
To configure some identity providers, you need a GitLab metadata URL. To find this URL:
Check your identity provider's documentation to see if it supports the GitLab metadata URL.
After you have set up your identity provider, you can:
You can change to a different identity provider. During the change process, users cannot access any of the SAML groups. To mitigate this, you can disable SSO enforcement.
To change identity providers:
To migrate users to a new email domain, tell users to:
If the NameID is configured with the email address, change the NameID for users.
{{< history >}}
{{< /history >}}
After you set up your identity provider to work with GitLab, you must configure GitLab to use it for authentication:
If you are having issues configuring GitLab, see the troubleshooting documentation.
After group SSO is configured and enabled, users can access the GitLab.com group through the identity provider's dashboard. If SCIM is configured, see user access on the SCIM page.
When a user tries to sign in with Group SSO, GitLab attempts to find or create a user based on the following:
{{< history >}}
bso_minimal_access_fallback. Disabled by default.{{< /history >}}
When restricted access is enabled with no available seats, users provisioned through SAML are assigned the Minimal Access role.
For more information, see Provisioning behavior with SAML, SCIM, and LDAP.
{{< history >}}
{{< /history >}}
[!note] If the user is an enterprise user of that group, the following steps do not apply. The enterprise user must instead sign in with a SAML account that has the same email as the GitLab account. This allows GitLab to link the SAML account to the existing account.
To link SAML to your existing GitLab.com account:
If a user is already a member of the group, linking the SAML identity does not change their role.
On subsequent visits, you should be able to sign in to GitLab.com with SAML or by visiting links directly. If the enforce SSO option is turned on, you are then redirected to sign in through the identity provider.
If an enterprise user is removed from the group and then returns, they can sign in with their enterprise SSO account. As long as the user's email address in the identity provider remains the same as the email address on the existing GitLab account, the SSO identity is automatically linked to the account and the user can sign in without any issues. This functionality also applies to existing users that have been claimed as an enterprise user but who may not have yet signed into the group.
{{< history >}}
{{< /history >}}
GitLab.com uses the SAML NameID to identify users. The NameID is:
The NameID must:
The NameID should not be an email address or username because:
The NameID format must be Persistent, unless you are using a field, like email, that
requires a different format. You can use any format except Transient.
Group owners can use the SAML API to change their group members' NameID and update their SAML identities.
If SCIM is configured, group owners can update the SCIM identities using the SCIM API.
Alternatively, ask the users to reconnect their SAML account.
[!warning] After users have signed into GitLab using SSO SAML, changing the NameID value breaks the configuration and could lock users out of the GitLab group.
For more information on the recommended value and format for specific identity providers, see set up your identity provider.
{{< history >}}
{{< /history >}}
GitLab allows setting certain user attributes based on values from the SAML response. An existing user's attributes are updated from the SAML response values if that user is an enterprise user of the group.
can_create_group - true or false to indicate whether an enterprise user can create
new top-level groups. Default is true.projects_limit - The total number of personal projects an enterprise user can create.
A value of 0 means the user cannot create new projects in their personal
namespace. Default is 100000.SessionNotOnOrAfter - An ISO 8601 timestamp value that indicates when to end the user SAML session.You can find SAML responses in the developer tools or console of your browser, in base64-encoded format. Use the base64 decoding tool of your choice to convert the information to XML. An example SAML response is shown here.
<saml2:AttributeStatement>
<saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.email</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="username" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.nickName</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.firstName</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">user.lastName</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="can_create_group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">true</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="projects_limit" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">10</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
{{< history >}}
saml_timeout_supplied_by_idp_override.{{< /history >}}
By default, GitLab ends SAML sessions after 24 hours. You can customize this duration with
the SessionNotOnOrAfter attribute in the SAML2 AuthnStatement. This attribute contains an
ISO 8601 timestamp value that indicates when to end the user session. When specified this
value overrides the default SAML session timeout of 24 hours.
By default, GitLab ends sessions after seven days (10080 minutes) of inactivity. If the
SessionNotOnOrAfter timestamp is after this time, users must re-authenticate when their
session ends.
<saml:AuthnStatement SessionIndex="WDE5aBYjNEj_9IjCFiK0E1YelZT" SessionNotOnOrAfter="2025-08-25T01:23:45.067Z" AuthnInstant="2025-08-24T13:23:45.067Z">
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
{{< history >}}
{{< /history >}}
By default, users provisioned with SAML or SCIM are sent a verification email to verify their identity. Instead, you can configure GitLab with a custom domain and GitLab automatically confirms user accounts. Users still receive an enterprise user welcome email. Confirmation is bypassed if both of the following are true:
{{< history >}}
{{< /history >}}
Prerequisites:
You can disable password authentication for all enterprise users of the group. This also applies to enterprise users who are administrators of the group. Configuring this setting stops enterprise users from changing, resetting, or authenticating with their password. Instead, these users can authenticate with:
To disable password and passkey authentication for enterprise users:
To rescind a user's access to the group when only SAML SSO is configured, either:
To rescind a user's access to the group when also using SCIM, refer to Remove access.
Users can unlink SAML for a group from their profile page. This can be helpful if:
[!warning] Unlinking an account removes all roles assigned to that user in the group. If a user re-links their account, roles need to be reassigned.
Groups require at least one owner. If your account is the only owner in the group, you are not allowed to unlink the account. In that case, set up another user as a group owner, and then you can unlink the account.
For example, to unlink the MyOrg account:
{{< history >}}
transparent_sso_enforcement to include transparent enforcement even when SSO enforcement is not enabled. Disabled on GitLab.com.transparent_sso_enforcement removed.{{< /history >}}
On GitLab.com, SSO is enforced:
A user has a SAML identity if one or both of the following are true:
Users are not prompted to sign in through SSO on each visit. GitLab checks whether a user has authenticated through SSO. If the user last signed in more than 24 hours ago, GitLab prompts the user to sign in again through SSO.
SSO is enforced as follows:
| Project/Group visibility | Enforce SSO setting | Member with identity | Member without identity | Non-member or not signed in |
|---|---|---|---|---|
| Private | Off | Enforced | Not enforced | Not enforced |
| Private | On | Enforced | Enforced | Enforced |
| Public | Off | Enforced | Not enforced | Not enforced |
| Public | On | Enforced | Enforced | Not enforced |
[!note] SSO enforcement does not apply to API requests. However, you can disable password and passkey authentication for enterprise users to prevent password-based API access.
An issue proposes to add SSO enforcement for API activity.
When the Enforce SSO-only authentication for web activity for this group option is enabled:
SSO enforcement for web activity has the following effects when enabled:
When SSO for web activity is enforced, non-SSO group members do not lose access immediately. If the user:
When you enable Enforce SSO-only authentication for Git and Dependency Proxy activity for this group, repository mirroring is subject to SSO session requirements. For more information, see Pull mirroring with SSO enforcement.
To migrate to a new identity provider, use the SAML API to update all of your group member's identities.
For example:
If you find it difficult to match the different SAML terms between GitLab and the identity provider:
ruby-saml library.For other troubleshooting information, see the troubleshooting SAML guide.