Advocacy: Manage users with SCIM provisioning

To make managing your users in Haiilo easier, Haiilo 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 Haiilo. Please note that although SCIM is a standard for user provisioning, its implementation is different from platform to platform and as a result, this guide is for reference only and configuration depends on the IdP your company uses.

SCIM can work independently from SSO, however, enabling SAML-based SSO for your Haiilo 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 Haiilo
• Remove users in Haiilo when they do not require access anymore
  • Users cannot be deactivated, only removed
• Keep user attributes synchronized between your IdP and Haiilo

Reach out to your dedicated Customer Success specialist from Haiilo if you are interested in SCIM to be enabled for your domain or for more information. 

How to setup 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 IdP's. For detailed instructions for how to setup SCIM on Microsoft Azure AD and Okta, see the bottom of this page.

• To setup SCIM, you need to generate an access token in your Haiilo profile. For more information on how to do this, see here. When you have generated 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://<your-subdomain>.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.

• • Please read the more detailed notes about profiling for groups and teams below.
  • Please make sure that you have only the attributes that 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 FAQ article for possible solutions. If you cannot find an answer there, please contact Haiilo Support from the button below.

Notes on mapping users to Haiilo

General notes

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 Azure group assigned to the Haiilo application has 100 users. When the SCIM integration is done, 90 users on Azure are matched on Haiilo and SCIM will bring the 10 missing users from Azure 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 Azure group and SCIM will take care of them from the next sync.

Mapping users to a Group on Haiilo

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) on Haiilo

• 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.

 

IdP-specific setup guides