Introduction
This guide provides detailed instructions for setting up SCIM (System for Cross-domain Identity Management) provisioning between your Okta Identity Provider (IdP) and Rhythms. Successful configuration will enable automated user lifecycle management (creation, updates, deactivation) and synchronization of user profile information, including both standard and custom attributes.
This document expands on Step 3: Configure SCIM with Your IdP from the general "Setting Up SCIM for User Provisioning and Profile Synchronization in Rhythms" guide. It's recommended to be familiar with the general SCIM concepts in Rhythms outlined in that overview. Rhythms' SCIM integration is facilitated by WorkOS. Some credentials or API endpoints mentioned in this guide will be obtained through the WorkOS-powered SCIM setup wizard, which you will initiate from your Rhythms AI admin settings.
The key focus of this guide is to walk you through connecting Okta to Rhythms, mapping standard profile attributes, and specifically detailing how to configure custom field synchronization to ensure comprehensive user profiles in Rhythms.
Prerequisites
Before you begin, ensure you have the following:
For the Rhythms Administrator (or a team member with equivalent permissions):
Access to the Rhythms AI admin portal to initiate the Directory Sync setup and retrieve SCIM credentials.
SCIM Endpoint (Base URL) and Bearer Token (API Token): These will be generated when you initiate the Directory Sync setup within Rhythms AI
For the Okta Administrator:
Administrator access to your Okta organization with permissions to:
Create and manage applications.
Configure provisioning and attribute mappings for applications.
Manage Okta Universal Directory user profiles and attributes (if adding new custom attributes to Okta).
A list of any custom attributes you wish to sync from Okta to Rhythms, along with the corresponding SCIM "External name" and "External namespace" values expected by Rhythms (this information will be available during the WorkOS-powered setup process or from Rhythms support).
Setup Steps
Follow these steps to configure SCIM provisioning between Okta and Rhythms. Before this follow instructions in "Setting Up SCIM for User Provisioning and Profile Synchronization in Rhythms" guide and get to the Okta configuration screen
Step 1: Add the Rhythms Application in Okta
Log in to Okta , go to the Okta admin dashboard and select “Applications” in the navigation bar.
If you haven’t created a SCIM application in Okta, select “Browse App Catalog”. From your Okta Application dashboard, search for “SCIM 2.0 Test App (OAuth Bearer Token)” and select the corresponding result.
On the following page, click “Add Integration”.
Enter a descriptive App name, then click “Next” (e.g. "RhythmsAI).
Many applications will work with the default configuration that is set on your new application. Click “Done” to complete creating your application.
Step 2: Configure SCIM API Integration in Okta
Open the Rhythms application you just added in Okta. Go to the Provisioning tab. Click Configure API Integration.
Select Enable API integration. After that, copy and paste the Endpoint from your Rhythms/WorkOS SCIM setup wizard in the SCIM 2.0 Base URL field. Then, copy and paste the Bearer Token from your Rhythms/WorkOS SCIM setup wizard into the OAuth Bearer Token field.
Click “Test API Credentials”, and then click “Save”.
Step 3: Select options to provision to your application
In the “To App” navigation section, check to enable: Create Users Update User Attributes Deactivate Users Click “Save”.
Step 4: Assign Users and Groups
Navigate to the Assignments tab of the Rhythms application in Okta.
Click Assign and choose Assign to People or Assign to Groups.
Select the users or groups you want to provision to Rhythms.
Only users assigned to the application (either directly or via group membership) will be provisioned or have their profiles synced to Rhythms.
When assigning,
Confirm assignments.
Step 5: Configuring user attribute mappings
For any custom attributes that needs to be sent to the application, some configuration may be required in Okta. Below is a guide on configuring user attribute mappings, so they propagate via SCIM.
Viewing application attributes - From the Okta administrator portal, navigate to Directory → Profile Editor, and find the application for which you’d like to edit mappings.
Clicking into the application will bring you to a Profile Editor page. You’ll likely see several attributes listed, which are scoped to the application.
Adding an attribute - If a desired attribute is missing from your application, click the “Add Attribute” button to create a new attribute.
Enter a display name and variable name of your choosing, and note the name so you can add to custom_field name in the WorkOS wizard.
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User. Once you’ve entered the required information, click “Save”.
Mapping an attribute: For example if you want to push additional attributes pulled from HRIS system into Okta to be sent the Rhythms App you can map the field from Okta to the newly created custom attribute.
To map Okta user profile attributes to your application users, click on the “Mappings” button.
Find the name of the attribute you’d like to map in the right column. In the corresponding row’s left column, enter the name of the Okta user profile attribute you’d like to map over.
Ensure the apply mappings setting is set to “Apply mapping on user create and update”. These new attribute mappings will now propagate to the application.
Testing the Okta SCIM Integration
Thorough testing is crucial after configuration:
Provision a New User:
Assign a new test user (who doesn't exist in Rhythms) to the Rhythms application in Okta.
Wait a few moments (Okta's processing time can vary).
Check the Rhythms admin portal ("Users" section) to verify the user has been automatically created.
Confirm all mapped standard and custom attributes are correctly populated in Rhythms.
Update a User's Profile:
For the test user, update a mapped attribute in their Okta profile (e.g., last name, department).
Wait for the sync to occur.
Verify in Rhythms that the user's profile reflects the changes. Test both standard and custom attributes.
Deactivate a User:
Unassign the test user from the Rhythms application in Okta, or deactivate the user in Okta (depending on your offboarding process).
Verify that the user's access to Rhythms is revoked or their account is deactivated in Rhythms according to your SCIM configuration.
Check Okta Logs: Review the Rhythms application logs in Okta (Reports > System Log or from the app's dashboard) for any provisioning errors or successful events.
User Experience with SCIM (via Okta)
Once SCIM is active and configured correctly:
Automated Provisioning: New users assigned to the Rhythms app in Okta are automatically created in Rhythms, with their mapped profile attributes (standard and custom) populated.
Profile Synchronization: Changes made to mapped user attributes in Okta are automatically updated in the corresponding Rhythms user profiles.
Automated Deprovisioning: When users are unassigned from the Rhythms app in Okta or deactivated in Okta, their Rhythms accounts are automatically deactivated or access revoked, ensuring timely removal of access.
Seamless Onboarding: Combined with SSO, newly provisioned users can typically log in to Rhythms immediately using their Okta credentials without manual account setup in Rhythms.
Best Practices for Okta SCIM Setup
Plan Your Attribute Mapping: Before configuring, clearly define which Okta attributes (standard and custom) need to map to which SCIM attributes in Rhythms.
Start with a Test Group: Initially assign only a small group of test users to the Rhythms application to verify provisioning, attribute mapping (especially custom fields), and de-provisioning before rolling out to all users.
Incremental Rollout: After successful testing, consider rolling out assignments to larger groups incrementally.
Regularly Monitor Okta Logs: Check Okta's system logs for the Rhythms application periodically for any SCIM provisioning errors or warnings.
Secure API Token: Treat the SCIM API Token from Rhythms/WorkOS as sensitive. Store it securely and regenerate it if compromised.
Troubleshooting Common Okta SCIM Issues
API Authentication Errors:
Verify the SCIM Base URL is correct.
Ensure the API Token is accurately copied from Rhythms/WorkOS and is active.
Check for any IP restrictions or firewall rules on either end.
Attribute Mapping Not Working:
Double-check the exact spelling and case of SCIM attribute names (including full URN for schema extensions) in Okta's mapping configuration.
Ensure the Okta attributes actually contain data for the users you are testing.
Confirm the data types are compatible between Okta and the Rhythms SCIM attributes.
Check Okta logs for specific error messages related to attributes.
Users Not Being Provisioned/De-provisioned:
Confirm users are correctly assigned to (or unassigned from) the Rhythms app in Okta.
Ensure the "Create Users," "Update User Attributes," and "Deactivate Users" options are enabled in the "To App" provisioning settings in Okta.
Look for any filters or rules in Okta that might be preventing provisioning for certain users.
Frequently Asked Questions (FAQ)
Q: How do I get the SCIM Base URL and API Token for Rhythms?
A: These credentials are provided through the SCIM setup wizard in your Rhythms admin portal, typically under Settings > Security > Directory Sync (SCIM). This process is usually facilitated by WorkOS.
Q: Can I map custom attributes from Okta that are not part of the standard Okta user profile? A: Yes. First, you'll need to add the custom attribute to your Okta Universal Directory user profile. Then, you can map this custom Okta attribute to the corresponding SCIM attribute that Rhythms expects
Q: Does this SCIM integration sync user roles from Okta to Rhythms? A: Typically, SCIM focuses on user identity and profile attributes. Role assignments within Rhythms are usually managed separately via Rhythms' own Role-Based Access Control (RBAC) system. Check Rhythms documentation for how roles are best managed.
Q: How often does Okta sync attributes to Rhythms via SCIM?
A: Okta typically processes provisioning tasks in near real-time or within a few minutes for individual changes. For large bulk updates or initial assignments, it might take longer. Consult Okta documentation for specifics on their SCIM processing times.