Create a Custom Enterprise Application for Your Litmos Organization

Clients can configure an end-to end SCIM integration to manage the employee lifecycle from Microsoft Azure Active Directory. Currently, this must be performed by performing the following steps:

1. Log into the Azure AD portal as an Administrator and click to Azure Active Directory

   

2. Select “Enterprise Applications” from the Azure sidebar menu and then choose “+ New Application” from the buttons across the top.

   

3. Choose the option to “+ Create your own application” provide a name for the app and then select the option, “Integrate any other application you don’t find in the gallery”.

   

4. Follow the getting started steps to:

• • • Assign Users
    • Assign Groups
    • Setup single sign on (SAML)
    • Provision User Accounts

Enable User Provisioning for the Custom Litmos Application

When it’s time to “Provision User Accounts”, the Admin will click “Get started”.

The provisioning mode can be manual or automatic. Choose Automatic to setup automated SCIM provisioning cycles.

Enter the URL https://api.litmos.com/v2/scim as the tenant URL, and the Secret token that is generated from the SCIM integration listing within your Litmos tenant. The Secret token can be generated by logging into the Litmos tenant as an Account Owner. Navigate to Account –> Integrations –> SCIM –> Create a SCIM Token.

Important Note: The tenant URL may be different if your Litmos organization is hosted in the AU or EU environment (i.e. https://api.litmos.com.au/v2/SCIM or https://api.litmoseu.com/v2/SCIM).

Once the token and the tenant URL have been entered, click “test connection” to ensure that the Azure AD tenant has been authorized for SCIM user provisioning and synchronization with your Litmos Training tenant.

Once the connection test is successful, press “save” and proceed to the user mappings.

Configure User Mappings for the Custom Application

Click into “Provision Azure Active Directory Users” to view and edit the user record field mappings.

This user mappings page will display options for attribute mapping “source object scopes” and “target object actions”. Please consult with your IT admin if you feel these settings need to be updated. It is best to leave the settings alone to ensure that all user records are in scope for the provisioning cycles and that all target object actions will be initiated.

The attribute mappings will display below. The initial list will be the Azure default attribute mappings.

Some of the fields in this default attribute mappings list will need to be deleted because some of these fields don’t exist on the Litmos user record, while others are not yet supported to match fields on the Litmos user record:

• • • displayName (doesn’t exist)
    • preferredLanguage (not supported yet)
    • Join(” “, [givenName], [surname]) (doesn’t exist)
    • physicalDeliveryOfficeName (doesn’t exist)
    • facsimileTelephoneNumber (doesn’t exist)
    • mailNickname (doesn’t exist)
    • department (doesn’t exist)

Before performing any additional mappings, review the attributes selected as Matching properties for the custom Litmos app. These are used to match the user records in Litmos Training for update operations. After these have been reviewed, make sure to “save” the current attribute mapping definitions.

Add New Mappings to the User Mapping for the Custom Litmos Application

Once these mapping definitions have been saved, the Admin can proceed to “add new mappings” if that is what your organization requires. First, it’s important to review the list of all supported attribute mappings for this SCIM provisioning integration. Litmos supports a variety of core, enterprise and customextension fields in the attribute field mappings. To learn more about core fields, enterprise fields and customextension fields in the SCIM user schema, review the Azure tutorial on user attribute mappings for SaaS applications.

Below is the list of attributes that are supported for the field mapping on the user provisioning cycles from Azure AD to Litmos Training:

Azure Active Directory Attribute	Custom Litmos App Attribute
userPrincipalName	userName
Switch([IsSoftDeleted], , “False”, “True”, “True”, “False”)	active
jobTitle	title
mail	emails[type eq “work”].value
givenName	name.givenName
surname	name.familyName
streetAddress	addresses[type eq “work”].streetAddress
city	addresses[type eq “work”].locality
state	addresses[type eq “work”].region
postalCode	addresses[type eq “work”].postalCode
country	addresses[type eq “work”].country
telehphoneNumber	phoneNumbers[type eq “work”].value
mobile	phoneNumbers[type eq “mobile”].value
employeeId	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber
manager*	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
companyName	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField1
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField2
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField3
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField4
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField5
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField6
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField7
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField8
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField9
Azure Active Directory Attribute	urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User:CustomField10

Important Note: The Manager field currently cannot be used until the Litmos application is certified by Microsoft

Be sure to review the list of fields that are currently supported in the Litmos Training SCIM 2.0 user and group schema.

User Schema:

{
  "active": "{true/false}",
  "addresses": [
    {
      "country": "{user.country}",
      "locality": "{user.city}",
      "postalCode": "{user.zip}",
      "region": "{user.state}",
      "streetAddress": "{user.address}",
      "type": "{work}"
    }
  ],
  "emails": [
    {
      "type": "{work}",
      "value": "{user.email}"
    }
  ],
  "externalId": null,
  "id": "{user.litmosId}",
  "name": {
    "familyName": "{user.firstname}",
    "givenName": "{user.lastname}"
  },
  "password": null,
  "phoneNumbers": [
    {
      "type": "{mobile/work}",
      "value": "{user.phone}"
    }
  ],
  "preferredLanguage": "{user.language}",
  "roles": [
    {
      "primary": "{true}",
      "type": "AccessLevel",
      "value": "{Learner/Account Owner/Administrator}"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
    "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User"
  ],
  "timezone": "{user.timezone}",
  "title": "{user.title}",
  "urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:CustomField:User": {
    "CustomField1": "{user.CustomField1}",
    "CustomField2": "{user.CustomField2}",
    "CustomField3": "{user.CustomField3}",
    "CustomField4": "{user.CustomField4}",
    "CustomField5": "{user.CustomField5}",
    "CustomField6": "{user.CustomField6}",
    "CustomField7": "{user.CustomField7}",
    "CustomField8": "{user.CustomField8}",
    "CustomField9": "{user.CustomField9}",
    "CustomField10": "{user.CustomField10}"
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "{user.externalEmployeeId}",
    "manager": {
      "value": "{user.manager.litmosId}"
    },
    "organization": "{user.company}"
  },
  "userName": "{user.username}"
}

Group Schema 

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "{team.name}",
  "members": [
    {
      "value": "{user.litmosId}",
      "type": "{User}"
    }
  ],
  "externalId": "{team.litmosId}",
  "id": "{team.litmosId}",
  "meta": {
    "resourceType": "Group"
  }
}

The 10 CustomExtension fields that have been designed to map to user custom fields on the user records in the Litmos application. This provides Admin with the flexibility of choice to map 10 select Azure AD user object fields to Litmos user records.  The 10 custom fields on the user object in Litmos that support matching to these CustomExtension fields can be found by logging into Litmos as an Account Owner and navigating to Account –> Messages & Settings –> Custom fields:

To begin customizing the attribute mappings, click the “Add New Mapping” link.

In the example below, the companyName field on the Azure user object is being mapped to the company field on the Litmos user object.

Notice that the target attribute for the custom Litmos app is displayed as “urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:organization” (instead of something like “company”). That’s because this is the syntax that has been given for the organization field in the standard SCIM user schema. Organization data belongs to the extension enterprise field group in the SCIM user schema.

To alter the entire list of attributes for the target application (Litmos), click the checkbox “show advanced options” and then click the link “edit attribute list for custom SSO”.

Attributes can be added and removed, or the syntax of the attributes can be modified as needed (depending on the solution providers requirements for the syntax given on certain fields supported in the SCIM user schema).

This is the option an Admin will select if the Admin wishes to add the CustomExtension fields to the field mapping for the Litmos Training field mapping (as shown below).

Once the list of attributes has been edited for the target application (i.e. a CustomExtension field has been added), return to the attribute mapping page and select an Azure Active Directory Attribute to map to the attributes for the target app (i.e.

Press “save” to save the new attribute mappings for the custom Litmos application and the mapping will be added to the list.

Important Note: Group mappings can be viewed but they do not need to be updated for this integration. To view the group mappings, click “Provision Azure Active Directory Groups” from the Provisioning page. Please also note that the Azure AD user provisioning service can’t read or provision users in nested groups. The service can only read and provision users that are immediate members of an explicitly assigned group. This limitation of “group-based assignments to applications” also affects single sign-on (see Using a group to manage access to SaaS applications). Instead, directly assign or otherwise scope in the groups that contain the users who need to be provisioned.

Resource: https://docs.microsoft.com/en-us/azure/active-directory/app-provisioning/how-provisioning-works

Important Note: There is an option to enter an email address that will receive notifications for provisioning cycle failures. It is recommended that an email address belonging to an IT mailbox is given.

Important Note: The scope of the provisioning can be set to all users and groups, but it is recommended to leave it for assigned users and groups only so that provisioning rules or select records can be eligible for provisioning cycles to the custom Litmos application.

Now your organization is just about ready to begin your provisioning deployment! Make sure that users and groups have been assigned to the custom Litmos application in Azure AD, so that these users and group entities are provisioned into Litmos.

Always be sure to review all the details of how the Azure AD provisioning service works before starting the first provisioning cycle. Once the first provisioning cycle has been initiated, be sure to regularly check the provisioning cycle logs for any failures you may want to investigate.