Haiilo Advocacy supports user provisioning with the System for Cross-domain Identity Management (SCIM) standard. This guide will help administrators establish a SCIM connection between their company's IdP and Haiilo.
With SCIM, you can:
- Create users in Haiilo
- Remove users in Haiilo when they do not require access anymore. Users cannot be deactivated; they are always deleted from Haiilo.
- Keep user attributes synchronized between your IdP and Haiilo
While SCIM can function without SSO, it's advantageous to enable SAML-based SSO for your Haiilo domain using the same credentials for both SAML and SCIM. Doing so provides added convenience and security benefits for both users and administrators.
Step-by-step setup instructions for the IdPs Entra ID and Okta can be found at the bottom of this page.
How to set up SCIM
If you don't already have a Haiilo application created in your IdP, please create one now. The below instructions are general and might not apply to all IdPs.
- To set up SCIM, you must generate an access token in your Haiilo profile. After generating your access token, proceed to your IdP to begin setting up SCIM.
- In your Haiilo application in your IdP, navigate to the Provisioning tab
- Fill in at least the following (other fields depending on IdP):
- URL: https://.smarpshare.com/api/scim/v2
- For Authorization: use the Access Token that you created in Haiilo
- In Mappings for Users, Haiilo supports these attributes:
|
Attribute |
Notes |
| userName | should be in the form of an email. It's unique per user. |
| name.givenName | displays as the user's first name on Haiilo |
| name.familyName | displays as the user's surname on Haiilo |
| active | required for provisioning (adding/removing) |
| country | to determine the user's group on Haiilo. Value must match existing group on Haiilo; case sensitive. |
| locality | to determine the user's team on Haiilo. Value does not need to match existing group on Haiilo, new value will create new team; case insensitive. |
| region | to determine the user's team on Haiilo. Value does not need to match existing group on Haiilo, new value will create new team; case insensitive. |
| organization | to determine the user's team on Haiilo. Value does not need to match existing group on Haiilo, new value will create new team; case insensitive. |
| division | to determine the user's team on Haiilo. Value does not need to match existing group on Haiilo, new value will create new team; case insensitive. |
| department | to determine the user's team on Haiilo. Value does not need to match existing group on Haiilo, new value will create new team; case insensitive. |
-
- Read the more detailed notes about profiling for groups and teams below.
Make sure that you have only the attributes you want to be synced in the mappings; otherwise, it can cause undesirable side effects in your platform, i.e., users added to teams you do not want or need.
- Assign users to Haiilo 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 IdP application. If you run into any issues during setup, please refer to our FAQs for possible solutions.
General information on mapping users to Haiilo
When you first set up provisioning, SCIM will match each user on Haiilo with a user in your IdP. After a user is matched, any changes in your IdP will be reflected on Haiilo. But if a user isn't matched, i.e. they have a Haiilo account from before SCIM was setup but are not in the IdP group, there'll be no changes made on Haiilo. The user will remain in Haiilo until they are manually deleted or added to the IdP group so they can be synced.
We have this example scenario: Haiilo has 200 users and the Entra ID group assigned to the Haiilo application has 100 users. When the SCIM integration is done, 90 users on Entra ID are matched on Haiilo and SCIM will bring the 10 missing users from Entra ID into Haiilo with SCIM. Haiilo now has 210 users. Note that there are 100 users on Haiilo 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 Haiilo anymore, or adding them to the Entra ID group and SCIM will take care of them from the next sync.
Mapping users to a Group
Disclaimer: any 'group' mentioned in this section refers to a Haiilo group, not an IdP group in the SCIM schema.
- Requires the group feature to be enabled for the Haiilo 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.
- 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 Haiilo 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.
Mapping users to Team(s)
- Haiilo supports mapping up to 5 teams per user with SCIM. Additional teams can be added manually in Haiilo under the Users tab. The team value is defined by these attributes:
- locality (addresses[type eq "work"])
- region (addresses[type eq "work"])
- organization
- division
- department
- 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 or they will be created in that group.