SCIM provisioning using SAML SSO for GitLab.com groups

Introduced in GitLab.com Silver 11.10.

System for Cross-domain Identity Management (SCIM), is an open standard that enables the automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of that group is synchronized between GitLab and the identity provider.

GitLab’s SCIM API implements part of the RFC7644 protocol.

Features

Currently, the following actions are available:

  • Create users
  • Update users (Azure only)
  • Deactivate users

The following identity providers are supported:

  • Azure
  • Okta

Requirements

GitLab configuration

Once Group Single Sign-On has been configured, we can:

  1. Navigate to the group and click Administration > SAML SSO.
  2. Click on the Generate a SCIM token button.
  3. Save the token and URL so they can be used in the next step.

SCIM token configuration

Identity Provider configuration

Azure configuration steps

The SAML application that was created during Single sign-on setup for Azure now needs to be set up for SCIM.

  1. Check the configuration for your GitLab SAML app and ensure that Name identifier value (NameID) points to user.objectid or another unique identifier. This will match the extern_uid used on GitLab.

    Name identifier value mapping

  2. Set up automatic provisioning and administrative credentials by following the Provisioning users and groups to applications that support SCIM section in Azure’s SCIM setup documentation.

During this configuration, note the following:

  • The Tenant URL and secret token are the ones retrieved in the previous step.
  • Should there be any problems with the availability of GitLab or similar errors, the notification email set will get those.
  • It is recommended to set a notification email and check the Send an email notification when a failure occurs checkbox.
  • For mappings, we will only leave Synchronize Azure Active Directory Users to AppName enabled.

You can then test the connection by clicking on Test Connection. If the connection is successful, be sure to save your configuration before moving on. See below for troubleshooting.

Configure attribute mapping

  1. Click on Synchronize Azure Active Directory Users to AppName to configure the attribute mapping.
  2. Click Delete next to the mail mapping.
  3. Map userPrincipalName to emails[type eq "work"].value and change its Matching precedence to 2.
  4. Map mailNickname to userName.

  5. Determine how GitLab will uniquely identify users.

    • Use objectId unless users already have SAML linked for your group.
    • If you already have users with SAML linked then use the Name ID value from the SAML configuration. Using a different value will likely cause duplicate users and prevent users from accessing the GitLab group.
  6. Create a new mapping:
    1. Click Add New Mapping.
    2. Set:
      • Source attribute to the unique identifier determined above, typically objectId.
      • Target attribute to externalId.
      • Match objects using this attribute to Yes.
      • Matching precedence to 1.

  7. Click the userPrincipalName mapping and change Match objects using this attribute to No.

  8. Save your changes. For reference, you can view an example configuration in the troubleshooting reference.

    Note: If you used a unique identifier other than objectId, be sure to map it to externalId.

  9. Below the mapping list click on Show advanced options > Edit attribute list for AppName.

  10. Ensure the id is the primary and required field, and externalId is also required.

    Note: username should neither be primary nor required as we don’t support that field on GitLab SCIM yet.

  11. Save all the screens and, in the Provisioning step, set the Provisioning Status to On.

    Provisioning status toggle switch

    Note: You can control what is actually synced by selecting the Scope. For example, Sync only assigned users and groups will only sync the users assigned to the application (Users and groups), otherwise, it will sync the whole Active Directory.

Once enabled, the synchronization details and any errors will appear on the bottom of the Provisioning screen, together with a link to the audit logs.

Warning: Once synchronized, changing the field mapped to id and externalId will likely cause provisioning errors, duplicate users, and prevent existing users from accessing the GitLab group.

Okta configuration steps

The SAML application that was created during Single sign-on setup for Okta now needs to be set up for SCIM. Before proceeding, be sure to complete the GitLab configuration process.

  1. Sign in to Okta.

  2. If you see an Admin button in the top right, click the button. This will ensure you are in the Admin area.

    Tip: If you’re using the Developer Console, click Developer Console in the top bar and select Classic UI. Otherwise, you may not see the buttons described in the following steps:
  3. In the Application tab, click Add Application.
  4. Search for GitLab, find and click on the ‘GitLab’ application.
  5. On the GitLab application overview page, click Add.
  6. Under Application Visibility select both check boxes. Currently the GitLab application does not support SAML authentication so the icon should not be shown to users.
  7. Click Done to finish adding the application.
  8. In the Provisioning tab, click Configure API integration.
  9. Select Enable API integration.
    • For Base URL enter the URL obtained from the GitLab SCIM configuration page
    • For API Token enter the SCIM token obtained from the GitLab SCIM configuration page
  10. Click ‘Test API Credentials’ to verify configuration.
  11. Click Save to apply the settings.
  12. After saving the API integration details, new settings tabs will appear on the left. Choose To App.
  13. Click Edit.
  14. Check the box to Enable for both Create Users and Deactivate Users.
  15. Click Save.
  16. Assign users in the Assignments tab. Assigned users will be created and managed in your GitLab group.

Okta Known Issues

The Okta GitLab application currently only supports SCIM. Continue using the separate Okta SAML SSO configuration along with the new SCIM application described above.

User access and linking setup

The following diagram is a general outline on what happens when you add users to your SCIM app:

graph TD A[Add User to SCIM app] -->|IdP sends user info to GitLab| B(GitLab: Does the email exists?) B -->|No| C[GitLab creates user with SCIM identity] B -->|Yes| D[GitLab sends message back 'Email exists']

As long as Group SAML has been configured, existing GitLab.com users can link to their accounts in one of the following ways:

  • By updating their primary email address in their GitLab.com user account to match their identity provider’s user profile email address.

  • By following these steps:

    1. Sign in to GitLab.com if needed.
    2. Click on the GitLab app in the identity provider’s dashboard or visit the GitLab single sign-on URL.
    3. Click on the Authorize button.

We recommend users do this prior to turning on sync, because while synchronization is active, there may be provisioning errors for existing users.

New users and existing users on subsequent visits can access the group through the identify provider’s dashboard or by visiting links directly.

For role information, please see the Group SAML page

Blocking access

To rescind access to the group, remove the user from the identity provider or users list for the specific app.

Upon the next sync, the user is deprovisioned, which means that the user is removed from the group.

Note: Deprovisioning does not delete the user account.
graph TD A[Remove User from SCIM app] -->|IdP sends request to GitLab| B(GitLab: Is the user part of the group?) B -->|No| C[Nothing to do] B -->|Yes| D[GitLab removes user from GitLab group]

Troubleshooting

This section contains possible solutions for problems you might encounter.

How come I can’t add a user after I removed them?

As outlined in the Blocking access section, when you remove a user, they are removed from the group. However, their account is not deleted.

When the user is added back to the SCIM app, GitLab cannot create a new user because the user already exists.

Solution: Have a user sign in directly to GitLab, then manually link their account.

Azure

How do I verify my SCIM configuration is correct?

Review the following:

  • Ensure that the SCIM value for id matches the SAML value for NameId.
  • Ensure that the SCIM value for externalId matches the SAML value for NameId.

Review the following SCIM parameters for sensible values:

  • userName
  • displayName
  • emails[type eq "work"].value

Testing Azure connection: invalid credentials

When testing the connection, you may encounter an error: You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account. If Tenant URL and secret token are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as .). Removing such characters from the group path typically resolves the error.

Azure: (Field) can’t be blank sync error

When checking the Audit Logs for the Provisioning, you can sometimes see the error Namespace can't be blank, Name can't be blank, and User can't be blank.

This is likely caused because not all required fields (such as first name and last name) are present for all users being mapped.

As a workaround, try an alternate mapping:

  1. Follow the Azure mapping instructions from above.
  2. Delete the name.formatted target attribute entry.
  3. Change the displayName source attribute to have name.formatted target attribute.

How do I diagnose why a user is unable to sign in

Ensure that the user has been added to the SCIM app.

If you receive “User is not linked to a SAML account”, then most likely the user already exists in GitLab. Have the user follow the User access and linking setup instructions.

The Identity (extern_uid) value stored by GitLab is updated by SCIM whenever id or externalId changes. Users won’t be able to sign in unless the GitLab Identity (extern_uid) value matches the NameId sent by SAML.

This value is also used by SCIM to match users on the id, and is updated by SCIM whenever the id or externalId values change.

It is important that this SCIM id and SCIM externalId are configured to the same value as the SAML NameId. SAML responses can be traced using debugging tools, and any errors can be checked against our SAML troubleshooting docs.

How do I verify user’s SAML NameId matches the SCIM externalId

Group owners can see the list of users and the externalId stored for each user in the group SAML SSO Settings page.

Alternatively, the SCIM API can be used to manually retrieve the externalId we have stored for users, also called the external_uid or NameId.

For example: 

curl 'https://gitlab.example.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=1"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

To see how this compares to the value returned as the SAML NameId, you can have the user use a SAML Tracer.

Update or fix mismatched SCIM externalId and SAML NameId

Whether the value was changed or you need to map to a different field, ensure id, externalId, and NameId all map to the same field.

If GitLab’s externalId doesn’t match the SAML NameId, it will need to be updated in order for the user to log in. Ideally your identity provider will be configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change.

Be cautious if you revise the fields used by your SCIM identity provider, typically id and externalId. We use these IDs to look up users. If the identity provider does not know the current values for these fields, that provider may create duplicate users.

If the externalId for a user is not correct, and also doesn’t match the SAML NameID, you can address the problem in the following ways:

  • You can have users unlink and relink themselves, based on the “SAML authentication failed: User has already been taken” section.
  • You can unlink all users simultaneously, by removing all users from the SAML app while provisioning is turned on.
  • You can use the SCIM API to manually correct the externalId stored for users to match the SAML NameId. To look up a user, you’ll need to know the desired value that matches the NameId as well as the current externalId.

It is then possible to issue a manual SCIM#update request, for example: 

curl --verbose --request PATCH 'https://gitlab.com/api/scim/v2/groups/YOUR_GROUP/Users/OLD_EXTERNAL_UID' --data '{ "Operations": [{"op":"Replace","path":"externalId","value":"NEW_EXTERNAL_UID"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account.

I need to change my SCIM app

Individual users can follow the instructions in the “SAML authentication failed: User has already been taken” section.

Alternatively, users can be removed from the SCIM app which will delink all removed users. Sync can then be turned on for the new SCIM app to link existing users.