SCIM provisioning

Introduction

SigningHub now supports user provisioning through the System for Cross-domain Identity Management (SCIM) protocol. This industry-standard integration enables seamless, automated management of user identities between identity providers and SigningHub. With SCIM, administrators can create, update, enable, disable and delete user accounts directly from their identity management system, removing the need for manual user administration. This improves operational efficiency, enhances data consistency, and strengthens access security across connected platforms.

This use case outlines the complete configuration required to enable SCIM-based provisioning. It walks through all the key steps—from generating the SCIM endpoint and secret token to configuring the connection between the identity provider and the service, and managing user assignments. Currently, SCIM provisioning in SigningHub is supported exclusively through Azure Active Directory (Azure AD).

---

How it works?

1. Enable SCIM provisioning in SigningHub Web to activate automatic user syncing.

2. Configure the token expiry time in SigningHub Admin to define how long the SCIM token stays valid.

3. Authenticate using the API to obtain a SCIM-specific token.

4. Create an SCIM App in Azure Active Directory to initiate provisioning.

5. Create an App Role to manage role-based user assignments.

6. Test the connection between Azure AD and the SCIM client.

7. Configure provisioning settings and access mappings for the SCIM app.

8. Assign users and roles to the SCIM application in Azure AD.

9. Set the source scope to define which users are provisioned.

10. Map user attributes from Azure AD to the required SCIM fields.

11. Trigger on-demand provisioning to validate the configuration or sync instantly.

---

Enable SCIM Provisioning

Enable SCIM provisioning in SigningHub Web to ensure that users assigned to the SCIM app in Azure AD are automatically created in the enterprise with mapped roles.

Follow the steps below to enable SCIM provisioning:

1. Log in to the SigningHub Web portal with your enterprise admin credentials.

2. Click "Configurations" from the left menu and click "Users" under "People" options in the "Enterprise Configurations" section.

3. Tick the "Enable SCIM provisioning" check box.

---

Configure Token Expiry Time

To define how long the SCIM token remains valid, you can set the expiry duration from the SigningHub Admin. This ensures secure communication between SigningHub and external identity providers.

Follow the steps below to configure SCIM token expiry time:

1. Log in to the SigningHub Admin portal.

2. From the left-hand menu, click Configurations.

3. Click on Global Settings.

4. In the top-right dropdown, select Session and Links Expiry Time.

5. Locate the field for 'SCIM Token Expiry Time' and specify the number of days (i.e. 7) after which the SCIM token should expire.

6. Click on the 'Save' button to apply the new expiry duration.

---

'Authenticate' API

Follow the steps below to generate a SCIM-specific token using the 'Authenticate' API.

1. Generate an authentication token using the Client ID and Secret from your Enterprise Integration.

   While making this request, include the custom header X-SCIM: true to specify that the token is intended for SCIM operations. If the request is successful, a SCIM-restricted token will be returned. This token is securely bound to the associated enterprise and is valid only for accessing SCIM endpoints through Azure AD.

2. Save the SCIM token (received in response), it will be used in Azure AD to authenticate and test the connection to the SCIM endpoint.

   

---

Create an SCIM App in Azure Active Directory

Access the Azure AD portal and create an application using the following steps:

1. Sign in to the Azure portal using your Azure Active Directory administrator account, and click on 'Enterprise applications'.

   
2. Click on the "New application" button.

   
3. Click on the "Create your own application" button.

   
4. Enter the name for the app, select an option for your app via the radio button, and click on the "Create" button.

   

---

Create an App Role for the SCIM App

Define custom roles for your application using the following steps:

1. Select the 'App registration' option from the left panel.

2. Choose the created application for which you want to define the app role.

3. Click on 'App roles', and then the 'Create app role' button.

   
4. Specify the 'Display name', 'Allowed member types' and the 'Value' for the app role.

   

---

Test Connection with SCIM Client

After creating the SCIM app, follow the steps below to establish a connection with the SigningHub API:

1. In the application’s navigation pane (left side), click on Provisioning:

2. Enter the 'Tenant URL' (SCIM endpoint) and the 'secret token'.

   • The format for the 'Tenant URL' shall be https://yourdomain.com/api/scim/v2.

   • The 'Secret Token' is the SCIM-specific bearer token, generated earlier.

3. Click the Test Connection button.

   

---

Configure Provisioning Settings and Access Mappings

Navigate to the 'Provisioning' section, and click on 'Mappings':

1. Set the 'Provisioning Mode' to Automatic.

2. Turn the 'Provisioning Status' to On.

3. Click on Provision Microsoft Entra ID Users to configure attribute mappings.

   

1. This section would be unlocked after successfully setting up the connection with the SCIM Client app.

---

Assign Users and Roles to the SCIM Application

To ensure users are eligible for provisioning and are mapped correctly to enterprise roles, follow these steps:

1. In the left-hand menu, click on Users and groups.

2. Click on Add user/group.

3. In the Users section, select the user(s) you want to assign to the application.

   
4. In the Select a role section, choose a role created under the app (e.g., SigningHub_Admin, User, etc.).

   
5. Click Assign to complete the user-role mapping.

   

1. Only assigned users are eligible for SCIM provisioning.

2. Roles must match the enterprise role names in SigningHub for automatic mapping.

3. If no role is assigned, the system will apply the DefaultEnterprise role by default.

4. Once mapped, no further role configuration is needed in SigningHub.

---

Set Source Scope for Provisioning

To define which users are eligible for SCIM provisioning, follow the steps below:

1. Navigate to Provisioning, then click on Provision Microsoft Entra ID Users, depending on your configuration.

2. Under Source Object Scope, set the value to All records. (This ensures that all assigned users are considered for provisioning.)

   
3. Optionally, apply a filter to include or exclude specific users from being provisioned.

---

SCIM User Attribute Mapping

User attribute mapping is a critical part of configuring SCIM provisioning. SigningHub requires a specific set of attributes to be mapped correctly from Azure AD.

Delete all default attributes before proceeding. Manually add only the attributes listed below.

1. Navigate to Provisioning, then click Provision Microsoft Entra ID Users to open the Attribute Mapping screen.

2. Delete all default mappings shown in the list.

3. Manually add the following attributes one by one:

SCIM Attribute (SigningHub)	Azure AD Attribute	Mandatory?
email[type eq "work"].value	mail	Yes
active	accountEnabled	No
title	jobTitle	No
userName	displayName	Yes
name.givenName	givenName	No
name.familyName	surname	No
phoneNumber[type eq "work"].value	mobile	No
roles[primary eq "True"].value	Custom expression	No
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization	companyName	No

1. Email is the primary identifier in SigningHub and is required for all user-related operations.

   1. It must be mapped to the Azure AD mail attribute.

   2. Set Matching Precedence to 1 to ensure it's treated as the unique key.

   3. If email is not correctly mapped, provisioning will fail.

   
2. The target attribute names can be customised but must align with the schema expected by the SCIM client (SigningHub).

3. Role mapping requires a custom attribute expression.

   1. For roles[primary eq "True"].value, use a custom expression to map Azure AD app role assignments to the enterprise role in SigningHub.

   2. This allows the correct role to be assigned automatically during provisioning.

   
4. All mandatory attributes (marked "Yes" in the table) must be configured. If any required attribute is missing or misconfigured, provisioning will not work.

5. Attribute formats must exactly match what the SigningHub SCIM client expects. This applies especially to structured attributes like email, phone number, and roles (e.g.,email[type eq "work"].value).

6. You may choose optional attributes like job title or mobile number based on your organisation’s needs, but they are not required for successful provisioning.

---

Trigger On-Demand Provisioning

Azure AD auto-provisioning runs every 40 minutes, which can delay testing or first-time setup. To speed up validation, use on-demand provisioning to manually trigger user or sync.

Follow the steps below to trigger on-demand provisioning:

1. Navigate to Provisioning, then click Provision Microsoft Entra ID Users.

2. Scroll down and click Provision on demand.

3. Search for a user and click Provision.

   

1. Use this method during initial setup to validate attribute mappings and API connectivity.

2. If provisioning fails, it may indicate:

   • Invalid or expired token,

   • SCIM endpoint is unreachable,

   • Attribute mismatch.

     
3. If auto-provisioning stops due to such errors, manual intervention may be needed to restore it.

---

SCIM Provisioning Behaviour

The following table outlines how user account actions in Azure AD are automatically reflected in SigningHub through SCIM provisioning.

Azure AD Action	SigningHub Response	Description
New user added	User account is automatically created	A new SigningHub user is created based on the SCIM mapping.
User details updated	User details are automatically updated	Updates to fields like job title, company name, mobile number, or role are synced.
User account disabled	User account is automatically disabled	The user becomes disabled in SigningHub.
User account deleted	User account is automatically deleted	The corresponding SigningHub user is permanently removed.
Disabled user re-enabled	User account is automatically re-enabled	The previously disabled SigningHub user account is enabled.

1. When auto-provisioning is enabled, all users assigned to the SCIM app in Azure AD will sync with the enterprise.

2. New users not yet registered will be created under the mapped enterprise role. If the role assigned in the identity provider:

   • does not exist in SigningHub, the user will not be registered.

   • is missing, the user will be added under the default enterprise role configured in the SigningHub web application.

3. Users manually created in SigningHub (outside SCIM) are not deleted automatically. These users will only be eligible for SCIM provisioning after they are added to Azure AD, assigned a valid role, and provisioned (either manually or automatically).

4. If the "Restrict users from editing fields" option is enabled in the user's role and the user is provisioned through Azure Active Directory or via SCIM provisioning through Azure Active Directory, any mismatch between their job title and or company in Azure Active Directory and SigningHub's Personal Configurations will result in the values from Azure Active Directory being mapped onto SigningHub, except when the values in Azure Active Directory are empty or null.