Configure SCIM for Microsoft Entra

   Take Control

   Estimated Read Time: 8 minutes

---

Sections in this article:

• What is SCIM?
• Configuration
  • Permissions Required for Setup
  • Step 1: Set the Fallback Team and Mapping
  • Step 2: Set Up the Enterprise Application in Microsoft Azure
  • Step 3: Configure SAML Single Sign-On (SSO)
  • Step 4: Configure SCIM Provisioning
  • Step 5: Adjust User Mapping
  • Step 6: Assign Users or Groups
  • Step 7: Verify Provisioning in Gatekeeper
• Manage Groups in Gatekeeper 
  • Edit Mappings for IdP Groups in Gatekeeper
  • View Users in an IdP Group
  • Remove Users
• Troubleshooting

---

 

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 to securely synchronise user data with Gatekeeper, helping to ensure consistency and reduce manual tasks. 

Configuration

Permissions Required for Setup

To follow the steps in this article, you’ll need:

• An Azure Entra tenant with admin permission to create enterprise applications and manage group assignments (i.e. Application Administrator and Groups Administrator).
• 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 Fallback Team and Mapping

The fallback team is where users will be assigned if their groups or permissions are deleted. 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.
   
   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 customappsso Attribute: emails[type eq "work"].value. By default, this is mapped to the mail attribute.
   
3. Click Edit, then select userPrincipalName from the Source attribute instead.
   
4. Save the configuration.

You'll also need to create a custom attribute to map the user's team.

1. To create a custom attribute, at the bottom of the Attribute Mapping page, select the Show advanced options checkbox.
2. Click Edit attribute list for customappsso.
3. Add a new attribute using the following value: urn:ietf:params:scim:schemas:extension:gatekeeper:2.0:User:teamName
   
4. Click Save, then return to the Attribute Mapping page.
5. Locate the department mapping, then delete it.
6. Create a new mapping, then map the department attribute, or the relevant IdP profile attribute you are using for Gatekeeper teams, to the new target attribute.
   

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.

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.

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 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.

Troubleshooting

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

• Verify the user is assigned to the application in Azure Entra.

Username mapping errors:

• Ensure the email mapping uses userPrincipalName instead of mail.

Provisioning not working:

• Check the provisioning interval (default is 40 minutes).
• Use Restart Provisioning if needed.