Configure SCIM for Okta

   Take Control

   Estimated Read Time: 15 minutes

Sections in this article:

• What is SCIM?
  • Supported SCIM Operations
• Configuration
  • Permissions Required for Setup

  • Step 1: Set the Fallback Team and Mapping

  • Step 2: Set Up the Application in Okta

  • Step 3: Configure Okta SSO

  • Step 4: Configure SCIM Provisioning

  • Step 5: Adjust User Mapping

  • Step 6: Assign Users or Groups

  • Step 7: Verify Provisioning in Gatekeeper

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

Supported SCIM Operations

• User provisioning (Create, update, and delete)
• User activation and deactivation
• User profile synchronisation
• Group push (Create, update, and delete)

Configuration

Permissions Required for Setup

To follow the steps, you’ll need:

• An Okta account.
• Appropriate admin roles in Okta (i.e. to create applications and manage group assignments).
• 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

Additionally, you can control the default email report preferences applied when a user is first provisioned via SCIM. To manage this, enable or disable the Owned by Me and All Reports toggles as required.

Step 2: Set Up the Application in Okta

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

1. Log in to the Okta Admin Console.
2. Navigate to Applications.
3. Click Browse App Catalog.
4. Search for Gatekeeper
5. Click the official Gatekeeper Okta application.
6. Click Add Integration.
7. Fill in the following required fields:
   1. Application Label: Give the application a meaningful name.
   2. GK Region: Enter the region value from your tenant's URL. This field is case-sensitive. Available values are: apac (Asia-Pacific), ca (Canada), eu (EMEA), us (United States). For example, the value from https://eu.gatekeeperhq.com/3222/executive-dashboard is eu.
   3. Tenant ID: Enter the numeric ID from your tenant's URL. Ex: the value from https://eu.gatekeeperhq.com/3222/executive-dashboard is 3222.
8. Click Done.

Step 3: Configure Okta SSO

To enable user login using Okta, you must configure the Okta SSO Application and Gatekeeper. To do this, follow the instructions in Configure Okta SSO.

 Step 4: Configure SCIM Provisioning

With SSO configured, the next step is to set up SCIM provisioning to automate user management between Okta and Gatekeeper.

1. In  your Gatekeeper tenant, from the navigation menu, expand Settings then click Configuration.
2. Click System for Cross-domain Identity Management (SCIM), then click Generate API Key.
3. Copy the API Key. For security reasons, you won't be able to view the key again after clicking Copy & Save.
4. Return to Okta, then navigate to the Provisioning tab and click Configure API Integration.
5. Configure the settings as follows:
   1. Enter the generated API Key into the API Token field.
   2. Deselect the Import Groups checkbox
   3. Click Test API Credentials.
6. From the Provisioning tab, navigate to To App to configure the following settings, then click Save:

1. 1. Enable Create Users.
   2. Enable Update User Attribute.
   3. Enable Deactivatre Users.
   4. Disable Sync Password. Users will use SSO to log in.

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

1. Click Go To Profile Editor.
2. Click Add Attribute.
3. Enter the required information:
   1. Display Name: Enter a meaningful name, ex: Gatekeeper Teams.
   2. Variable Name: Used internally for Okta only. This should generate automatically.
   3. External name: teamName. This name is case sensitive.
   4. External namespace: urn:ietf:params:scim:schemas:extension:gatekeeper:2.0:User.
   5. Description: Enter additional information if required.
   6. Attribute type: Select Personal.
4. Click Save.
5. Click Mappings.
6. Click the Okta User to Gatekeeper App tab (this may display as the name you called your application in Step 2: Set Up the Application in Okta).
7. Map user.department on the Okta side with GKTeamName (or the name of the variable created in the previous step) on the Gatekeeper side.
8. Click Save Mapping, then click Apply Updates.

Step 6: Assign Users or Groups

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

Step 7: Verify Provisioning in Gatekeeper

After assigning users or groups in Okta, 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.