Skip to main content
Status

How to setup SCIM between Azure and Motimate?

  • Updated

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.

Prior to starting this process, you must reach out to your Customer Success Manager in Motimate or support@motimateapp.com in order to request the following data which is required to complete the steps below:

  • SCIM Tenant URL
  • SCIM Secret Token

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*
      *) It's requirement in Motimate that all users' phone numbers starts with a plus sign following by country code and then only digits.
      Correct example: +4798765432
      This example will fail: 98765432
      An empty field is okay.
      If a user's mobile number is not correctly formatted, synchronization of that user will fail, and will not be created in Motimate.
      If you are not confident that all phone numbers are correctly formatted, or there is not a need to synchronize phone numbers in Motimate, we recommend that you delete this attribute as well, and it will not be passed on to Motimate for any users.

  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:
    76.png
  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:
    77.png
  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:
    78.png
  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 40 minutes before users are provisioned automatically. After having started provisioning, you can click Provision on Demand in order to provision a few users immediately.

  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:
    79.png
    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.

We highly recommend activating SCIM as soon as possible if you plan to sync your users from Azure AD. If the instructions above look complicated, you can book an hour with us, and we'll walk you through the steps and ensure everything is working. It's usually done in less than 30 minutes, but an hour ensures we have enough time if something unexpected happens.


Additional Technical Notes

Default Mapping

By default we map SCIM attributes in the following way:

Azure AD Attribute customappsso Attribute Motimate Attribute
userPrincipalName userName employee_number
givenName name.givenName first_name
surname name.familyName last_name
mail emails[type eq "work"].value email
mobile phoneNumbers[type eq "mobile"].value phone_number
jobTitle title position


For example, this payload:

{
  "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:

Motimate Attribute Value
employee_number john.doe@example.onmicrosoft.com
first_name John
last_name Doe
email john.doe@example.com
phone_number +4700000000(not +4899999999)
position CTO

 


This mapping can be changed, but only in cooperation with Motimate.

When mapping title to position, Motimate tries to find an already existing position which matches the title. If such a position doesn’t exist, it will be created. It is not possible to synchronize multiple positions per user using SCIM.

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.

 

Related articles

Motimate is a registered trademark. All rights reserved.