Motimate: How to setup SCIM between Azure and Motimate?

Enable a SCIM integration between your Azure Active Directory (AD) and Motimate, in order to synchronize users automatically in Motimate.

Motimate supports automatic data import/sync from Azure AD using SCIM API. You can also check out Microsoft's Tutorial: Develop and plan provisioning for a SCIM endpoint in Azure Active Directory in order to learn more.

 

Limitations to be aware of

While the SCIM integration will let you import and keep your users synched between Azure (now Entra ID) and Motimate, all users will be getting the standard 'normal user' user role, and 'member' role in all groups. Any users who should have other roles will need to be manually updated once they have been imported. You can read more about the various types of roles in Motimate here.

Setting up SCIM between Microsoft Azure and Motimate

1. Log in to your Microsoft Azure Portal with a Microsoft Azure Admin account.
    
2. Start by searching for Enterprise Applications in the search bar at the top of the Azure Portal, and click it when it appears.
    
3. A new page for Enterprise Application settings appear. Here you should click New Application at the top of the page.
    
4. Then click Create Your Own Application at the top of the page.
    
5. In the window that appears on the right, you need to give this Name to your app: Motimate SCIM.
    
6. Then select the following radio-button:
   Integrate any other application you don't find in the gallery (Non-gallery).
    
7. Click Create, and you'll soon be taken to the Overview page of your new application.
    
8. Now you should go to Provisioning in the left-side menu, and then click the Get Started button.
    
9. You will now need to set Provisioning Mode to Automatic.
    
10. Enter the Tenant URL and Secret Token you received from Motimate. If you have not yet contacted Motimate to obtain these, you will not be able to proceed.
     
11. Click Test Connection to make sure it's successful. It could take a few seconds, but you'll see a notification in the top right corner when it's completed.
    • If the test fails, please double-check that you've entered Tenant URL and Secret Token exactly as provided from Motimate.
       

    • The Tenant URL will typically have this format:

      https://{identifier}.motimateapp.com/scim/v1

      Remember to replace {identifier} with that of your Motimate account.
       

    • The Secret Token will consist of a mix of 32 characters and numbers, e.g.:

      5e188cf76084d08cde4b7d68083f27c4

      (this example Token will NOT work, so don't use it)
       

12. When the test is successful, you must click Save before you can continue.
     
13. When the settings have saved, a new section for Mappings will appears below the Test Connection button.
     
14. Please expand the Mappings section, and then click Provision Azure Active Directory Users.
     
15. Scroll down until you see the Attribute Mappings section.
     
16. First you have to find the Azure Active Directory Attribute in the first column called mailNickname.
     
17. Click on mailNickname, and a new window to Edit Attribute will open.
     
18. You must change Source Attribute from mailNickname to objectId.
     
19. Then select Yes in the drop-down for Match objects using this attribute.
     
20. Click OK.
     
21. You now have to make sure you keep all of the following Azure Active Directory Attributes in the first column:
    • objectId
    • Switch([IsSoftDeleted], , "False", "True", "True", "False")
    • jobTitle
    • mail
    • userPrincipalName
    • givenName
    • surname

    • mobile*
      
      *) Phone numbers must start with a plus sign, followed by the country code and digits only:

      Correct: +4798765432
      Incorrect: 98765432

      Empty field is allowed. Incorrect format will prevent synchronization. If you are unsure of the format or do not need to synchronize numbers, we recommend removing this attribute.

22. You can Delete the following:
    • displayName
    • preferredLanguage
    • Join(" ", [givenName], [surname])
    • physicalDeliveryOfficeName
    • streetAddress
    • city
    • state
    • postalCode
    • country
    • telephoneNumber
    • facsimileTelephoneNumber
    • employeeId
    • department
    • manager
       
23. Now you must click the attribute userPrincipalName to open the Edit Attribute window.
     
24. Change the drop-down for Match objects using this attribute to No, and then click OK.
     
25. Then click the attribute objectId to open the Edit Attribute window again.
     
26. This time change the value for Matching precedence to 1, and then click OK.
     
27. Your list of Attribute Mappings should now look like this:
    
    
     
28. If everything looks correct, you can now click Save at the top, and then Yes.
     
29. Very Important: Unfortunately, due to a bug in Azure, you will now need to go back to the Overview of your Motimate SCIM Application and follow these instructions:
    1. Click Provisioning in the menu to the left again.
    2. Click Edit Attribute Mappings under the Manage Provisioning section.
    3. Expand the Mappings section and click Provision Azure Active Directory Users again.
    4. Now most likely the name of the first Azure Active Directory Attribute has unfortunately changed name back to mailNickname.
    5. Please click mailNickname and in the Edit Attribute window, change Source Attribute back to objectId.
    6. Click OK, then Save at the top, and then Yes.
    7. This step is very important to correct, otherwise all users will fail to synchronize with Motimate.
        
30. After fixing the bug above, you can go back to Provisioning settings. You can get there by clicking > Provisioning > at path in the very top here:
    
    
     
31. This time you should click Provision Azure Active Directory Groups.
     
32. In the Attribute Mappings section, click the Azure Active Directory Attribute called objectID.
     
33. In the Edit Attribute window, change Match objects using this attribute to Yes, and click OK.
     
34. Then click the attribute displayName.
     
35. In the Edit Attribute window, change Match objects using this attribute to No, and click OK.
     
36. Now click the attribute objectID again, and change Matching Precedence to 1, and click OK.
     
37. Your list of Attribute Mappings should now look exactly like this:
    
    
     
38. If everything looks correct, you can now click Save at the top, and then Yes.
     
39. You can now click the X in the top right corner below your username and profile picture. Click it twice, to get back to your Application settings.
     
40. Configuration of your application is now completed, and we need to test synchronization of a couple test users.
     
41. Click Users and groups in the menu to the left. This is where you would normally add the groups that will be synchronized with Motimate, but for testing, you just just add a users or two instead.
     
42. Click Add user/group at the top of the screen.
     
43. Click None Selected under Users.
     
44. Search and find a user which you would like to test. We recommend testing your own user, perhaps also your organization's Motimate org admin (if that's not you). If you have created a user account for testing for your contact in Motimate, please add this account as well.
     
45. All the users you've selected will appear under Selected Items. When done, simply click the Select button below them.
     
46. Now click the Assign button.
     
47. You are now ready to turn on provisioning to test that everything is working. However before you do so, you must send an email to your Motimate contact or to support@motimateapp.com to notify us that you plan to turn on provisioning. With this email you must let us know the Object ID, User Principal Name (UPN), and Email of each user that you plan to test. In addition you must attach screenshots of the Attribute Mappings for the following:
    • Provision Azure Active Directory Users
    • Provision Azure Active Directory Groups
       
48. We will get back to you and confirm that you can turn on provisioning if everything looks correct.
     
49. In order to turn on provisioning, click Provisioning in the menu to the left.
     
50. Then click Start Provisioning at the top of the screen.
     
51. It could take up to several hours before users are provisioned automatically. After having started provisioning, you can click Provision on Demand in order to provision a few users quicker (how soon the users will turn up in Motimate depends on how much data is being transferred at that particular time).
     
52. Search for one of the users that you added for testing. Select the user, and then click the Provision button at the bottom. You can only provision a single user on demand at a time, and you can only provision users already added to the application under Users and Groups. They must be added directly, or be direct members of an added group.
     
53. If the provisioning was successful, all the check-marks will be green like this:
    
    If the provisioning fails for any reason, you must take a screenshot of your entire screen, as well as under View details of the step that failed. Please send this to your Motimate contacts for troubleshooting.
     
54. If the provisioning was successful, you can click the button Provision another user in order to add the other users you would like to test.
     
55. When Provision on Demand has been completed for all test users, please email Motimate to confirm that you've completed Provisioning.
     
56. We'll confirm if everything looks fine on our end, and you will then be able to add groups for provisioning as well.
     
57. You should discuss Motimate group structure with your Motimate contact before you start provisioning groups.

Congratulations! You've now successfully set up SCIM between Azure and Motimate.

Additional Technical Notes

Default Mapping

By default we map SCIM attributes in the following way:

{
  "name":{
  "formatted":"John Doe",
"givenName":"John",
"familyName":"Doe"
  },
"title":"CTO",
  "active":true,
"emails":[
    {
      "type":"work",
"value":"john.doe@example.com",
      "primary":true
    }
  ],
"userName":"john.doe@example.onmicrosoft.com",
  "externalId":"cc5c3f1b-e046-40e8-a317-5e71b2b73286",
  "displayName":"John Mark Doe",
"phoneNumbers":[
    {
      "type":"mobile",
"value":"+4700000000",
      "primary":false
    },
    {
      "type":"work",
      "value":"+4899999999",
      "primary":true
    }
  ],
  "preferredLanguage":"en-US",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User":{
    "department":"DevOps"
  }
}

... will create a Motimate user with the following attributes:

Email Format Requirements

Email address must follow standard email format rules, for example:

• No @ symbols or whitespaces in either the localpart or the domain.
• There must be a single @ symbol separating the localpart and the domain.

Employee Number Requirements

The most important requirement is that employee numbers must be unique. Our default mapping sets employee numbers based on the SCIM userName attribute, which means that userNames on your side have to be unique, too.

Another requirement for employee numbers is that it cannot contain any whitespace characters.

Phone Number Requirements

Phone numbers must start with "+" and the country code, e.g. "+4799999999". It also should not contain any whitespace characters. Here are some examples of invalid phone numbers:

• 99999999
• 004799999999
• 4799999999
• @4799999999

About external_id

SCIM sends externalId which is usually equal to User or Group’s Active Directory Object ID. This externalId can be fetched via our SCIM API. It's also displayed in Motimate Admin Panel under Imports>SCIM Users>View User>EXTERNAL attribute.

Note: There is no association between SCIM externalId and the Motimate Users and Groups external_id attribute, which can be fetched with our OpenAPI.

If you have any questions, please contact support@motimateapp.com.