How do I add a role attribute to the SAML assertion that comes from my Identity Provider?

Dynamic Role Sync streamlines onboarding and provisioning for Sprout users. It improves access security. It lets your Identity Provider (IdP) assign users their Sprout role based on their group/role in the IdP. When a user logs into Sprout via SSO, they are assigned whatever Organizational Role and/or Profile Permission Set is linked to their Role/Group assignment in the IdP.

The system achieves this by using the SAML assertion that the IdP sends over during SSO. Many IdPs let you map groups/roles to custom attributes. You can choose one Sprout Organizational Role and/or Profile Permission Set to assign to a role or group in the IdP. When the IdP updates a user's group, their Sprout role/profile permission set updates at their next SSO login accordingly.

How-to set up Dynamic Role Sync

1. Check the SAML assertion sent to Sprout from your IdP. Ensure it has no existing role attribute (from previous testing) included. Once DRS is enabled, this could cause errors or wrong role assignments.
    
2. Submit a ticket to Sprout Support and ask them to enable the Dynamic Role Sync feature.
    
3. Configure your IdP once our Support team confirms the feature has been enabled. Add the Organizational Role (orgRole) and/or Profile Permission Set (profileRole) attribute to the user's SAML assertion. Then, map the Group/IdP role to the Sprout role/profile permission set. Each IdP has its own method for this. So, please check your IdP's documentation for support and setup instructions. 
    
4. Send the following in the SAML to assign the roles correctly in Sprout:
   • The role attribute must be named one of these: orgRole or profileRole.
   • The role name in the attribute must match Sprout's, including case and spaces. For example:If the role in Sprout is "General Admins," it must match exactly in the IdP mapping. So, not "generalAdmins" or "general admins," etc.
   • Role assignment fails if the role attribute sent does not match a role name in Sprout. Any user with "Manage SSO" permissions is notified of the failure.
   • The role attribute data type can be a string or a string array.
   • Currently, Sprout supports the assignment of one Organizational Role and one Profile Permission Set per user. If additional roles or permission sets are sent, only the first valid one (upper case, alphabetical) is assigned. 
     • For example, if the following three roles are sent: “admin,” “Content Creator” and “Manager,” the “Content Creator” role is selected because upper-case letters are considered to be alphabetically ahead of lower-case letters. 
   • Legacy roles are not supported by Dynamic Role Sync.

After configuring the mapping and adding the role to the SAML assertion, the user's role is assigned on their next SSO login. If you have SSO and username/password login enabled, note this: The system won't update the user's role if they don't log in via SSO. 

Things to consider:

• If no role attribute or blank attribute is sent for a user, they keep the role they currently have. Dynamic Role Sync does not support de-provisioning a user. It cannot remove their role or access to Sprout. If the IdP no longer sends the user (e.g., they were deactivated), they won’t have access to Sprout (unless username/password login is enabled).
   
• It’s still possible to assign roles directly to users within the Sprout Application. If DRS is enabled, role assignment from the IdP takes precedence. If someone changes a user's role in the Sprout app, then a different role is sent from the IdP when the user logs in via SSO, their role is changed again to the one from the IdP. If DRS is enabled, a warning appears when a user's role is changed in the app. 

Illustrative example of adding a role attribute to SAML assertion in Okta

Identity Providers all have different instructions for adding attributes to a SAML assertion as well as for mapping the role attribute to the Group/Role for automatic assignment to each user. Additionally, some IdPs offer several different ways to configure this based on your organization’s setup and requirements. As such, please refer to your IdP documentation for specific instructions. To help you get started, we’ve provided an Okta example below.

This example is for illustrative purposes only. 

In this scenario, we have the following Organizational Roles and Profile Permission Sets, which can be assigned to users:

Please note, at this point, we assume you already have SSO configured for Sprout, and your desired Groups/Roles within Okta for the Sprout application. 

1. (In Okta) Add the role attribute within the profile editor for the Sprout App.
    
2. Search for and select the Sprout application.
    
3. Select add attribute and add the role attribute. Most fields are optional and depend on your organization’s requirements. See Okta documentation for more information on each of the fields and what they mean. For DRS, the data type must be string or array, and the Display Name must be either orgRole or profileRole. 

4. Navigate to the application section and find the Sprout Application.

5. Click on General and select Edit on SAML settings to add the role attribute to the Attribute Statements.

6. Name the custom attributes orgrole and profilerole and assign the value appuser.orgrole and appuser.profilerole.

7. Save your changes and scroll down to confirm the attribute appears in the Attribute Statements.

8. Indicate what specific Sprout role each group should be assigned by navigating to Assignments and then Groups within the Application section.

9. Edit the group to which you want to assign a Sprout role.
    
10. Click Add Another next to the orgRole and/or profileRole attributes and type in the exact name of the Sprout role you wish to assign the group. 

11. Validate the role appears in the SAML assertion by going back to the General tab. Click Edit on the SAML statement section and view a sample of the SAML assertion.

12. Cancel out of the SAML configuration screen. 

Now, when a member of the group logs into Sprout via SSO, they are assigned their corresponding Sprout Organizational Role and/or Profile Permission Set.

Frequently Asked Questions

Can I use this with JIT+SSO?

Yes, but if you use JIT+SSO and have set a Default Role (in Sprout), please note that DRS role assignment takes precedence.

Can the Account Owner role be assigned/changed via DRS?

The Account Owner cannot be assigned a new role via DRS. There are no other restrictions to who can be assigned roles or what roles can be assigned to them.

Can I remove a user’s role or their access to Sprout via DRS?

No - de-provisioning is not generally supported via SAML. If you send a blank role attribute or a SAML assertion without it, the user keeps their current role. If you want to remove a user’s access to Sprout, you must do so in the Sprout application. If they are removed or deactivated in the IdP, they cannot log in to Sprout (unless you have username/password login enabled).

Can we enable DRS if we have multiple IdP configurations associated with our Sprout account?

No, DRS can only be enabled for a single IdP configuration.

What happens if someone changes a user’s role directly in Sprout?

The next time the user logs in via SSO, their role changes back to whatever is sent via the IdP. If DRS is enabled, any changes to a user's role should be managed in the IdP by changing their IdP role/group. 

What if I want to assign a user granular permissions, and not an Organizational Role or Profile Permission Set?

DRS only supports Organizational Role and Profile Permission Set assignment. Users to whom you wish to assign granular permissions should be managed in the Sprout app and should not have any role attributes sent via the IdP. 

If a user does have only granular permissions and an Organizational Role or Profile Permission Set is sent over for them via DRS, DRS takes precedence and they are assigned the related role and the permissions. Any permissions they had previously that are not included in the role are then removed.

Can you use this to assign users to Sprout Groups or Teams?

No - DRS is for Sprout Organizational Role and Profile Permission Set assignment only. Any references to Groups in this document refer to Groups within the IdP.