To make managing your users in Smarp easier, Smarp supports user provisioning with the System for Cross-domain Identity Management (SCIM) standard. This guide aims to help an admin setup a SCIM connection between their company’s IdP and Smarp. Although SCIM is a standard for user provisioning, its implementation is different from platform to platform. As a result, the latter part of this guide is platform-specific.
SCIM can work independently from SSO, however, enabling SAML-based SSO for your Smarp domain using the same credential for both SAML and SCIM is beneficial for both users and admins in terms of convenience and security.
With SCIM you can:
- Create users in Smarp
- Remove users in Smarp when they do not require access anymore
- Keep user attributes synchronized between your IdP and Smarp
Reach out to your dedicated Customer Success specialist from Smarp if you are interested in SCIM for more information. (Please note that SCIM is a feature that needs to be enabled for your company Smarp domain).
Generate a new token on Smarp
To setup SCIM, you need to generate an access token in your Smarp profile. To be able to do this, you first have to ask your dedicated Customer Success specialist from Smarp to enable SCIM setup for your company Smarp domain. Once this has been enabled, you will see an Access token option in your settings in Smarp.
- To get an access token, first please check if you have a Company Admin, Group Admin or Channel Manager role in Smarp.
- Navigate to your settings from under your profile by clicking on your user avatar and choosing Settings from the drop-down menu.
- Choose the Access token-option in the left-side list
- If you don't have an access token, please create one by clicking Create new access token-button. Then give a name for the token so you remember where are you going to use it.
- The generated token will be used to set up a connection between Smarp (as SCIM server) and the IDP (as SCIM client).
You can also find more detailed instructions for generating an access token in Smarp here. When you have generated your access token, proceed to your IdP to begin setting up SCIM.
For detailed instructions for how to setup SCIM on Microsoft Azure AD and Okta, see the bottom of this page.
How to setup SCIM
If you don’t already have a Smarp application created in your IdP, please create one now.
- In your Smarp application, navigate to the Provisioning tab
- Fill in at least the following (other fields depending on IdP):
- URL: https://<your-subdomain>.smarpshare.com/api/scim/v2
- For Authorization: use the Access Token that you created in Smarp
- In Mappings for Users, Smarp supports these attributes:
- userName: should be in the form of an email. It’s unique per user.
- name.givenName: displays as the first name on Smarp
- name.familyName: displays as the last name on Smarp
- active: for deprovisioning
- addresses[type eq "work"].country: to determine the user’s group on Smarp, matched by group name. See Profiling: Group
- addresses[type eq "work"].locality: to determine the user’s team on Smarp, matched by team name. See Profiling: Team
- addresses[type eq "work"].region: to determine the user’s team on Smarp, matched by team name. See Profiling: Team
- organization: to determine the user’s team on Smarp, matched by team name. See Profiling: Team
- division: to determine the user’s team on Smarp, matched by team name. See Profiling: Team
- department: to determine the user’s team on Smarp, matched by team name. See Profiling: Team
- Please make sure that you have only the attributes that you want to be synced in the mappings. Smarp is always looking for ways to improve our SCIM support, so new attributes might be implemented in the future, which might cause undesirable side effects with your integration.
- Assign users to Smarp if you have not yet configured this
- Save the app. The initial cycle will run shortly after that.
Once a cycle has run, the process is logged in the Provisioning logs of the application. When you first set up the provisioning, SCIM will match each user on Smarp with a user on Azure. After a user is matched, any changes on Azure will be reflected on Smarp. BUT if a user isn't matched, i.e. they have a Smarp account from before SCIM was setup but are not in the Azure group, there'll be no changes made on Smarp. The user will remain in Smarp until they are manually deleted or added to Azure.
We have this example scenario: Smarp has 200 users and Azure has 100 users initially. When the SCIM integration is done, 90 users on Azure are matched on Smarp and SCIM will bring the 10 missing users on SCIM into Smarp. Smarp now has 210 users. Note that there are 100 users on Smarp that SCIM has no idea about. These 100 users will need to be taken care of manually by either deleting them if they aren't allowed to use Smarp anymore, or add them to Azure and SCIM will take it from there.
Notes on profiling
Disclaimer: any 'Group' mentioned in this section refers to a Smarp Group, not an IdP Group as in the SCIM schema.
Requires the Group feature to be enabled for the Smarp domain. If it is not, the value is simply ignored. The Group is defined by the 'country' attribute in the SCIM schema. Please check the SCIM schema mappings in your IDP if you wish to have Group Profiling. Find instructions on how to setup SCIM on your specific IDP.
The value represents the name of a Group, which is case sensitive. The Group must exist before any user can be assigned to it. If it does not exist when a sync run happens, an error will occur. To resolve this, simply create a Group in Smarp with the corresponding name and let the SCIM sync again.
When moving a user to a different Group, all of its current Teams will be removed from the profile. After a successful move, Team profiling will assign the users to the Teams according to the request.
Smarp supports up to 5 Teams per user. Additional Teams can be added manually in Smarp under the Users tab. The Team value is defined by these attributes:
- addresses[type eq "work"].locality
- addresses[type eq "work"].region
Unlike Group, Team names are case insensitive. A Team doesn't need to exist prior to the sync. During syncing, the Team is searched for (Team 'AbC' would match Team 'abc') and if found, the user will be assigned to the matching Team. If a Team isn't found, a new Team will be created, preserving the case as it came (Team 'AbC' will be created as 'AbC') and the user will be assigned to the newly created Team.
All Teams are required to be in the Group where the user is assigned.