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, but we have also implemented steps to support Okta. See here

WATS Provisioning is meant to be used alongside either Microsoft Entra ID Authentication or a Custom Single Sign On authentication. Having Entra ID Authentication is a requirement for the Microsoft Entra ID Gallery application. 

 NOTE: WATS Provisioning through Entra ID is supported from WATS version 23.1 and through Okta from WATS version 24.2

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. 

NOTE: From WATS Cloud version 2025.1, we have added additional attributes that can be configured.

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

    NOTE: We currently only support assigning a single role through SCIM.
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.

NOTE: From WATS Cloud version 2025.1, we have added additional attributes that can be configured.

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.

Okta setup

Setting up an application for Okta is similar to Azure, but with some differences. Some things are also unsupported in Okta for now, mainly updating the user object. 

1. Log in to your Okta tenant
2. Navigate to Applications under the Applications tab in the sidebar
3. Click Browse App Catalog
4. Search for "SCIM 2.0 Test App (OAuth Bearer Token)
5. Add the app to your tenant, then navigate to the created application. Note: We recommend setting the "Application username format" to Okta username and create only, and Sign On Method to Secure Web Authentication with Administrator sets username, user sets password.
6. Open the "Provisioning" tab
7. Click edit on the "To app" tab. Make sure "update user attributes" and "sync password" are disabled. These are currently not supported.
8. Click save.
9. Edit the profile to follow these values
10. For email, follow these settings
11. If roles are to be included, make sure the settings are as followsMake sure the external name and namespace is exactly as shown. These are case sensitive. Attribute members and enum are optional, but highly recommended. Make sure the "Display name" and "Value" have the same string, and that the role exists in WATS. The characters "WATS " will be removed during validation. We currently only support assigning a single role using SCIM.
12. If levels and productGroups are to be included, make sure the settings are as followsSettings is the same for productGroups, just replace "levels" with "productGroups". Ensure the "Display name" and "Value" have the same string, and that the level/productGroup exists in WATS.
13. After configuring the profile, navigate back to the provisioning tab of the application you created.
14. Under the integrations tab, fill out your WATS url and bearer token as shownToken is generated in WATS. On how to generate, read the requirements further up in the document.
15. (Optional) In the "To app" section, you can experiment with various mappings to automatically add to each user object. 
16. Under the "Assignments" tab, you can add users to your application. There might be some differences for assigning a group, which might require some testing. We recommend individually adding each user directly for Okta. 

Okta is more strict in the way they add data to the provisioning objects, so ensure they're as shown in the images.

We also recommend adding a small group of users first before rolling out all applicable users. This will allow any errors to be caught early in the implementation process.