Haiilo Advocacy supports user provisioning with the System for Cross-domain Identity Management (SCIM) standard. This article will help you establish a SCIM connection between your company's identity provider and Haiilo.

While SCIM can function without SSO, it's recommended to enable SSO for your Haiilo platform using the same credentials for both SAML and SCIM. Doing so provides added convenience and security benefits for both users and administrators.

Basics of SCIM

With SCIM, you can:

• Create users in Haiilo
• Remove users in Haiilo when they don't require access anymore. Users cannot be deactivated; they are always deleted from Haiilo.
• Keep user attributes synchronized between your identity provider and Haiilo

When you first set up provisioning, SCIM will match each user on Haiilo with a user in your identity provider. If a user doesn't yet exist on Haiilo, they will be added. After a user is matched or added by SCIM, any changes to the user's account in your identity provider will be reflected on Haiilo.

If a user isn't matched, i.e., they have a local account on Haiilo from before SCIM was set up, but is not assigned to the application in the identity provider and therefore cannot be synced, there'll be no changes made to their account on Haiilo. The user will remain in Haiilo until they are manually deleted or assigned to the application in the identity so they can be synced.

Set up SCIM in Haiilo

To set up SCIM, you need to complete steps in your identity provider. If you don't already have a Haiilo application created in your identity provider, you should create this first. For IdP-specific instructions on setting up an application and SCIM, view your identity provider's documentation or our IdP-specific setup guides:

• Setting up SSO on Microsoft Entra ID and Setting up SCIM on Microsoft Entra ID
• Setting up SSO on Okta and Setting up SCIM on Okta

1. To set up SCIM, you need to generate an access token in your Haiilo profile. You can find instructions for this in the Generate an Access Token article.
2. After generating your access token, proceed to your identity provider to begin setting up SCIM. You will need to input at least the following (other fields depending on IdP):
   • Tenant URL: https://<your_subdomain>.smarpshare.com/api/scim/v2, where <your_subdomain> is replaced with your company's subdomain. 
   • Token: The Access Token that you generated in Haiilo 
3. Configure user profile field mappings. You should only map the attributes you want to be synced; otherwise, it can cause undesirable side effects in your platform when users are added to teams you do not want or need.
   • Haiilo supports the attributes in the table below.

     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 users)
     country	To determine the user's group on Haiilo. The user profile value must match an existing group on Haiilo; case sensitive. If no group with the same value exists, provisioning will fail. Read more in Map users to a group.
     locality	To determine the user's team on Haiilo. The user profile value does not need to match an existing team on Haiilo. A new value will create a new team; case insensitive. Read more in Map users to team(s).
     region	To determine the user's team on Haiilo. The user profile value does not need to match an existing team on Haiilo. A new value will create a new team; case insensitive. Read more in Map users to team(s).
     organization	To determine the user's team on Haiilo. The user profile value does not need to match an existing team on Haiilo. A new value will create a new team; case insensitive. Read more in Map users to team(s).
     division	To determine the user's team on Haiilo. The user profile value does not need to match an existing team on Haiilo. A new value will create a new team; case insensitive. Read more in Map users to team(s).
     department	To determine the user's team on Haiilo. The user profile value does not need to match an existing team on Haiilo. A new value will create a new team; case insensitive. Read more in Map users to team(s).

4. Assign users to the application if you haven't yet. Once users are assigned, they will be provisioned in the next sync. We recommend testing the sync with a few example users first.
5. Save the app. The initial cycle will run shortly after that and any assigned users will be created on the platform.

Once a cycle has run, the process is logged in the Provisioning logs of the identity provider application. If you run into any errors, please view the logs for error information and share the findings with our Service Desk. You can also view our FAQ section for help.

Map users to a group

Any group mentioned in this section refers to a Haiilo group, not an identity provider group in the SCIM schema.

• A user on Haiilo can only have one group. The group is defined by the country attribute in the SCIM schema.
• The value represents the name of a group, which is case-sensitive. The group must exist before any user can be assigned to it. Hence, please create and determine your Haiilo groups based on the information you have in your user profiles in the identity provider. 
  • If a group does not exist when a sync runs, an error will occur. You can read about this in the I get a "Group does not exist" error when adding users via SCIM. Why? article.
  • To resolve a group sync error, 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 mapping will assign the users to the teams in the new group according to the request.
• Mapping users to groups requires that the Groups feature is enabled for your platform. If it is not, the value is simply ignored.

Map users to team(s)

• Haiilo supports mapping up to 5 teams per user with SCIM. Additional teams can be added manually from Administration > Users. Each 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 "marketing" would match team "Marketing"), 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 "marketing" will be created as "marketing"), and the user will be assigned to the newly created team.
• Teams are unique per group, meaning when you add users to groups and teams, users are added first to a group and then to that group's teams. You would have a "Marketing" team in the "AMER" group and another "Marketing" team in the "EMEA" group. Teams don't overlap between groups.