Configure SCIM in Okta

Step 1: Locate and Verify the SSO Application

To verify the SSO configuration, perform the following steps:

1. Navigate to the Okta Admin Console.
2. On the left navigation menu, go to Applications > Applications.
3. On the Applications page, find your application in the list or use the Search for people, apps, and groups box to find it.
4. Click the application name from your list that you want to configure SCIM for.
   
   
5. Click the General tab.
6. Scroll to the SAML Settings section, and verify that the SAML configuration details match the metadata from your MoEngage workspace.
   
   

Step 2: Enable SCIM in Okta App Settings

Now, to enable SCIM in Okta, perform the following steps:

1. Repeat steps 2 through 5 as mentioned in Step 1.
2. In the App Settings section, click Edit in the right corner.
3. Click the SCIM radio button, and then click Save.
   
   
   The Provisioning tab is displayed next to the Sign On tab.
   
   

Step 3: Configure SCIM in MoEngage and Generate Token

To configure SCIM on MoEngage and generate a token, perform the following steps:

1. On the left navigation menu in the MoEngage workspace, click Settings > Account > Security.
2. On the Security page, click the Login tab.
3. Click Single Sign On (SSO) only.
4. Turn the Enable SCIM Provisioning toggle on.
   
   
5. Copy the Base Connector URL to use in Step 4.
6. In the Default role list, select the required role (Default or Custom role).
7. In the Expiry Date field, select the expiry date for the SCIM access token.
   Note: MoEngage recommends setting the Expiry date to one year.
8. Click Generate Access Token.
   • The Successfully generated SCIM token message and the Generate access token dialog box appear.
   • Note: Copy the token immediately; it is only shown once.
     
9. Click Okay.
   

Step 4: Configure SCIM on Okta

To configure SCIM on Okta, perform the following steps:

1. Return to the Okta Admin Console and click the Provisioning tab.
2. On the left navigation pane, click Integration, and then click Edit.
3. Enter the connection details:
   1. SCIM connector base URL: Paste the URL copied from the MoEngage workspace in Step 3.
   2. Unique identifier field for users: Type email.
4. In the Configure Supported Provisioning Actions section, select the appropriate check boxes to define the data flow. You can enable all five to automate both individual users and groups, or select them based on the following requirements:
   • Import New Users and Profile Updates: Select this to bring existing users from MoEngage into Okta.
   • Push New Users: Select this to automatically create a MoEngage user when a new user is assigned to the application in Okta.
   • Push Profile Updates: Select this to sync attribute changes, such as Role updates, from Okta to MoEngage.
   • Push Groups: Select this to sync Okta groups and their user lists to MoEngage.
   • Import Groups: Select this to fetch existing groups from MoEngage into Okta.
5. In the Authentication Mode list, click HTTP Header.
6. In the HTTP Header section, in the Authorization box, paste the generated access token copied in Step 3 from the MoEngage workspace.
7. Click Test Connector Configuration.
   
   
   
   A Test Connector Configuration dialogue box appears (this process may take up to 30 seconds). The connector configured successfully message appears to review the following list of provisioning features detected in your connector:
   • User Import and Import Profile Updates: This confirms that Okta fetches user data from MoEngage.
   • Create Users and Update User Attributes: This confirms that Okta sends new users and profile changes to MoEngage.
   • Push Groups and Import Groups: This confirms that group memberships and roles are synchronized.

8. Click Close and then Save.
   
   
   

   info

   Information If you do not select Push New Users, MoEngage does not create users for the newly assigned users, and they won't be able to sign in. You can select Push Groups to automatically assign specific permissions to a group of users in MoEngage based on their Okta details, eliminating the need for manual user management.

Step 5: Enable Provisioning Actions

To ensure identity data flows correctly from Okta to MoEngage, you must enable Create, Update, and Deactivate provisioning actions within the To App settings. To enable the provisioning actions, perform the following steps:

1. On the Provisioning tab, in the left navigation pane, under Settings, click To App.
2. Click Edit next to the Provisioning to App section.
3. Select the Enable check box for the following actions:
   • Create Users: Grant Okta permission to create users on MoEngage.
   • Update User Attributes: Sync profile updates from Okta to MoEngage.
   • Deactivate Users: Revoke MoEngage access immediately when a user is unassigned in Okta.
     

Step 6: Create Attribute Mappings

Grant specific write permissions in Okta and map the role attribute to help ensure that users are provisioned with the correct permissions in MoEngage. You must create roles in MoEngage to assign them to users correctly. This attribute mapping helps ensure that users receive their intended access levels rather than the Default role that was configured earlier.

Step 6.1: Configure Profile Attributes

1. Navigate to the Okta Admin Console.
2. On the left navigation menu, click Directory > Profile Editor.
   
3. On the Profile Editor page, find your application in the list or use the Search for people, apps, and groups box to find and select the appropriate application from your list.
   
4. Under the Attributes section, click + Add Attribute.
   
   The Add Attribute dialogue box is displayed.
5. In the Add Attribute dialogue box, configure the following details:
   1. In the Data type list, click string.
   2. In the Display name box, enter role (for example, MoEngage role).
   3. In the Variable name box, enter role (any value can be defined by the client).
   4. In the External name box, enter role (This is the specific name passed within the schema).
   5. In the External namespace, enter urn:ietf:params:scim:schemas:extension:moengage:2.0:User
      
6. Scroll down and set the following:
   1. Attribute required: Select the Yes check box to enforce that a role is provided during the user invitation process in Okta.
      Note: This must be set to Yes. If a user invites an email without a role, MoEngage needs Attribute required to be active so it can fetch the default role from the MoEngage workspace. This ensures both default and custom role scenarios work during testing.
   2. Attribute type:
      • For Individual Assigning: Select the Personal radio button.
      • For Group Assigning (Bulk Update): Select the Group radio button.
7. Click Save.
   
   The MoEngage Role is now established in the application's attribute list.

Step 6.2: Group Creation and Role Updates

To update roles effectively for groups, perform the following sequence:

Step 6.2.1: Create a Group

1. Navigate to the Okta Admin Console.
2. On the left navigation menu, click DirectoryGroups.
3. Click Add group.
   
   The Add group dialog box appears.
   1. In the Name box, enter a group's name.
   2. In the Description box (optional), provide a description.
4. Click Save.
   
5. After the group is created, click it and copy the Group ID from the browser's URL (this is the unique identifier required for mapping logic).
   

Step 6.2.2: Assign Users

1. Within the Groups page, click Assign People.
   
2. Click the + (plus) icon next to each user whose MoEngage roles need to be updated or assigned via this group.

Step 6.2.3: Update Okta User Attribute

1. Navigate to Directory > Profile Editor.
   
   On the Profile Editor page, the All filter is selected by default.
2. Click the Okta filter and click the Okta User (default) profile.
   
3. Scroll to the end of the page and verify whether the role attribute created in Step 6.1 exists. If the attribute is missing, click + Add Attribute.
4. In the Add Attribute dialog box, add a role attribute with the following settings:
   1. In the Data type list, click string.
   2. In the Display name box, enter role.
   3. In the Variable name box, enter role.
   4. In the Description (optional) box, enter a description for the role.
      
   5. In the User permission section, select the Read-Write radio button.
5. Click Save.
   

Step 6.2.4: Update the Application Attribute Mapping

1. In the Profile Editor, click the Apps filter and find your application. 
2. Click Mappings.
   
3. Select the Okta User to [Your Application Name] (for example, Okta User to DC 03) tab.
   
4. Scroll to the role attribute at the bottom of the list.
5. In the expression box, enter the role attribute following logic to map Okta groups to MoEngage roles (isMemberOfGroup("group_id") ? "Admin" : "User").
   1. group_id: Paste the ID copied in Step 6.2.1.
   2. Role: The specific role name as defined in your MoEngage workspace.

6. Confirm and paste that the role attribute details (namespace and external name) for the role attribute match the mandatory values defined in Step 6.1.

7. Click Save Mappings and then click Apply updates.
   

Step 7: Push Groups

Use this option to bulk push entire groups to MoEngage. This triggers the creation of all group members in the MoEngage workspace at once.

1. Click the Push Groups tab.
2. Click + Push Groups > Find groups by name.
   
3. Under Push groups by name, in the Enter a group to push field, enter the name of the group assigned to the MoEngage workspace.
4. Ensure the Push group memberships immediately check box is selected.
   
5. Click Save. Okta initiates a background job to sync all members.

Step 8: Final Force Synchronization

Manual force sync ensures that mapped properties and roles are updated instantly across all assigned users.

1. Click the Provisioning tab, and in the left navigation pane under Settings, click To App.
2. Scroll down to the Attribute Mappings section.
3. Click Force Sync.
   
   This initiates a global synchronization, pushing the newly mapped attribute data immediately and ensuring global attributes are in sync. Individual user sync via the Assignments tab is not required separately as Force Sync covers all assigned users.

Step 9: Validation 

Verify the following in the MoEngage workspace (Settings > Account > Team Management):

• User Invitation: Confirm the user is successfully invited and the status is Joined.
  
• Default Role Update: Confirm that if no specific role was passed from Okta, the system correctly assigned the Default Role configured in Step 3.
• Role Accuracy: Confirm that the specific role sent from Okta (based on group membership logic) matches the assigned role in the workspace.