This document provides guidelines on how to configure Microsoft’s Entra ID identity management system to automatically provision user accounts to Workvivo over an industry standard protocol called SCIM (System for Cross-domain Identity Management).
Workvivo supports automatic user provisioning via a series of SCIM 2.0 compatible
RESTful JSON APIs. In this document, you will learn how to set up Entra ID to
provision users to Workvivo using these APIs.
Important!
- If conducting a Meta Workplace migration DO NOT provision any users until the migration of users is complete.
1. Adding Workvivo as an Enterprise Application in Entra ID
The first step to configuring Workvivo in Entra AD is to set Workvivo up as an Enterprise application using the Entra ID portal.
Check out our Microsoft Entra ID - Single Sign On article and follow step 1 to add Workvivo as an Enterprise application.
If you have already set up Workvivo as an application in Entra ID for Single Sign On purposes, you can skip this step and go directly to the existing Workvivo application in Entra ID.
2. Setting up Provisioning Tenant URL and Secret Token
Navigate to the Workvivo Enterprise application you have created in your Entra ID instance.
On the left-hand-side, under the "Manage" sub-navigation list, click on "Provisioning" to go to the provisioning setup screen.
By default, the "Provisioning Mode" is set to "Manual". Change this field to "Automatic" and a series of new fields will appear on the screen. The first step is to enter the Admin Credentials for the Workvivo SCIM API.
Under "Tenant URL" enter the following:
https://[yourworkvivodomain]/azure/v2/scim
Where "yourworkvivodomain" is the domain name for your Workvivo instance, e.g. https://[companyname].workvivo[.com][.us][.me]
*Note - Depending on whether your Workvivo instance is hosted on our EU, US, or UAE data center, make sure you enter the correct domain. It will either be workvivo.com, workvivo.us, or workvivo.me. The format may also differ if your organisation has configured a custom domain name for Workvivo. If you do not know your Workvivo domain name, please contact our Support team at support@workvivo.com for assistance. Press the “Save” button to continue.
Under "Secret Token" please reach out to the Workvivo Support Team at support@workvivo.com for this token. Please also let us know you're leveraging Microsoft Entra ID for SCIM provisioning, as we will need to configure an item on our side.
Note that this token can’t be recovered so if you lose it a new token will need to be generated and set up in Entra ID.
Press the "Test Connection" button – Entra ID should respond with a success message. Now press the "Save" button at the top of the screen - once again, Entra ID should respond with a success message.
3. Disabling 'Provision Microsoft Entra ID Groups'
At this point, there should be two records displayed under the Mappings section, as shown below:
For the majority of customers, we don’t need to synchronise Entra ID groups as we can get the relevant team data required for Workvivo directly from the user resource. So click on "Provision Microsoft Entra ID Groups" to edit the mappings for Entra ID Groups.
On the screen that opens, under "Enabled" click “No” to disable Entra ID Groups provisioning and click the "Save" button at the top of the screen. Click "Yes" to confirm your changes.
When this is completed, click the "X" at the top right of the window to close the Attribute Mapping screen and return to the previous screen. You should see "No" under the "Enabled" column for Entra ID Groups in the Mappings section.
3. Configuring Entra ID User Mappings
The final step is to confirm the mappings for Entra ID Users. Click on "Provision Microsoft Entra ID Groups" to open the Attribute Mapping screen for Entra ID Users. Under "Attribute Mappings", verify that the Entra ID attributes being mapped are the correct ones for your organisation. In most cases the default options should work.
The following are the "Customappsso" attributes that are used in Workvivo, and how they are used:
-
externalId
Used by SCIM provisioning as the unique identifier to determine when to add or update users in Workvivo. By default this is set to mailNickname however if users do not have unique mailNicknames we recommend changing the source attribute here to a more unique value for example objectID or userPrincipalName
- userName*
We map this to email in Workvivo. By default this is set to "userPrincipalName" in Entra ID – if this attribute’s value is not an email address in your organisation you should use a different attribute here (e.g. "mail") -
emails[type eq "work"].value*
We map this to email in Workvivo. By default this is set to "userPrincipalName" in Entra ID – if this attribute’s value is not an email address in your organisation you should use a different attribute here (e.g. "mail").
*Very important userName & emails[type eq "work"].value are mapped to the same value
-
name.givenName
The user’s first name
-
name.familyName
The user’s surname
-
title
The user’s job title
-
phoneNumbers[type eq "mobile"].value
The user’s mobile phone number. This is an optional field in Workvivo
-
phoneNumbers[type eq "work"].value
The user’s direct dial number. This is an optional field in Workvivo
-
active
Whether the user’s account should be active or not
-
department
The user’s department. This will be set up as a team in Workvivo – if it doesn’t already exist it will be created and the user will be assigned to it automatically. This will map to the Primary Team in Workvivo Adv Analytics
-
addresses[type eq "work"].locality
The user’s location (defaults to “city” in Entra ID). This will be set up as a team in Workvivo – if it doesn’t already exist it will be created and the user will be assigned to it automatically. This will map to the Secondary Team in Workvivo Adv Analytics
- urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter - this is not a default mapping you will need to add this as an additional attribute. This will map to the Tertiary Team in Workvivo Adv Analytics
Please let your Workvivo IT contact know your preferred primary, secondary & tertiary teams so this can be configured on the Workvivo side.
Again, most organisations shouldn’t need to change the default mappings, but you can if you would like to use different Entra ID attributes for the given Workvivo field (e.g. use a different attribute for location other than "city").
When you are happy with the mappings, click the "X" button to close the window.
4. Additional Attributes
If you would like to map additional Attributes please follow the below syntax.
In Attribute Mapping – choose Show advanced options - Edit attribute list for customappsso
From here you can edit the Attribute List.
Hire Date:
urn:ietf:params:scim:schemas:extension:workvivo:2.0:User:hireDate – value needs to be YYYY-MM-DD
Date of Birth:
urn:ietf:params:scim:schemas:extension:workvivo:2.0:User:dateOfBirth – value needs to be YYYY-MM-DD
Cost Center:
You will first need to tell your Workvivo IT contact the name of your cost center tertiary team type e.g Office, Tenant, Country
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:costCenter
Custom Team Types:
You will first need to tell your Workvivo IT contact the name of your additional team types e.g Office, Tenant, Country
urn:ietf:params:scim:schemas:extension:workvivo:2.0:User:wvtax_TeamTypeName e.g: urn:ietf:params:scim:schemas:extension:workvivo:2.0:User:wvtax_Office
Custom Fields:
You will first need to tell your Workvivo IT contact the name of your additional fields e.g Pronouns, Employee Number
urn:ietf:params:scim:schemas:extension:workvivo:2.0:User:CustomFieldName e.g. urn:ietf:params:scim:schemas:extension:workvivo:2.0:User:Pronouns
Auth Roles:
If you would like to provision user roles, please use the following syntax:
urn:ietf:params:scim:schemas:extension:workvivo:2.0:User:authRoles
Value: admin, space moderator
5. Starting the Provisioning sync
The provisioning setup is now complete. If you'd like to test first, please provision a few users on Demand to make sure they are coming across to us correctly. The user will need to be added to Users/Groups prior to actioning this.
One successful, within the overview section, you can click "Start provisioning"
The initial synchronization can take up to an hour depending on how many users are in scope.
Entra ID typically provisions data every 20 - 40 minutes although this may vary depending on the number of users in your Entra ID instance.
At this point, you may notify your Workvivo contact that you have started the provisioning process in Entra ID. They can check our relevant internal logs to ensure that the process is working as expected. Once the provisioning process starts to work, you can review the provisioning logs in Entra ID.
If there are any problems with provisioning you’ll see information about these errors in the logs. Unfortunately these aren’t very helpful – so if there are errors, please contact Workvivo for assistance as we have more useful logging in place on our side that will help to diagnose any issues with provisioning.