Configure SCIM

System for Cross-domain Identity Management (SCIM) lets you manage GitGuardian users and teams directly from your Identity Provider (IdP). Based on changes in your IdP, SCIM automatically creates, updates, deactivates, and deletes users, and creates/manages teams from IdP groups.

info

SCIM supports user and team provisioning/deprovisioning for Okta and Microsoft Entra ID.

Prerequisites

• SCIM requires Single Sign-On (SSO) to be configured first.
• SCIM is supported for Okta and Microsoft Entra ID.

SCIM Features

GitGuardian supports:

• Manage the full user lifecycle: provision, activate, deactivate, and delete based on your IdP.
• Provision and manage teams from IdP groups.

Enable SCIM in GitGuardian

1. Navigate to Settings > Authentication in your GitGuardian workspace.
2. Under SCIM, toggle the option to enable SCIM integration.
3. Follow the instructions in the Set up SCIM in your IdP section.

Once SCIM is enabled, your users can be synchronized with your IdP, and user deprovisioning can occur automatically.

Unlinked Members

You may see a message indicating that some users are not linked to your IdP. These users won't be managed by SCIM.

• Review the Members List: Check the unlinked users.
• Deactivate if Necessary: Manually deactivate any users who shouldn't have access.

This typically happens for users added before SCIM was enabled or not assigned in your IdP. SCIM only manages linked users.

Set up SCIM in your IdP

To configure SCIM, you will need to provide the SCIM endpoint and configure the corresponding SCIM settings in your IdP. Here's a high-level overview for common IdPs:

Follow the specific steps for your IdP to enable SCIM integration. Most IdPs provide an option to configure SCIM via their API or dashboard settings. You will need to provide:

• GitGuardian SCIM Endpoint: https://api.gitguardian.com/v1/scim/v2 (or https://gitguardian.mycorp.local/exposed/v1/scim/v2 for self-hosted)
• API Token: Use a GitGuardian service account token with members:write and teams:write permissions.

Each IdP’s SCIM configuration page will have specific instructions. Refer to the documentation for your IdP for details on how to enter the SCIM endpoint and configure API credentials.

Google & Keycloak Users

Google only supports automatic provisioning for specific apps, so SCIM cannot be used for provisioning with Google at this time. However, we are planning to support SCIM for Google and publish our app in the future.

The scim-for-keycloak plugin has a bug that causes confusion with the externalId value, which is used for making SCIM requests to GitGuardian, so it won't work with our SCIM integration. For more details, see the issue here.

Set up procedures

Okta

Important Note

If users are assigned to the Okta app before SCIM is enabled, they won’t be deactivated in GitGuardian when later unassigned. To ensure proper deactivation:

1. Duplicate the original Okta group (same members).
2. Assign the duplicate group to the app.
3. Unassign the original group from the app.

1. In Okta, navigate to the General settings of your GitGuardian app and check the box for Enable SCIM provisioning.

2. In the Provisioning settings of your Okta app, configure the following:

   • Set the SCIM Connector Base URL to:
     https://api.gitguardian.com/v1/scim/v2 (or https://gitguardian.mycorp.local/exposed/v1/scim/v2 for self-hosted).
   • Use email as the unique identifier field for users. Username field must be an email.
   • Enable the Push New Users, Push Profile Updates and Push Groups settings.
   • Select HTTP Header for authentication mode and add the service account token in the Authorization HTTP header.

3. Check the Create Users, Update User Attributes and Deactivate Users options under the Provisioning to app settings.

4. Finally, in Assignments, assign the users. In Push Groups, assign the groups you want to sync with GitGuardian.

Microsoft Entra ID

important note

When a user is unassigned from the GitGuardian app in Entra ID, no deactivation request is sent. To deactivate, the user must be disabled in Entra ID.

1. In Microsoft Entra ID (formerly Azure Active Directory), navigate to the Enterprise Applications section.
2. Select your GitGuardian app, then go to Provisioning and set the Provisioning Mode to Automatic.
3. Provide the SCIM API Token and GitGuardian SCIM Endpoint:
   https://api.gitguardian.com/v1/scim/v2 (or https://gitguardian.mycorp.local/exposed/v1/scim/v2 for self-hosted).
4. In the Attribute Mappings section under Provision Microsoft Entra ID Users, configure the following mappings to match GitGuardian's SCIM requirements:
   • Target Object Actions: Set actions to Create, Update and Delete for the target object.
   • Attribute Mappings:
     • userName: Map this to userPrincipalName
     • active: Map this to Switch([IsSoftDeleted], , "False", "True", "True", "False")
     • name.givenName: Map this to givenName
     • name.familyName: Map this to surname
     • externalId: Map this to userPrincipalName
5. In the Attribute Mappings section under Provision Microsoft Entra ID Groups, configure the following mappings to match GitGuardian's SCIM requirements:
   • Target Object Actions: Set actions to Create, Update and Delete for the target object.
   • Attribute Mappings:
     • displayName: Map this to displayName
     • externalId: Map this to objectId
     • members: Map this to members
6. Save the mapping and sync the users and teams.

FAQ

Can I use SCIM for provisioning teams?

Yes, SCIM supports team provisioning for Okta and Microsoft Entra ID. Teams are automatically created and managed in your workspace when groups are added or updated in your IdP. Ensure your service account token has teams:write permissions.

How do I link GitGuardian to my IdP for SCIM?

You will need to configure SCIM in your IdP by entering the provided SCIM endpoint and API token. Each IdP has its own process for linking SCIM integrations. Follow the relevant setup instructions for your IdP.

Does GitGuardian support Just-In-Time (JIT) provisioning with SCIM?

SCIM now supports user provisioning, activation, deactivation, and deletion. JIT provisioning via SSO is also available, while SCIM gives you more control over the user lifecycle for provisioning, activation, deactivation, and deletion.