Configuring external user provisioning
Enabling external user provisioning allows automatic user management from one identity provider data source by leveraging the System for Cross-domain Identity Management (SCIM).
Permissions
External user provisioning needs to be enabled in Diligent One and set up in an identity provider. To configure external user provisioning for an organization, someone with System Admin permissions in Diligent One and someone with administrative permissions in the identity provider is required. These permissions may be held by one person or multiple people who will need to coordinate the external user provisioning set up. In general, this should only need to be set up once, and then the system runs on its own.
Requirements
Diligent One supports user provisioning via SCIM 2.0 to enable automatic user management from one data source.
Supported operations
Once external user provisioning is enabled, adding or removing users from an organization and updating user profiles is automatically pushed to Diligent One from an identity provider.
In the future, support is planned for the following operations: group assignment and group management (add and delete).
When you enable external user provisioning, it doesn't remove the ability to manually add and manage users directly in Diligent One. By enabling external user provisioning, you are adding to your user management options and can use both in a hybrid solution.
To clarify, users exclusively added in Diligent One, that are not synched with the identity provider, can only be managed in Diligent One. Users synched from an identity provider should only be managed in the identity provider. If changes are made to synched users in Diligent One, the changes will be overwritten in the next synch. See Support for hybrid user provisioning.
Support for hybrid user provisioning
Ideally, the identity provider would operate as the single source for all users to streamline and automate user management. However, there may still be scenarios where a hybrid solution is the best way to manage users in your system. For example, you might not need to add users to an identity provider if those users only require temporary access for the purposes of troubleshooting or consulting.
In a hybrid solution, users exclusively added in Diligent One, that are not synched with the identity provider, can only be managed in Diligent One. Users synched from an identity provider should only be managed in the identity provider.
Important
The following information is intended to make you aware of potential issues that may arise from a hybrid solution so that you can make the best choice for your organization and avoid these issues:
- Currently, in Diligent One, there is no visual distinction between users managed via the identity provider and those manually added in Diligent One.
- Users manually added in Diligent One and not synched with the identity provider, only exist in Diligent One and can only be managed in Diligent One.
- Do not manage user updates in Diligent One if the user is already synched from the identity provider. If a user that is synched with the identity provider is edited in Diligent One, those edits will be overwritten by a subsequent, automated sync from the identity provider. If a user is synched, the identity provider is the single, trusted source that the profile will default to. In this case, any changes should be made in the identity provider, so that they will be pushed to Diligent One.
- While the risk is low, removing a synched user from Diligent One before that user is removed from the identity provider could result in automation failures in the external source. If this does happen, manual action may be required in the external source to re-sync the Diligent One with the identity provider. If this happens, contact Support for assistance.
Limitations
External user provisioning is limited to one integration per organization.
Enable external user provisioning in Diligent One
There are two main components to setting up external user provisioning: enabling external user provisioning in Diligent One and setting up your identity provider.
Enabling external user provisioning in Diligent One
By enabling external user provisioning in Diligent One, an API key is generated to add to your identity provider to complete the set up process.
- Open Launchpad.
If your company uses more than one instance in Diligent One, make sure the appropriate instance is active.
- Select Platform Settings > Organization.
If you do not see Organization as an option, the account you used to sign in does not have Admin privileges.
- Select Manage user provisioning. This opens the User provisioning page.
- Select Enable user provisioning. This generates an API key and gives you the Base URL that you can copy from the Provisioning set up details dialog box.
- Copy the API key and the Base URL, and save the values in a secure place before you close the Provisioning set up details dialog box.
- Once you have saved the API key and the Base URL, select Close. This dismisses the Provisioning set up details dialog box, and the User provisioning page reloads confirming that SCIM external user provisioning is enabled.
- The final aspect of setting up external user provisioning configuration happens outside of Diligent One within your identity provider. See Setting up your identity provider details.
Caution
As a security measure, this is your only opportunity to have access to the API key. If you do not save the API key and it is lost or forgotten, you will need to create a new one by briefly disabling external user provisioning from the identity provider and Diligent One, generating a new token, and re-enabling external user provisioning in both Diligent One and the identity provider with the new token. See Refresh tokens for external user provisioning.
Once you enable external user provisioning, you still have the option to add and remove users manually to grant short term access for scenarios such as support troubleshooting and consulting. However, this should be done with caution (if at all), since it may cause syncing issues. See Support for hybrid user provisioning.
Setting up your identity provider details
Once external user provisioning is enabled in Diligent One, set up is complete when external user provisioning is configured in your identity provider. For the steps to set up external user provisioning, consult the documentation for that specific identity provider, since it may differ depending on the identity provider. Other identity providers that support SCIM 2.0 may be compatible with this solution; however, the following are the identity providers we actively test on and support:
- Microsoft Entra (formerly Azure Active Directory): Configuring external user provisioning for Microsoft Entra
- Okta:
SCIM attribute mapping
The following table demonstrates how Diligent One attributes map to standard SCIM attributes.
Core user schema
| SCIM attribute name | Diligent One attribute name | Mandatory at user creation |
|---|---|---|
| userName | Yes | |
| name.givenName | First Name | Yes |
| name.familyName | Last Name | Yes |
| title | Title | No |
| name.initials | Initials | No |
| phoneNumbers(type work).value | Phone Number | No |
| phoneNumbers(type extension).value | Phone Extension | No |
| name.middleName | Middle Name | No |
| addresses[type eq "work"].streetAddress | Office Address line 1 | No |
| addresses[type eq "work"].streetAddress2 | Office Address line 2 | No |
| addresses[type eq "work"].locality | Office Address City | No |
| addresses[type eq "work"].region | Office Address State | No |
| addresses[type eq "work"].country | Office Address Country | No |
| addresses[type eq "work"].postalCode | Office Address Postal Code | No |
| addresses[type eq "work"].location | Office location | No |
| phoneNumbers[type eq "home"].value | Home Phone | No |
| phoneNumbers(type mobile).value | Mobile Phone | No |
| phoneNumbers[type eq "mobile"].value | Secondary Email | No |
Policy manager extension
There are up to 13 optional fields that can be populated through SCIM by mapping an attribute of a user in the identity provider to the following SCIM attribute:
urn:ietf:params:scim:schemas:extension:Diligent:2.0:User:externalField<insert_field_number>Value
Refresh tokens for external user provisioning
A token may need to be refreshed if it is lost, forgotten, or expired. If a token needs to be refreshed, external user provisioning will need to be briefly disabled and re-enabled from both Diligent One and your identity provider. This needs to be done concurrently to prevent syncing issues.
To avoid syncing issues, when preparing to start this process, make sure that you are able to complete it in one sitting. Completing these steps may require coordination with your IT department or an administrator, since you are generating a new token in Diligent One that needs to be implemented in your identity provider. It is not recommended to start this process and come back later.
-
Optional, but strongly recommended. In your identity provider, disable user provisioning to implement a new token. Once external user provisioning is disabled in Diligent One, it no longer receives user data from your identity provider, but the identity provider still sends user data as normal which causes it to fail. To avoid this, disable external user provisioning from the identity provider. How this is disabled depends on your specific identity provider. See Setting up your identity provider details.
- In Diligent One, disable user provisioning to implement a new token. Open Launchpad.
- Select Platform Settings > Organization.
-
Select Manage user provisioning. This opens the User provisioning page.
-
Select Disable user provisioning. This opens a Disable user provisioning? dialog box.
-
Select Disable. The existing API key immediately becomes invalid, all user syncs stop, and user management can only happen locally in Diligent One. This returns you to the User provisioning page where a message displays confirming that user provisioning was successfully disabled.
- Select Enable user provisioning. This generates an API key and a Base URL that you can copy from the Provisioning set up details dialog box.
- Copy the API key and the Base URL and save the values in a secure place before you close the Provisioning set up details dialog box.
- Once you have saved the API key and the Base URL, select Close. This dismisses the Provisioning set up details dialog box, and the User provisioning page reloads confirming that SCIM user provisioning is enabled.
- In your identity provider, re-enable external user provisioning with the newly-generated token. The steps to complete this will depend on the identity provider you have. See Setting up your identity provider details.
The following steps, with the exception of the final step, all take place within Diligent One.
If your company uses more than one instance in Diligent One, make sure the appropriate instance is active.
If you do not see Organization as an option, the account you used to sign in does not have Admin privileges.
Caution
As a security measure, this is your only opportunity to have access to the API key. If you do not save the API key, and it is lost or forgotten, you will need to briefly disable user provisioning in both Diligent One and your identity provider, create a new token, and re-enable user provisioning in both Diligent One and your identity provider. See Refresh tokens for external user provisioning.
This step concludes what you need to do in Diligent One to generate a new token for external user provisioning. The rest of the steps to re-set external user provisioning are completed in your identity provider with the newly-generated token.
Unless you have administrative permissions in the identity provider, this may need to be coordinated with your IT department.
Re-enabling user provisioning will automatically force a sync to refresh user data.
Disable external user provisioning in Diligent One
If you only need to briefly disable external user provisioning to generate a new token that has been lost, forgotten, or expired, see Refresh tokens for external user provisioning. The following instructions are to disable external user provisioning to manually manage users via Diligent One exclusively.
- Disable external user provisioning in your identity provider. How this is disabled will depend on your specific identity provider. See Setting up your identity provider details.
Note
Once external user provisioning is disabled in Diligent One, it no longer pulls user data from your identity provider, but the identity provider still sends user data as normal which causes it to fail. To avoid this, external user provisioning needs to be disabled from the identity provider. This may require coordination with your IT department or whoever has the appropriate permissions for your identity provider.
- Open Launchpad.
- Select Platform Settings > Organization.
If you do not see Organization as an option, the account you used to sign in does not have Admin privileges.
- Select Manage user provisioning. This opens the User provisioning page.
- Select Disable user provisioning. This opens a Disable user provisioning? dialog box.
- Select Disable. This returns you to the User provisioning page where a message displays confirming that user provisioning was successfully disabled. The existing API key immediately becomes invalid, all user syncs stop, and user management is only available locally in Diligent One.
- Select Go to organization page. Disabling user provisioning is complete.
If your company uses more than one instance in Diligent One, make sure the appropriate instance is active.
