WATS Provisioning (SCIM)

To make creating new users easier, we now introduce WATS Provisioning. WATS Provisioning is an addition to the existing API to allow WATS to communicate with SCIM-compliant provisioners to automatically create, update, and disable/delete user accounts in WATS.

SCIM (System for Cross-domain Identity Management) is a specification for user provisioning cross-domain through specific behaviours for API actions. Read more about it here: IETF RFC7644

For WATS, the intended application is through Azure and is the only officially supported channel, but users can experiment with other SCIM-compliant providers (Okta, Google) as well.

WATS Provisioning is meant to be used alongside Microsoft Entra ID Authentication, which is also a requirement to set up through the Microsoft Entra ID Gallery. To enable, see Microsoft Entra ID integration. 

 NOTE: WATS Provisioning is supported from WATS version 23.1

To set up WATS Provisioning, please note that there is two ways to create a provisioning application in Azure:

• Using the pre-made WATS app from the Microsoft Entra ID Gallery
• Creating your own Enterprise Application

We recommend using the Microsoft Entra ID Gallery to set up provisioning.

Before setting up, you need to prepare this:

• Your tenant URL with the SCIM endpoint: https://<your_WATS_instance_url>/api/SCIM/v2/
  • Replace <your_WATS_instance_url> with your URL; example.wats.com
• A Bearer token generated through your instance.
  • You can call this URL directly: https://<your_WATS_instance_url>/api/SCIM/v2/Token?duration=90 (Change 90 if you wish to generate a longer-lived token measured in days) or generate a token through the WATS API documentation under the “SCIM” header then calling the “/api/SCIM/v2/Token” endpoint.

Microsoft Entra ID Gallery setup

NOTE: If you have multiple WATS Instances and wish to have provisioning for all of them, you will be required to create additional Enterprise Applications and set them up for each Instance. Please follow the steps here.

The Enterprise Application is automatically added to the Microsoft Entra ID when setting up authentication through Entra ID Authentication. This is a requirement to use the application provided through the Microsoft Entra ID Gallery. After following the steps to add Entra ID Authentication, configure Provisioning by following from step 3 in the WATS Provisioning Tutorial from Microsoft or following these steps:

1. Log in to the Azure Portal with your Azure account.
2. Navigate to your Microsoft Entra ID and go to the Enterprise Applications tab.
3. Find WATS in the list of Enterprise Applications
4. Select the Provisioning tab
   1. We recommend setting the “Assignment Required to enabled and “Visible to users” to disabled in the Properties tab beforehand.
      
5. Set “Provisioning Mode” to automatic.
6. Under the “Admin Credentials” section, Fill out the “Tenant URL” field with the tenant URL and the “Secret Token” field with the Bearer token you generated earlier.
7. Click “Test Connection”. Azure will verify the setup.
8. Click Save.
9. Under the “Mappings” section, click “Synchronize Azure Active Directory Users to WATS.
10. Verify that the attributes looks like this:

    userPrincipalName	userName
    mail	emails[type eq "work"].value
    givenName	name.givenName
    surname	name.familyName
    SingleAppRoleAssignment([appRoleAssignments])	roles[primary eq "true"].value
    IIF([IsSoftDeleted], "false", "true")	active

11. Navigate to the “Settings” section and fill out according to your needs. We recommend setting the scope to “Sync only assigned users and groups” if you want to only provision assigned users.
12. Toggle “Provisioning Status” to on in the Settings section and click save.
    

Azure will now connect to WATS and start the provisioning cycle. You can now navigate to the "Users and Groups" tab to assign users to the provisioning. 

We recommend starting small when rolling out provisioning for your users. Test with a few users, then scale up.

We currently support the standard WATS roles (Administrator, Viewer, Analyzer, Manager, Operator) and custom roles. If you wish to create your own roles, please refer to the "Creating WATS Roles in Azure" section of the guide to create your own role entries. WATS will throw an error if the role does not exist, which will pause the Provisioning job. If this happens, please make changes to the Entra ID roles or add the role in WATS. To make provisioning new Microsoft Entra ID users easier, we recommend creating or assigning relevant groups in your Microsoft Entra ID for each of the desired roles.

Creating your own Enterprise Application

If you wish to create your own Enterprise Application, please follow these steps instead:

1. Log in to the Azure portal with your Azure account.
2. Navigate to your Microsoft Entra ID and go to the "Enterprise applications" tab on the left-hand menu.
   
3. Click on the "New application" button then “Create your own application”.
    ->
4. Fill out the necessary details, use something easy to recognise such as "WATS Provisioning" or "WATS SCIM" for the name. Ensure "Integrate any other application you don't find in the gallery (Non-gallery)" is checked. Click "Create" to continue.
   
   
5. After the application is created, it is recommended to navigate to the “Properties” tab and enable “Assignment required” and disable “Visible to users”.
6. Select "Provisioning" from the left-hand menu and click on "Get Started."
7. Under “Admin Credentials”, fill the “Tenant URL” field with "https://<your_WATS_instance_url>/api/SCIM/v2/".
8. Generate a secret token through this URL: https://<your_WATS_instance_url>/api/SCIM/v2/Token?duration=90 (Change 90 if you wish to generate a longer-lived token measured in days) or through the WATS API (see here) and fill the “Secret Token” field with this token. The fields should look something like this:
9. Click “Test Connection”. If the token or URL cannot be verified, Azure will return an error.
10. Under “Mappings”, click “Provision Azure Active Directory Groups”, set “Enabled” to No, then save.
11. Under “Mappings”, click “Provision Azure Active Directory Users” and ensure the “Attribute Mappings” are set to these values:

    userPrincipalName	userName
    mail	emails[type eq "work"].value
    givenName	name.givenName
    surname	name.familyName
    SingleAppRoleAssignment([appRoleAssignments])	roles[primary eq "true"].value
    IIF([IsSoftDeleted], "false", "true")	active

12. Note: SingleAppRoleAssignment and IIF requires "Mapping Type" to be set to "Expression":
13. Ensure all values are the same as provided above. userPrincipalName is used to match objects and should be the only field with a "Matching Precedence". The other fields should not be populated in this column. If using a provisioner other than Azure, apply a mapping named "PasswordSignInEnabled" and set this to true, or users will not be able to login and will require an administrator or manager to enable local login.
14. Click Save.
15. Under “Settings” in the “Provisioning” tab, set “Scope” to “Sync only assigned users and groups”. Fill out the other fields as desired.
16. When finished, toggle “Provisioning Status” to On and click Save.
    

Azure will now connect to WATS and start the provisioning cycle.

You can now add users under the “Users and groups” tab and Azure will automatically provision them on a 40-minute cycle (Azure-defined, this cannot be changed).

Creating WATS Roles in Azure

By default, WATS will assign users the “Analyzer” role when creating new users. We recommend creating custom roles that can be assigned in the application that allows for easier synchronization of user roles to WATS:

1. Log in to the Azure portal with your Azure account.
2. Navigate to your Microsoft Entra ID and go to the "App Registrations" tab.
3. Find the Enterprise application you created above in the list.
4. From the left-hand menu, select “App roles”.
   .
5. Click “Create app role”.
   

From here, you can create roles for the standard WATS roles (Administrator, Viewer, Analyzer, Manager, Operator) or your own custom roles.  

An example setup can be seen in the screenshot below:

Note: We use Display name to match to roles in WATS, but for simplicity sake we recommend providing the same role name in both the Display name and Value fields. The text "WATS " is also reserved and will be removed when processing the request, so do not use this in your WATS role. 

Here is a full example of all WATS standard roles and their properties:

After setting up roles, you can go back to the Enterprise Application by navigating back to your Microsoft Entra ID, then selecting your application under Enterprise applications in the left-hand menu, where you can now (after Azure syncs the roles) assign groups or individual users to the roles you created. The role sync can take up to an hour.

We recommend creating individual Microsoft Entra ID Gallery roles for each WATS role to make assigning new users easier or use suitable roles existing in your Directory already.