SAML Group Sync

Introduced for self-managed instances in GitLab 15.1.

caution
Adding or changing Group Sync configuration can remove users from the mapped GitLab group. Removal happens if there is any mismatch between the group names and the list of groups in the SAML response. Before making changes, ensure either the SAML response includes the groups attribute and the AttributeValue value matches the SAML Group Name in GitLab, or that all groups are removed from GitLab to disable Group Sync.

For a demo of Group Sync using Azure, see Demo: SAML Group Sync.

Configure SAML Group Sync

note
You must include the SAML configuration block on all Sidekiq nodes in addition to Rails application nodes if you use SAML Group Sync and have multiple GitLab nodes, for example in a distributed or highly available architecture.
caution
To prevent users being accidentally removed from the GitLab group, follow these instructions closely before enabling Group Sync in GitLab.

To configure SAML Group Sync for self-managed GitLab instances:

  1. Configure the SAML OmniAuth Provider.

  2. Ensure your SAML identity provider sends an attribute statement with the same name as the value of the groups_attribute setting. See the following attribute statement example for reference: 

    gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name", # optional label for login button, defaults to "Saml",
    groups_attribute: 'Groups',
    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"
    }
  }
]

To configure SAML Group Sync for GitLab.com instances:

  1. See SAML SSO for GitLab.com groups.
  2. Ensure your SAML identity provider sends an attribute statement named Groups or groups.
note
The value for Groups or groups in the SAML response may be either the group name or an ID. For example, Azure AD sends the Azure Group Object ID instead of the name. Use the ID value when configuring SAML Group Links.
<saml:AttributeStatement>
  <saml:Attribute Name="Groups">
    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Other attribute names such as http://schemas.microsoft.com/ws/2008/06/identity/claims/groups are not accepted as a source of groups.

For more information on configuring the required group attribute name in the SAML identity provider’s settings, see example configurations for Azure AD and Okta.

When SAML is enabled, users with the Maintainer or Owner role see a new menu item in group Settings > SAML Group Links.

  • You can configure one or more SAML Group Links to map a SAML identity provider group name to a GitLab role.
  • Members of the SAML identity provider group are added as members of the GitLab group on their next SAML sign-in.
  • Group membership is evaluated each time a user signs in using SAML.
  • SAML Group Links can be configured for a top-level group or any subgroup.
  • SAML Group Sync only manages a group if that group has one or more SAML group links.
    • If a SAML group link is created then removed, the user remains in the group until they are removed from the group in the identity provider.

Prerequisites:

  • Self-managed GitLab instances must have configured SAML Group Sync. GitLab.com instances are already configured for SAML Group Sync, and require no extra configuration.

To link the SAML groups:

  1. In SAML Group Name, enter the value of the relevant saml:AttributeValue. The value entered here must exactly match the value sent in the SAML response. For some IdPs, this may be a group ID or object ID (Azure AD) instead of a friendly group name.
  2. Choose the role in Access Level.
  3. Select Save.
  4. Repeat to add additional group links if required.

SAML Group Links

If a user is a member of multiple SAML groups mapped to the same GitLab group, the user gets the highest role from the groups. For example, if one group is linked as Guest and another Maintainer, a user in both groups gets the Maintainer role.

Users granted:

  • A higher role with Group Sync are displayed as having direct membership of the group.
  • A lower or the same role with Group Sync are displayed as having inherited membership of the group.

Use the API

Introduced in GitLab 15.3.

You can use the GitLab API to list, add, and delete SAML group links.

Microsoft Azure Active Directory integration

Introduced in GitLab 16.3.

note
Microsoft has announced that Azure Active Directory (AD) is being renamed to Entra ID.

Azure AD sends up to 150 groups in the groups claim. When users are members of more than 150 groups Azure AD sends a group overage claim attribute in the SAML response. Then group memberships must be obtained using the Microsoft Graph API.

To integrate Microsoft Azure AD, you:

  • Configure Azure AD to enable GitLab to communicate with the Microsoft Graph API.
  • Configure GitLab.

GitLab settings to Azure AD fields

GitLab setting Azure field
Tenant ID Directory (tenant) ID
Client ID Application (client) ID
Client Secret Value (on Certificates & secrets page)

Configure Azure AD

  1. In the Azure Portal, go to Microsoft Entra ID > App registrations > All applications, and select your GitLab SAML application.
  2. Under Essentials, the Application (client) ID and Directory (tenant) ID values are displayed. Copy these values, because you need them for the GitLab configuration.
  3. In the left navigation, select Certificates & secrets.
  4. On the Client secrets tab, select New client secret.
    1. In the Description text box, add a description.
    2. In the Expires dropdown list, set the expiration date for the credentials. If the secret expires, the GitLab integration will no longer work until the credentials are updated.
    3. To generate the credentials, select Add.
    4. Copy the Value of the credential. This value is displayed only once, and you need it for the GitLab configuration.
  5. In the left navigation, select API permissions.
  6. Select Microsoft Graph > Application permissions.
  7. Select the checkboxes GroupMember.Read.All and User.Read.All.
  8. Select Add permissions to save.
  9. Select Grant admin consent for <application_name>, then on the confirmation dialog select Yes. The Status column for both permissions should change to a green check with Granted for <application_name>.

Configure GitLab

To configure for a GitLab.com group:

  1. On the left sidebar, select Search or go to and find your top-level group.
  2. Select Settings > SAML SSO.
  3. Configure SAML SSO for the group.
  4. In the Microsoft Azure integration section, select the Enable Microsoft Azure integration for this group checkbox. This section will only be visible if SAML SSO is configured and enabled for the group.
  5. Enter the Tenant ID, Client ID, and Client secret obtained earlier when configuring Azure Active Directory in the Azure Portal.
  6. Optional. If using Azure AD for US Government or Azure AD China, enter the appropriate Login API endpoint and Graph API endpoint. The default values work for most organizations.
  7. Select Save changes.

To configure for self-managed:

  1. Configure SAML SSO for the instance.
  2. On the left sidebar, at the bottom, select Admin Area.
  3. Select Settings > General.
  4. In the Microsoft Azure integration section, select the Enable Microsoft Azure integration for this group checkbox.
  5. Enter the Tenant ID, Client ID, and Client secret obtained earlier when configuring Azure Active Directory in the Azure Portal.
  6. Optional. If using Azure AD for US Government or Azure AD China, enter the appropriate Login API endpoint and Graph API endpoint. The default values work for most organizations.
  7. Select Save changes.

With this configuration, if a user signs in with SAML and Azure sends a group overage claim in the response, GitLab initiates a Group Sync job to call the Microsoft Graph API and retrieve the user’s group membership. Then the GitLab Group membership is updated according to SAML Group Links.

Global SAML group memberships lock

Introduced in GitLab 15.10.

GitLab administrators can use the global SAML group memberships lock to prevent group members from inviting new members to subgroups that have their membership synchronized with SAML Group Links.

Global group memberships lock only applies to subgroups of a top-level group where SAML Group Links synchronization is configured. No user can modify the membership of a top-level group configured for SAML Group Links synchronization.

When global group memberships lock is enabled:

  • Only an administrator can manage memberships of any group including access levels.
  • Users cannot:
    • Share a project with other groups.
    • Invite members to a project created in a group.

To enable global group memberships lock:

  1. Configure SAML for your self-managed GitLab instance.
  2. On the left sidebar, at the bottom, select Admin Area.
  3. On the left sidebar, select Settings > General.
  4. Expand the Visibility and access controls section.
  5. Ensure that Lock memberships to SAML Group Links synchronization is selected.

Automatic member removal

After a group sync, users who are not members of a mapped SAML group are removed from the group. On GitLab.com, users in the top-level group are assigned the default membership role instead of being removed.

For example, in the following diagram:

  • Alex Garcia signs into GitLab and is removed from GitLab Group C because they don’t belong to SAML Group C.
  • Sidney Jones belongs to SAML Group C, but is not added to GitLab Group C because they have not yet signed in.
graph TB subgraph SAML users SAMLUserA[Sidney Jones] SAMLUserB[Zhang Wei] SAMLUserC[Alex Garcia] SAMLUserD[Charlie Smith] end subgraph SAML groups SAMLGroupA["Group A"] --> SAMLGroupB["Group B"] SAMLGroupA --> SAMLGroupC["Group C"] SAMLGroupA --> SAMLGroupD["Group D"] end SAMLGroupB --> |Member|SAMLUserA SAMLGroupB --> |Member|SAMLUserB SAMLGroupC --> |Member|SAMLUserA SAMLGroupC --> |Member|SAMLUserB SAMLGroupD --> |Member|SAMLUserD SAMLGroupD --> |Member|SAMLUserC
graph TB subgraph GitLab users GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph GitLab groups GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] end GitLabGroupB --> |Member|GitLabUserA GitLabGroupC --> |Member|GitLabUserB GitLabGroupC --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserD
graph TB subgraph GitLab users GitLabUserA[Sidney Jones] GitLabUserB[Zhang Wei] GitLabUserC[Alex Garcia] GitLabUserD[Charlie Smith] end subgraph GitLab groups after Alex Garcia signs in GitLabGroupA[Group A] GitLabGroupA["Group A (SAML configured)"] --> GitLabGroupB["Group B (SAML Group Link not configured)"] GitLabGroupA --> GitLabGroupC["Group C (SAML Group Link configured)"] GitLabGroupA --> GitLabGroupD["Group D (SAML Group Link configured)"] end GitLabGroupB --> |Member|GitLabUserA GitLabGroupC --> |Member|GitLabUserB GitLabGroupD --> |Member|GitLabUserC GitLabGroupD --> |Member|GitLabUserD

User that belongs to many SAML groups automatically removed from GitLab group

When using Azure AD with SAML, if any user in your organization is a member of more than 150 groups and you use SAML Group Sync, that user may lose their group memberships. For more information, see Microsoft Group overages.

GitLab has a Microsoft Azure Active Directory integration that enables SAML Group Sync for organizations with users in more than 150 groups. This integration uses the Microsoft Graph API to obtain all user memberships and is not limited to 150 groups.

Otherwise, you can work around this issue by changing the group claims to use the Groups assigned to the application option instead.

Manage Group Claims.