Introduction to SCIM Integration with Gatekeeper

   Take Control

   Estimated Read Time: 8 minutes

---

Sections in this article:

• What is SCIM?
  • How it Works
• Set the Fallback Team and Access Mapping
• Access the Base URL and API Key
• User Profile Attributes Supported by Gatekeeper
  • Team Attribute
• Manage Groups in Gatekeeper
  • View Users in an IdP Group
• Revoke the API Key
• Troubleshooting
  • Common Issues
  • Best Practices
• FAQ

---

What is SCIM?

SCIM (System for Cross-domain Identity Management) is an open standard designed to automate the provisioning and management of users between identity providers (IdPs) and Gatekeeper. When a user is added, updated, or removed in your IdP, SCIM automatically reflects those changes in Gatekeeper, without the need for manual administration. This keeps user access and permissions in sync across both systems.

How it Works

• Your IdP acts as the source of truth. You connect it to Gatekeeper using the Gatekeeper Base URL and a SCIM API key.
• You can connect Gatekeeper to any identity provider that supports SCIM (e.g. Okta, Entra, OneLogin). If you use Microsoft Entra, follow the steps in the Microsoft Entra configuration guide.
• Provisioning flows from your IdP to Gatekeeper. When someone is added, updated, or removed in your IdP, SCIM tells Gatekeeper to create, update, or revoke access for that user.
• User permissions come from your mappings. Gatekeeper applies the mappings you set. If there is no match, the user is assigned to a fallback team with default access.
  • Gatekeeper merges permissions when a user belongs to multiple groups, granting the highest permission level.

• When users are provisioned using SCIM, the user's email will be checked to see if it already exists in Gatekeeper. 
  • If the email already exists, your IdP links to that account and continues to manage it going forward.
  • If it does not, a new user will be created in Gatekeeper.

Set the Fallback Team and Access Mapping

The fallback team acts as a safety net for user provisioning in Gatekeeper. If a user is provisioned through SCIM but their assigned team or group mapping in your IdP is missing, deleted, or not yet synced, Gatekeeper automatically places them into this fallback team.

It’s recommended to assign minimal permissions to the default fallback team. 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.

Access the Base URL and API Key

The Base URL and API Key are the two core credentials that enable your IdP to communicate securely with Gatekeeper via the SCIM protocol. You will need these when configuring the connection. To locate your credentials:

1. From the navigation menu, expand Settings then click Configuration.
2. Click System for Cross-domain Identity Management (SCIM).
3. Copy the Base URL, then click Generate API Key.
   
4. Copy the API Key. For security reasons, you won't be able to view the key again after clicking Copy & Save.
   

User Profile Attributes Supported by Gatekeeper

Gatekeeper uses SCIM to synchronise user attributes that determine the account details, team membership, and user access. See the table below for a breakdown of the supported attributes:

Attribute	Description	Notes
email	User's email address	Acts as the unique identifier for matching and updating user records in Gatekeeper, so cannot be changed.
first name	User’s given name
last name	User’s surname
team	The department the user belongs to	This must match the team name in Gatekeeper exactly. This is case sensitive.
active	Indicates whether a user’s Gatekeeper access is enabled (true), or revoked (false)

Team Attribute

To map an IdP field (such as department or team) to the user’s team field in Gatekeeper, use one of the following formats:

Attribute: urn:ietf:params:scim:schemas:extension:gatekeeper:2.0:User:teamName

OR

Name: urn:ietf:params:scim:schemas:extension:gatekeeper:2.0:User

Namespace: teamName

Manage Groups in Gatekeeper

After your first sync, groups created in your IdP will appear automatically in Gatekeeper. To manage the permissions that will apply to users in that group: 

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

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.
   
3. Type Revoke as the confirmation phrase, then click Confirm.

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 your SAML or authentication settings.

Team mapping issues:

• Ensure the team or department name in your IdP matches the team name in Gatekeeper exactly. This mapping is case sensitive.

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:

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

FAQ

Q: What happens if I created users directly in Gatekeeper before implementing SCIM?

A: As long as the same email is used for existing users, it will get updated by SCIM. When users are provisioned in your IdP using SCIM, your IdP performs a check to see if the user's email already exists in Gatekeeper.

• If it does, your IdP should internally map it in its system and manages the existing Gatekeeper users going forward.
• If it does not, your IdP creates a new user in Gatekeeper.

Q: We set up SAML before SCIM. Do we need to repeat the setup process?

A: No, SAML and SCIM are separate functions. SCIM manages user provisioning and access, while SAML handles user authentication.

Q: What Gatekeeper user attributes sync via SCIM?

A: The following attributes are synced:

• email (this cannot be changed)
• first name
• last name
• team
• active (i.e. whether the user's access to Gatekeeper is revoked or not)

Q: Does Gatekeeper support nested groups?

A: Nested groups are not currently supported in Gatekeeper.

Q: Are invitation emails sent when a user is provisioned via SCIM?

A: Gatekeeper does not send an invitation email when a user is provisioned via SCIM. The user can access the platform without needing to activate their account.