<img height="1" width="1" style="display:none" src="https://www.facebook.com/tr?id=691116991096043&amp;ev=PageView&amp;noscript=1">
Skip to content
  • There are no suggestions because the search field is empty.

Configure SCIM for Microsoft Entra

This article explains how to configure SCIM (System for Cross-domain Identity Management) integration between Microsoft Entra and Gatekeeper.

   Take Control

   Estimated Read Time: 8 minutes

Sections in this article:


What is SCIM?

SCIM (System for Cross-domain Identity Management) is an open standard used to automate the provisioning and management of users. It enables identity providers, such as Microsoft Entra or Okta, to securely synchronise user data with Gatekeeper, helping to ensure consistency and reduce manual tasks.

Note:

  • SCIM provisioning runs every 40 minutes.
  • SAML user sync occurs every hour at the 45th minute.
  • Users created via SCIM cannot sign in until the SAML sync has completed.

Configuration

Permissions Required for Setup

This article focuses on setting up SCIM integration using Microsoft Entra. To follow the steps, you’ll need:

  • An Azure Entra tenant with permission to create enterprise applications.
  • Appropriate admin roles in Microsoft Entra (i.e. Application Administrator to create enterprise applications, and Groups Administrator to manage group assignments).
  • Additional Azure Entra permissions may be required, depending on your organisation’s configuration.
  • Global Administrator permissions in Gatekeeper, with the Configuration additional permission.

Step 1: Set the Default Team and Mapping

The fallback team is where users will be assigned if their groups or permissions are deleted, for example. The Default Mapping should grant only minimal permissions. To do this: 

  1. From the navigation menu, expand Settings then click Configuration.
  2. Click System for Cross-domain Identity Management (SCIM).
  3. Select the relevant team from the Select Fallback Team dropdown list.
  4. Click the pencil icon on Default Mapping.
  5. Select the relevant permissions, then click Save.

Step 2: Set Up the Enterprise Application in Microsoft Azure

The next step is to create a new enterprise application in Microsoft Azure to enable the SCIM connection with Gatekeeper.

  1. Log in to the Microsoft Azure Portal.
  2. Navigate to Enterprise Applications.
  3. Click New Application.
  4. Click Create your own application, then enter a name e.g. Gatekeeper - SCIM.
  5. Select the Integrate any other application you don’t find in the gallery radio button, then click Create.

Step 3: Configure SAML Single Sign-On (SSO)

To enable user login, you must configure SAML Single Sign-On between Microsoft Entra and Gatekeeper. In the newly created enterprise application:

  1. From the navigation menu, click  Single sign-on , then select SAML.
  2. From the SAML Certificates section, copy the App Federation Metadata Url.
  3. Return to Gatekeeper, and from the navigation menu, expand Settings then click Configuration.
  4. Click Authentication, then click Configure SAML 2.0.
    configure saml
    1. Enter the App Federation Metadata Url that you copied earlier in the IDP metadata URL field.
    2. Click Create. Gatekeeper then generates required fields. Copy the following:
      1. Metadata url
      2. Sso url
      3. ACS (Assertion Consumer Service, Recipient) url
      4. Logout url
  5. Return to Microsoft Entra, then click Edit in the Basic SAML Configuration box.
  6. Enter the fields copied from Gatekeeper into their respective fields, then save the configuration.

Verify that the certificate is now available in Microsoft Entra, indicating the SAML setup is complete.

Step 4: Configure SCIM Provisioning

With SAML configured, the next step is to set up SCIM provisioning to automate user management between Microsoft Entra and Gatekeeper.

  1. Within the Microsoft Azure Enterprise Application, click Provisioning from the navigation menu.
  2. Click Connect your application.
  3. In a separate Gatekeeper tab, from the navigation menu, expand Settings then click Configuration.
  4. Click System for Cross-domain Identity Management (SCIM).
  5. Copy the Base URL, then click Generate API Key.
  6. Copy the API Key. For security reasons, you won't be able to view the key again after clicking Copy & Save.
  7. In Azure Entra, enter the Base URL into the Tenant URL field and the API Key into the Secret Token field.
  8. Click Test Connection to ensure it has been successful, then click Create.

Step 5: Adjust User Mapping

To ensure user details are mapped correctly in Gatekeeper, you’ll need to update the default user attribute mapping in Microsoft Entra.

  1. In Microsoft Azure, from the navigation menu, click Provisioning, then expand Mappings and click Provision Microsoft Entra ID Users.
  2. Locate the custommappsso Attribute: emails[type eq "work"].value. By default, this is mapped to the mail attribute.
    email attribute
  3. Click Edit, then select userPrincipalName from the Source attribute instead.
  4. Save the configuration.

Step 6: Assign Users or Groups

Once provisioning is configured, you can assign users or groups to the SCIM-integrated application in Microsoft Entra.

  1. Go to Users and Groups in the application.
  2. Create a test user or group in Microsoft Entra.
  3. Assign the group or user to the SCIM-integrated app.
    • To test, you can use Provision on Demand from the provisioning page.
    • Select a user from the group and click Provision.

Note: SCIM syncs every 40 minutes, and SAML syncs every hour at the 45th minute. Logging in via SSO might be delayed if attempted before the next sync cycle.

Step 7: Verify Provisioning in Gatekeeper

After assigning users or groups in Microsoft Entra, verify that they have been successfully provisioned into Gatekeeper.

  1. In Gatekeeper, from the navigation menu, expand Settings then click Configuration.
  2. Click System for Cross-domain Identity Management (SCIM).
  3. You should see the provisioned group and user appear. The system applies the default permissions initially.
  4. Click the pencil icon for the group to configure group permissions (e.g. Global Collaborator or Administrator), then click Save.

Note:

  • A group will only sync to Gatekeeper from Microsoft Entra once a user has been added to it. 
  • If a user is already synced, and you later update their group’s permissions, the user will automatically inherit the new permissions.

  • When a user belongs to multiple groups, Gatekeeper will:

    • Merge all assigned permissions.
    • Grant the highest privilege level among all groups.

    For example, a user in both Global Collaborator and Global Administrator groups will be assigned Global Administrator, as this is the highest permission.

Manage Groups in Gatekeeper 

Edit Mappings for IdP Groups in Gatekeeper

Once a group has synced from Microsoft Azure, you can manage the permissions that will apply to users in that group. To do this: 

  1. In Gatekeeper, from the navigation menu, expand Settings then click Configuration.
  2. Click System for Cross-domain Identity Management (SCIM).
  3. Click the pencil icon on the relevant group.
  4. Select the groups and permissions required.
  5. Click Save.

View Users in an IdP Group

To view which users have been synced as part of an IdP group:

  1. In Gatekeeper, from the navigation menu, expand Settings then click Configuration.
  2. Click System for Cross-domain Identity Management (SCIM).
  3. Click the name of the IdP Group.

This will display all users belonging to this IdP Group. Click on a user's name to navigate to their user profile page.

Remove Users

Removing a user from the group in Azure will revoke their Gatekeeper access once the sync is complete. Use the Restart Provisioning function in Microsoft Entra to trigger an immediate update.

Revoke the API Key

If you need to rotate the API key, you can remove the current one, ensuring it can never be used again. To do this: 

  1. In Gatekeeper, from the navigation menu, expand Settings then click Configuration.
  2. Click System for Cross-domain Identity Management (SCIM), then click Revoke Key.
    scim_api_key_revoke
  3. Type Revoke as the confirmation phrase, then click Confirm.
    scim_api_key_revoke_confirmation

This process cannot be undone. After revoking the API key, you can generate a new one by clicking Generate API Key.

Troubleshooting

Common Issues

User can't sign in even though they're provisioned:

  • Check if the SAML sync has completed (runs every hour at 45 minutes).
  • Verify the user is assigned to the application in Azure Entra.

Username mapping errors:

  • Ensure the email mapping uses userPrincipalName instead of mail.

Group permissions not working:

  • Remember that groups only appear after the first user is provisioned.
  • Permission changes apply retrospectively to existing group members.

Provisioning not working:

  • Check the provisioning interval (default is 40 minutes).
  • Use Restart Provisioning if needed.
  • Verify the SCIM API Key and Tenant URL are correct.

Best Practices

It's recommended to follow these guidelines to support a successful SCIM configuration:

  • Test with a small group first before rolling out to all users.
  • Document group naming conventions for easier management.
  • Set up an appropriate fallback team in Gatekeeper.
  • Monitor provisioning logs regularly.
  • Rotate your API key periodically by revoking and generating a new key for your SCIM integration.