As people join and leave your organization, you need to grant and revoke access to Motimate. This standard set of API calls is a set of common commands for Identity Management and makes it esier to maintain good security in the cloud.

The System for Cross-domain Identity Management (SCIM) specification is designed to make managing user identities in cloud-based applications and services easier. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. Its intent is to reduce the cost and complexity of user management operations by providing a common user schema and extension model, as well as binding documents to provide patterns for exchanging this schema using standard protocols. In essence: make it fast, cheap, and easy to move users in to, out of, and around the cloud.

Model

SCIM 2.0 is built on a object model where a Resource is the common denominator and all SCIM objects are derived from it. It has id, externalId and meta as attribute and RFC7643 defines User, Group and EnterpriseUser that extends the common attributes. Go to the SCIM standard docs for more information. Identity Synchronization Across Multiple Nodes is not supported in one org unit. Multiple node mapping must be done on client side.

To try out the SCIM api, goto our Postman documentation of Motimate API:

Register SCIM in Azure Active Directory

Motimate supports automatic data import/sync from Azure AD using SCIM API. You can check out these official Microsoft docs for more information.

To start provisioning Azure AD data to Motimate app, you need to perform the following steps:

1. Add SCIM application.

Go to Enterprise applications

You need to add a non-gallery application:

You can call it whatever you want e.g., Motimate SCIM.

You might not be able to add the non-gallery application because of your current Azure subscription tier. In that case, you should contact Microsoft support to discuss your options. We don’t offer support on choosing the right Azure plan because every company’s case is different.

2. Configure automatic data provisioning

Go to the newly created application settings and enable automatic users data provisioning:

Now fill in the Admin credentials:

You’ll receive Tenant URL and Secret Token from Motimate support. Notification email should be set to your email address.

3. Configure data mappings

You need to configure the following Groups mapping:

Compared to the default group mapping, you need to change the matching attribute from displayName/displayName to objectId/externalId.

and User mapping:

Compared to the default user mapping, you need to change the matching attribute from userPrincipalName/userName to objectId/externalId. To do it, you’ll have to change the mapping from mailNickname/externalId to objectId/externalId.

4. Default mapping

By default we map SCIM attributes in the following way:

SCIM attribute => Motimate attribute

1. userName => employee_number
2. userName => email
3. name.givenName => first_name
4. name.familyName => last_name
5. title => position
6. phoneNumbers with type equal to “mobile” => phone_number

For example, the payload below:

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

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

Notes:

  • 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.

5. Data structure requirements

Email
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
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
Phone numbers must start with the “+” and the country code, e.g. “+4799999999”. Here are some examples of invalid phone numbers:

  • 12345678
  • 004712345678
  • +47 99999999
  • @4712345678

6. Set provisioning scope

After saving the mappings, you need to leave the provisioning tab and come back (it’s an Azure bug). Only then you’ll see the Scope configuration button:

Syncing all the users and groups is not recommended. Instead, you should fine-tune users and groups that will be synchronized to Motimate.

7. Assign groups

Only groups assigned to the application will be synchronized together with all its users. It means that you don’t have to assign every single user manually but only the groups. You can also assign groups as the members of other groups to create a tree structure that will be mapped to Motimate. One thing to watch out, that groups that are members of the other groups are not automatically synchronized. You need to assign every single group to the application.

8. Enable provisioning

When your groups are assigned, you can now turn on the provisioning.

The initial sync has the a of ~30 minutes. All the subsequent changes will be replicated with ~10min delay.

Login to Motimate Admin to view the import logs from SCIM.

9. 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 (Imports => Scim Users => View User => EXTERNAL attribute).

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

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