Configuring SCIM Provisioning with Okta

SCIM (System for Cross-domain Identity Management) lets you automatically provision, update, and deprovision Sprout Social users directly from Okta. Instead of managing users manually in Sprout, your IT or Sprout admin team controls access from Okta and keeps Sprout in sync automatically.

Before You Begin

You’ll Need:

• Account Owner role, or the Manage Single Sign-On permission + API permissions (to create API Tokens in Sprout)
• Admin access in Okta
• The Sprout Social app installed in your Okta tenant
• SSO already configured on the Sprout Social app in Okta — SCIM provisioning builds on top of an existing SSO connection
• To ensure you’re using Sprout Organizational Roles and Profile Permission Sets - Legacy roles are not supported for SCIM.

This Guide will cover:

• Prerequisites to configuring SCIM for Sprout
• Enabling SCIM as a feature in Sprout
• Configuring SCIM for Sprout in Okta
• Testing/Go Live
• Managing Users once SCIM is enabled
• Troubleshooting

1: Prerequisites to configuring SCIM for Sprout

Required Org Roles and Profile Permission Sets must exist in order for users to be provisioned with them, therefore these should be set up first. Legacy roles are not supported. 

Before enabling SCIM in "Live" mode, we recommend removing all manually-assigned Roles and Profile Permission Sets for users that will be managed by SCIM. 

SCIM enforces one role per category (Organization Role and Permission Set) - if a user already has a different role assigned in the same category, SCIM will not be able to assign the new one and you'll get a sync error.

1a. Review the Preset Org Roles and Create custom roles if needed. 

If your organization needs roles beyond Sprout's defaults, create them first:

1. Go to Settings > Users & Social Profiles > Roles
2. Create your custom roles and assign appropriate permissions

1b. Create Profile Permission Sets (PPS)

Profile Permission Sets control what actions users can take on social profiles (publish, reply only, needs approval, etc.):

1. Go to Settings > Users & Social Profiles > Profile Permission Sets
2. Create a PPS for each access tier you plan to map from Okta

Note: Name your roles and PPS carefully — you'll need to match these names exactly when configuring group mappings in Okta. A mismatch will cause mapping errors.

More details Sprout Org Roles and Profile Permission Sets and how to create them can be found in our Help Center:

• Roles
• Permissions

1c. Setup/Review Groups in Okta to ensure they align with the Organizational Roles and Profile Permission Sets

These are general instructions related to setup in Okta to illustrate mapping between the apps. Okta can change or your organization’s setup could be different, so please be sure to refer to Okta official help documentation for more detailed guidance on setting up Groups. 

Group Management in Okta Classic

Group Management in Okta Identity Engine

In Okta, go to Directory > Groups and create one group per Organizational Role and one group per Profile Permission set. For example:

Roles:

• Sprout_SuperAdmin
• Sprout_SocialMediaManagers
• Sprout_ContentCreators
• Sprout_CareAdmins
• Sprout_CustomCare

Profile Permission Sets

• Sprout_allpermissions
• Sprout_SocialmediamgmtPPS
• Sprout_contentcreationPPS
• Sprout_careadministrationPPS
• Sprout_customcarePPS

Groups can map to either an Org Role or a Profile Permission Set or both. Keep in mind that only one Org Role and one PPS can be assigned to a user via SCIM. Assigning a user to two groups that both map to a role (or both map to a PPS) will cause a sync error.

If different users need the same Org Role but different Profile Permission Sets, create separate groups: one group for the Org Role (all users are members), and one group per PPS (each user is added to the PPS group matching their needs). For example, if all content team members need the 'Content Creators' Org Role but some need a 'Publish' PPS while others need a 'Needs Approval' PPS, create three groups: one for the role, one for each PPS

The user will always be assigned to the Org Role and/or PPS mapped to their Okta group as long as SCIM is enabled. This means if you make changes to those directly in the Sprout app but *not* in Okta, their Okta Group’s associated Org Role/PPS will be reassigned again in the next sync.

Note: If someone has custom permissions set up in Sprout (permissions outside the standard Roles and Permission Sets), they should not be added to any Okta or Entra group that's mapped to Sprout. Doing so will cause a sync error. These users need to be managed manually in Sprout instead.

1d. Create users and assign them to groups

In Directory > People, create your users and assign each to their appropriate group.

For detailed instructions on how to do this, please refer to Okta’s help documentation. 

User Management in Okta Classic
User Management in Okta Identity Engine

2: Enable SCIM as a feature in Sprout

1. Go to Settings > Authentication & Provisioning>Identity Provider Integrations (tab)
   
2. Select Enabled Via SCIM and click Start Configuring SCIM

3. In the configuration wizard, expand Section 1 to find your SCIM Endpoint URL and link to the API page where you can create an API token.

4. On the API page, click generate API. Give the token a descriptive name and click Create Token.

5. There are icons to copy the SCIM Connector Base URL and the API token to your clipboard - you’ll need to paste both of those when configuring SCIM in Okta, next.  
   

6. The steps in Section 2 must be done in Okta because this is where your organizational SCIM groups are centralized and your users will be managed. Mapping Okta Groups to Sprout Roles and Profile Permission sets is what ensures that Okta and Sprout remain in sync. 
7. In Section 3, you can leave SCIM in Test Mode. What the modes mean:

SCIM has two modes: Validate and Live. Validate is where you set everything up and confirm your connection works, no real users are created or changed yet, so it's safe to test. Live is when SCIM actually starts creating, updating, and removing users based on what your IdP tells it. 

Before enabling SCIM in "Live" mode, we recommend removing all manually-assigned Roles and Profile Permission Sets for users that will be managed by SCIM. 

SCIM enforces one role per category (Organization Role and Permission Set) - if a user already has a different role assigned in the same category, SCIM will not be able to assign the new one and you'll get a sync error.

3: Configure SCIM Provisioning in Okta

3a. Enable SCIM on the Sprout app

1. Open the Sprout Social app in Okta and go to the General tab
2. Click Edit, select SCIM as the provisioning type, and click Save
3. A new Provisioning tab will appear — go there

3b. Connect Okta to Sprout

1. Under Provisioning > Integration, click Edit
2. Enter the SCIM Connector Base URL and OAuth Bearer Token from Step 2
3. Enter the Unique Identifier for users (userName) and check the provisioning actions that you want enabled.
4. Authentication Mode should be HTTP Header and when you select that, paste in the API token you generated in Sprout in the Authorization : Bearer field.
5. Click Test Connector Configuration - A successful test will return a green confirmation showing the capabilities Sprout supports. If you see an error, return to Settings > Authentication & Provisioning in Sprout and switch to Test or Live mode before retesting.

Success Message:

Example Error:


 

3c. Enable provisioning actions

Under Provisioning > To App, click Edit and enable:

• Create Users
• Update User Attributes
• Deactivate Users

All three are required. If any are disabled, the corresponding actions will fail silently in Okta — users won't be created, updates won't sync, or deactivations won't process.

On attribute mapping: Sprout stores a limited set of user attributes — first name, last name, email, and username. Default Okta mappings may include fields like locality, employee number, cost center, and organization that Sprout doesn't use. We recommend cleaning up the attribute mapping to only include the fields Sprout supports to avoid unnecessary sync noise.

📎 Okta documentation: Attribute mapping

3d. Map Okta Groups to Sprout Roles and Profile Permission Sets (via Push Groups)

This is the most critical step. Group Push sends your Okta groups to Sprout via SCIM. When configuring Push Groups, you set the remote group name - this is the displayName Sprout receives and uses to look up the matching Org Role or Profile Permission Set. This name must exactly match (case-insensitive) a role or Profile Permission Set name in Sprout.

If a group name in your IdP doesn't exactly match the Role or Permission Set name in Sprout, the mapping won't work. You'll see an error on the IdP side (Okta or Entra) right away. On the Sprout side, there's no visible error, the group will just silently fail to assign a role, but the failed sync is recorded in the logs. If a user isn't getting the expected role and nothing looks wrong in Sprout, check the IdP for a sync error first, and pull the Sprout audit log if you need to confirm it from the Sprout side.

1. In the Sprout Social app in Okta, go to Push Groups and select find group by name
2. For each group, configure the mapping to the corresponding Sprout Org Role or PPS. You can see in the group list the group name in Okta and its corresponding Sprout name when you’ve completed the mappings.

You’ll also want to make sure that the “Rename Groups” box is unchecked in the Push Group Settings (if the box is checked, Okta will overwrite the Sprout Role or PPS name with the Okta name and the push will fail):

Here’s an example mapping using the example groups mentioned in Step 2:

Example Assignments:
User Carl Cramer is a Content Creator. In Sprout, you have a content creator Organizational Role as well as a Profile Permission Set that has the right profile permissions for all content creators in your organization. Carl should be added to both the Sprout_ContentCreators group in Okta, as well as the Sprout_ContentCreationPPS group. Both each of those groups would be mapped in Push Groups to their corresponding Sprout role and profile permission set. 

Important: The Role and PPS names you enter here must exactly match what exists in Sprout. If the name doesn't match, the mapping will fail and you'll see an error indicating the role or permission set wasn't found on Sprout's side.

📎 Okta documentation: Group Push

4: Test, Then Go Live

Before enabling SCIM in "Live" mode, we recommend removing all manually-assigned Roles and Profile Permission Sets for users that will be managed by SCIM. 

SCIM enforces one role per category (Organization Role and Permission Set) - if a user already has a different role assigned in the same category, SCIM will not be able to assign the new one and you'll get a sync error.

4a. Verify the connection with a test user

Before assigning all groups, assign a single user to the Sprout app to confirm the connection works as expected. Since you're still in Test mode, no user will actually be created in Sprout — but you can check the audit log in Sprout (Settings > Authentication & Provisioning > Export Audit Logs) to confirm a successful sync event was recorded. You can also verify success on the Okta-side by viewing the Okta logs.

In Sprout: 

In Okta:

4b. Switch Sprout to Live mode

1. In Sprout, go to Settings > Authentication & Provisioning
2. Change the provisioning mode from Test to Live and confirm.

4c. Assign the Sprout app to all groups

In Okta, go to the Sprout Social app > Assignments and assign the app to each of your Sprout groups. This triggers bulk provisioning — all group members will be created in Sprout with their mapped roles and PPS.

Once complete, check Settings > Users & Social Profiles > Team Members in Sprout to confirm users appear with the correct roles and permissions assigned.

5: Managing Users After Setup

5a. Changing a user's role or permissions

Update group membership in Okta — Sprout syncs automatically, typically within seconds.

Example: To promote a content creator to a social media manager:

1. Remove the user from Sprout_ContentCreators in Okta
2. Add them to Sprout_SocialMediaManagers
3. Sprout will update their Org Role automatically
4. Remove the user from Sprout_ContentCreationPPS
5. Add the user to Sprout_SocialMediaMgmtPPS
6. Sprout will update their Profile Permission Set automatically

5b. Offboarding a user

Deactivate the user in Okta, or remove them from the Sprout app assignment. Sprout will lock or remove the user automatically — no action needed in Sprout.

When a user is deactivated in Okta they are not pushed to the downstream app (Sprout), so the user will remain assigned to an Org role or PPS even if they are removed from the push group in Okta. 

More details: https://support.okta.com/help/s/article/Group-Push-Common-Issues?language=en_US

5c. Adding a new user

Add the user to the appropriate Okta group and assign them the Sprout app. Sprout provisions the account automatically. You should ensure that you do not assign more users to Sprout than available user seats.

6: Common Errors & Troubleshooting

What happens if you switch to Live too early (Validate → Live recovery)

If a user or group seems 'stuck' after switching from Validate to Live on Okta, here's what to do:

A group won't sync because of an old/stale member: Remove that member from the group in Okta. The next sync will go through right away; you don't need to fix the member first.

A single user is stuck: Unassign them from the Sprout app in Okta, then reassign them. Okta will re-check them by username and create them properly. Do this one user at a time.

Don't bother clicking Retry, and don't try editing the user's profile; neither one fixes this. Retry is the button an admin will reach for first, so it's worth calling out directly that it won't help here.

Deactivating a stuck user also won't work while they're in this state; removing them from the app just looks like a failed lookup to us, not a deactivation. Use the unassign/reassign steps above instead."

Group mapping fails with "role not found" or similar error

The name you entered in the Okta group mapping doesn't match any Org Role or PPS in Sprout. Check the exact names of your Org Roles and PPS in Sprout (Settings > Users & Social Profiles) and update the mapping in Okta's Push Groups tab to match precisely.You can use both the Okta and Sprout audit logs to further troubleshoot issues if you continue to see an error message.

Sync fails with a "duplicate assignment" error

A user has been added to two Okta groups that both map to the same type of Sprout attribute — either two groups that map to an Org Role, or two groups that map to a PPS. Sprout only supports one Org Role and one PPS per user. Review the user's group memberships in Okta and ensure they belong to only one role-mapped group and only one PPS-mapped group.

Users were provisioned but have no roles or permissions assigned

Users will appear in Sprout immediately after the app is assigned to groups, but role and PPS assignment happens in a second step when Okta pushes the group configurations. If users appear without roles, wait for the group push to complete (this can take up to a minute) and then refresh the Team Members page in Sprout.

Users aren't being created in Sprout after group assignment

Check the following in order:

1. Is Sprout in Live mode? Users are not created in Test mode.
2. Is Create Users enabled under Provisioning > To App in Okta?
3. Is the Sprout app assigned to the groups, not just individual users?
4. Do your API credentials still work? Run Test Connector Configuration in Okta to verify.

A deactivated user in Okta is still active in Sprout

Deactivate Users is not enabled under Provisioning > To App in Okta. Enable it, then deactivate the user again to trigger the sync. This could also be related to a sync error that should be visible in the Okta logs or as an admin task.

Updates to a user's role or permissions aren't syncing

Update User Attributes may not be enabled under Provisioning > To App. Enable it, then trigger a re-sync by removing and re-adding the user to the relevant Okta group.

7: FAQ

Can I use SCIM and manage some users manually at the same time? Yes. SCIM only manages users provisioned through it. Users created manually in Sprout before SCIM was enabled will not be affected unless explicitly linked to an Okta account.

What happens to manually-created users once SCIM is live? Existing manual users remain unchanged. If their email in Okta matches their email in Sprout, Sprout will link the accounts on the next sync and SCIM will take over management of that user. If that user has a Role or Profile Permission Set in Sprout when SCIM is enabled, there will be a sync error. All SCIM-managed users should have their Roles/Permissions removed before enabling SCIM, so that they can be assigned via SCIM.

Can a user belong to multiple Sprout groups in Okta? Yes, but with constraints. A user can be in one role-mapped group and one PPS-mapped group simultaneously — this is the intended way to assign both attributes independently. However, placing a user in two role-mapped groups or two PPS-mapped groups will cause a sync error.

How do I switch from JIT provisioning to SCIM? Go to Settings > Authentication & Provisioning in Sprout, disable JIT, and follow the SCIM setup steps above. Existing JIT-provisioned users will be matched by email when SCIM first syncs and won't be duplicated.

Do I need to map every default Okta attribute to Sprout? No — and we recommend you don't. Sprout only uses first name, last name, email, and username. You can remove other default attribute mappings (locality, employee number, cost center, organization, etc.) in Okta to keep your configuration clean and avoid unnecessary sync noise.

How long does a sync take after making a change in Okta? In most cases, changes sync within a few seconds to about a minute.  Bulk provisioning operations (assigning many groups at once) may take longer — wait a minute and refresh before assuming something went wrong.This timing is set and controlled by Okta, not Sprout, so if there are any issues, we recommend you consult Okta documentation or Okta Support.