The SCIM API is accessible via the public internet and is implemented as a RESTful API. Using the SCIM API you can automate user and role provisioning within Assure. 

This guide contains instructions for setup and configuration for connecting OKTA or Microsoft Entra ID to Assure using the SCIM 2.0 protocol. 

Introduction

Implementing a SCIM API streamlines identity management by providing a standard, automated approach to user provisioning and lifecycle management across multiple systems. With SCIM, organisations can efficiently synchronise user data, reduce manual administrative tasks, and enhance security by ensuring that user access is consistent and up to date everywhere. This not only improves operational efficiency but also supports compliance and governance initiatives.

Before enabling SCIM for there are several pre-requisites that must be completed first to enable a smooth transition to SCIM.

Pre-requisites

The following pre-requisites must be completed before SCIM is enabled.

Set org unit external ids

Note: SCIM can be enabled without assigning external ids to all Org Units but only those with an external id will be usable by SCIM.

External Id’s can be added to Org Units in 2 ways. They are:

1. Via the Edit Org unit screen in Assure
2. Using the org unit import tool. This can be used to bulk add External Id’s to Org units by uploading a csv.

Set role external ids

Note: SCIM can be enabled without assigning external ids to all Roles but only those with an external id will be usable by SCIM.

External Ids can be added to Roles via the edit Role screen within Assure.

Generate API Key

Your SCIM provider will require an API key to utilize the Assure SCIM API. Instructions on how to create and manage an API key for Assure can be found at Creating and managing your API keys – Evotix

Make a note of this API key as it will be required when configuring the SCIM connection within your Identity Provider.

SCIM URL format

The SCIM API URL takes the following format: https://scim.<STACKNAME>.sheassure.met/v1/scim

The URLs for the different Assure stacks can be found below

• UK: https://scim.uk.sheassure.net/v1/scim
• UK2: https://scim.uk2.sheassure.net/v1/scim
• NA: https://scim.na.sheassure.net/v1/scim
• ANZ: https://scim.anz.sheassure.net/v1/scim

To configure SCIM you will need the URL that matches the stack that your Assure instance is deployed on.

SCIM Functionality in Assure

The Assure SCIM API supports the following actions:

• Create new User records and corresponding Person Register records. 
• Update existing User records and corresponding Person Register records. 
• Deactivate Users (make them ‘Not Current’).
• Reactivate Users (make them ‘Current’).
• Create and Delete Assure Roles (via SCIM Groups).
• Add and Remove Assure Roles from Users (via SCIM Groups). 

Note: When an Assure role is created through SCIM, all permissions are set to Deny by default. A user with the appropriate permissions can then manually adjust the role’s permissions as needed. 

More information about what cannot be managed via SCIM can be found here: Managing users via the SCIM API – Evotix

Users

Minimum required fields

The following fields are the minimum required to create a user within Assure via SCIM:

1. Default Unit (see section below for more information)
2. Forename (First Name)
3. Surname (Last Name)
4. Email

User Access Type

For users that only require access to AssureGo+ the “UserType” field of the SCIM request must be set to “agoonly”. If this value is not set, then the user will be added to Assure as a full user which will count towards your licensed users count.

Default Unit

Thew default unit for a user is set by supplying the external Id of the Org Unit in the department field of the SCIM request

Is Manager

The “Is Manager” field can be set to true by supplying the value “manager” in the Entitlements field of the SCIM request.

Other fields

1. User language can be set using the same codes as Accept-Language HTTP header values (https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.5)
2. User Time zone can be set using IANA Time Zone database format (https://datatracker.ietf.org/doc/html/rfc6557)
3. If User Specific Time Zone, Language, and Date Format are not provided, defaults from system settings will apply
4. If Job title is sent through and does not exist, it will be added to the managed picklist.

Roles

Roles and their memberships in Assure are managed via SCIM Groups. The groups endpoint supports the follow actions:

1. Create role
2. Remove a role
3. Add user to role
4. Remove user from a role

Please note: When a new role is created via SCIM all permissions will default to “deny”. The permissions can then be changed by your Assure administrator from within the Assure UI.

OKTA

Set up SCIM connection

1. Navigate to your application within OKTA that is used for single sign on with Assure.
2. Click on the “General” tab.
3. Click on the edit button in the “App Settings” section.
4. For “Provisioning” select “SCIM”
5. Click the “Save” Button.
6. Click on the “Provisioning” tab.
7. Click on the “Edit” button
8. Set the “SCIM connector base URL”  to the appropriate URL from the “SCIM URL format” section of this document
9. Set the “Unique identifier field for users” to “Username”
10. For “Supported provisioning actions” set the following
    • “Push New Users”
    • “Push Profile Updates”
    • Push Groups
11. Set “Authentication Mode” to “HTTP Header”
12. Set the “Authorization” field to the API key that you created earlier.
13. Click “Test Connection Configuration”
14. If the connection test is successful, then click “Save”

Managing Assure Users

Add single user

The following section contains steps for adding a single user to Assure via SCIM

1. Navigate to the application create in the “Set up SCIM connection” section
2. Click on the Assignments tabs
3. Click on the “Assign” button
4. Click on “Assign to people”

5. Select the person you wish to add and click the “Assign" button.
6. Populate the fields required to create a user (Department, First name, Last name, Email)
7. Click “Save and Go Back”
8. Click “Done”
9. Refresh the page. If the SCIM process has been successfully completed then it will look something like this

Add groups of users

Groups of users can be added using the following steps. Please note that adding these groups will not assign roles to users. This must be handled separately (se section below). 

1. Navigate to the application create in the “Set up SCIM connection” section
2. Click on the Assignments tabs
3. Click on the “Assign” button
4. Click “Assign to Groups”

5. Find the group you wish to add and click “Assign”
6. The next screen allows you to set values that will be applied to all users. For example, if there was a group for all the managers then the “Is manager” field in Assure can be set by adding “manager” value to the Entitlements. This would look something like this:

7.  Click “Save and Go Back”
8. Click “done”

All the users who are members of the group will be added to Assure. This may take some time depending on the number of users within the group.

Managing Assure Roles

Role memberships in Assure are managed in Okta using a process called “Push Groups”. This process will get a list of available roles from Assure, these can then be linked to an Okta group (How Group Linking Works for SCIM Integrations or Group Push | Okta Identity Engine). When the linking is set up Okta will automatically add any new users to Assure and assign them to the role. If a user is removed from the group within Okta, then the role will be removed from them in Assure. The links above contain more details about how the reconciliation of groups work within Okta itself.

Synchronisation of role membership can take some time depending on the number of users within the group.

Microsoft Entra ID

Set up SCIM connection

1. Navigate to your enterprise application that is used for Assure SSO
2. Click on “provisioning”
3. Click on “Connectivity”
4. For “Select authentication method” select the “Bearer authentication” option.
5. Set the “Tenant URL” to the appropriate URL from the “SCIM URL format” section of this document
6. Set the “Secret token” field to the API key that you created earlier.
7. Click “Test Connection”
8. If the connection test is successful, then click “Save”

Managing Assure Users

User can be added to Assure by adding them to the Enterprise application that was created in the section above. This can be achieved by adding a single user, a group or by several other means that can be found within the official Entra Id documentation.

Managing Assure Roles

Roles and their memberships within Assure are managed by assigning Entra ID groups to the Assure enterprise application. Groups will be added to Assure as roles (if a role does not already exist with an external ID that matches the group name). If a role is added to Assure, then all permissions will be set to deny and will require manual updating by your Assure administrator. Any members of the group will be added to Assure and have the role assigned to them. If a user already exists within Assure, then they will be updated to have the new role assigned to them. Any other roles that were assigned to the user will be preserved.

Adding a role to Assure

The following step show how to add a Role(group) to Assure from Entra Id

1. Navigate to your Entra ID instance and click on “Enterprise Applications”
2. Find your application that is associated with Assure
3. Click on “Users and groups”

4. Click “Add Users and Groups”

5. When the Add assignment screen loads click on the “None Selected” link

6. Select the groups you wish to add and click on the “Select” button
7. Click the “Assign” button

After performing the above steps, the group(s) selected will be added to Assure as roles and any members of those groups will be added as users in Assure with the role assigned to them. If the user already exists in Assure, then it will be updated to include the new role.

The synchronisation process is not instantaneous. Entra Id only periodically synchronises with external systems. This can take anything between 20 minutes and 3 hours. If you are testing and need the synchronization to happen more quickly there is a provision on demand option. Please note that the on-demand option is limited to 5 users per group for testing purposes.