Automatic User Provisioning with SCIM 2.0 – BlueDolphin

Introduction

BlueDolphin supports automatic user provisioning. When automatic user provisioning is enabled, you can use the public API to manage BlueDolphin users and their role assignments. This means you no longer need to do this manually in the BlueDolphin UI. When you use automatic user provisioning, whenever a user logs in, they will have the role(s) that correspond to their user groups in your organization's Identity and Access Management (IAM) tool. BlueDolphin user authentication is still done through IDP. New users added automatically via the SCIM user provisioning API can go directly to the login page and log in using single sign-on to start using BlueDolphin.

In BlueDolphin, automatic user provisioning is done using public REST API calls that follow the SCIM 2.0 protocol. If your organization uses an IAM tool that supports SCIM 2.0, that tool can issue public API calls to BlueDolphin to read, create, update, delete users and manage role assignments in BlueDolphin for all users that belong to certain user groups in your organization's IAM tool.

Note: BlueDolphin automatic user provisioning is currently supported with the following IAM tools: Microsoft Entra ID, Okta, and SailPoint. Any other IAM tool that supports SCIM 2.0 may also work, but is not explicitly supported.

For more information on the SCIM 2.0 protocol, see here. Please also refer to the documentation of your IAM tool.

The public REST API for automatic user provisioning has two endpoints, /Users and /Groups.

BlueDolphin supports the following operations:

For users

Operation	Method	Endpoint	Note
Create a user	POST (content-type = application/scim+json)	/Users
Delete a user	DELETE	/Users/{user_id}	BlueDolphin user id is the {user_id}
Get a single user	GET	/Users/{user_id}	BlueDolphin user id is the {user_id}
Get all users	GET	/Users
Replace a user	PUT (content-type = application/scim+json)	/Users/{user_id}	BlueDolphin user id is the {user_id}
Update a user	PATCH (content-type = application/scim+json)	/Users/{user_id}	BlueDolphin user id is the {user_id}

For groups

Operation	Method	Endpoint	Note
Get a single group	GET	/Groups/{group_id}	{role_id} in BlueDolphin is the {group_id}
Get all groups	GET	/Groups
Replace a group (membership only)	PUT (content-type = application/scim+json)	/Groups/{group_id}	{role_id} in BlueDolphin is the {group_id}
Update a group (membership only)	PATCH (content-type = application/scim+json)	/Groups/{group_id}	{role_id} in BlueDolphin is the {group_id}

For a visual representation of the API and its documentation, please see BlueDolphin SCIM API

How to start using automatic user provisioning

Enable the feature

BlueDolphin automatic user provisioning is disabled by default. To request the feature to be enabled, raise a Zendesk support ticket with BlueDolphin. BlueDolphin support will inform you when the feature is enabled.

Please be aware that when automatic user provisioning is enabled:

You can still manually manage users and their role assignments in the BlueDolphin UI.
There can be a mix of manually and provisioned users.
Also, each user can have a mix of manual and provisioned role assignments.
You cannot recognize the difference between a manually managed user or role assignment from an automatically provisioned one - neither in the UI nor through public API call responses.

Create an API key

To successfully issue public API calls for a certain feature, calls must use a valid API key with that feature as the scope of the API key. The public API calls for this feature need to make use of an API key with the scope 'User provisioning'.
In Admin > Public API keys, create an API key and store the key secret. For more information on this, see Working with the public API.

Map user groups in IAM to BlueDolphin roles

Before starting with automatic user provisioning, you must decide the groups in IAM that should be mapped to roles in BlueDolphin. In general, you only want to provision users in BlueDolphin for a subset of your user groups in IAM. This mapping can be many-to-many.

Note: A 'role' in BlueDolphin is called a 'group' in SCIM 2.0 schema.

Initial matching

Assuming you have used BlueDolphin without automatic user provisioning, your BlueDolphin tenant will contain users that have been manually created. Before you can use user provisioning on a day-to-day basis, you need to match (or correlate) those pre-existing BlueDolphin users with the users in IAM.

Day-to-day automatic user provisioning

At regular intervals, the relevant changes to the users in IAM will be propagated to BlueDolphin, so that the users and role assignments are in sync.
A relevant change in IAM can be one of the following types:

A new user
A deleted user
A change in relevant user details or
A change in IAM user group membership (for one of the relevant IAM user groups)