Provisioning users and groups in Azure AD¶

The user/group provisioning service enables the synchronization of users and groups between Azure AD and Lime CRM. This service implements the SCIM standard (System for Cross-domain Identity Management), which uses a RESTful API to automatically provision/de-provision users and groups that exist in Azure AD.

Warning

To be able to use the provisioning service, Azure AD login for Lime CRM must be enabled and configured!
Please refer to this guide on how to set up Azure AD login.
Note that it is not possible to us both Ladi and SCIM for synchronizing user data.

How it works¶

SCIM provisioning is a one-directional synchronization of users and/or groups from Azure AD to Lime CRM.

Users are provisioned by their user principal name attribute, which must contain the user's email address (please change it manually if that is not the case).
Groups are provisioned by their group name. If a group with the same name exists in both Azure AD and Lime CRM, group memberships will be synchronized after provisioning.
A coworker is created for each user.
Removing a user or group from your application in Azure does not delete your user from the Lime CRM database after the synchronization. Instead, the user/group will be deactivated (aka "soft delete").
Created groups can not be nested in LISA, SCIM provisioning only support a flat group structure.

The provisioning employs a three-way attribute mapping:

Azure AD attributes -> SCIM attributes -> Lime CRM labels

The Azure AD to SCIM mappings are edited in the Azure portal.
The SCIM to Lime CRM mapping is done using labels in LISA.

The default mapping is shown below.

Attribute Mapping¶

SCIM Attribute	Column on [user] table	Lime CRM field label on [coworker] table
userName	`username`
displayName	`fullname`	Name
name.familyName		Last Name
name.givenName		First Name
emails[type eq "work"].value		Email
emails[type eq "home"].value		Email 2
active		Inactive
title		Job Title
externalId	`external_id`
phoneNumbers[type eq "work"].value		Business Telephone Number
phoneNumbers[type eq "mobile"].value		Mobile Telehphone Number
phoneNumbers[type eq "home"].value		Home Telephone Number
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager		Responsible Co-worker

Configuration Steps¶

Steps 1-3 and 6 are performed by a Lime consultant. Steps 4-5 are performed by the customer's Azure AD admin.

Apply labels to coworker lime type
Generate Secret Token
Change settings for Lime CRM
Setup Provisioning
Edit Attribute Mappings
Add Permissions for Provisioned Groups

Step 1. Apply labels to coworker lime type (performed by Lime consultant)¶

In LISA,

Make sure the coworker lime type has as the User label
Make sure all mandatory fields on the coworker lime type either has default values or have labels among those in the Attribute Mapping above

Step 2: Generate Secret Token (performed by Lime consultant)¶

The provisioning will use a token that is shared between Azure SCIM and Lime CRM. While it can be anything we recommend generating one us like this:

python -c "import secrets; print(secrets.token_hex(64))"

Step 3: Change settings for Lime CRM (performed by Lime consultant)¶

Warning

Previous versions of Lime CRM incorrectly exposed the user and group resources as records Ids from the database. This could cause the provisioning process to fail as a user and group could have the same id. To fix this issue a new optional flag use_legacy_resource_ids was added to the application config. To be backwards compatible with existing deployments with active SCIM provisioning this flag is true by default. For all new setups this flag should be set to false to use the new resource ids.

Cloud setup¶

Open the CAFE page for your application
Go to the Configuration tab
Add the following to Configuration and Secret:

Configuration:

scim:
  enabled: true
  use_legacy_resource_ids: false

Secret:

scim:
  token: <YOUR SECRET TOKEN>

On-prem setup¶

open %programdata%\Lundalogik\LIME Pro Server\application_config.yaml
Update the application_config.yaml file with the parts in section config and secrets:

<application-name>:
  config:
    scim:
      enabled: true
      use_legacy_resource_ids: false

  secrets:
    scim:
      token: <YOUR SECRET TOKEN>

Step 4: Setup Provisioning¶

Before starting this guide, please make sure you have received a secret token and Tenant URL from Lime. The Tenant URL follows the format https://{root_url}/{application_name}/api/v1/scim/.

Go to the Azure Portal at https://portal.azure.com
Click the search bar, search for "Enterprise Applications" and click it
Find your application in the list and click to open it
Click "Provisioning" in the left menu
Click on the "Get started" button and choose "Automatic provisioning mode"
In the Admin Credentials section
- Enter the Tenant URL (https://{root_url}/{application_name}/api/v1/scim/).
- In the Secret Token field, fill in the 128 length char string Lime gave you.
- Test the connection and if successful, save the provisioning
Now you can start the provisioning process, which by default synchronizes the data every 40 minutes. You can also use "Provision on demand" to test the synchronization, but be aware that it only syncs users and not groups.

Step 5. Edit Attribute Mappings¶

Go to the Azure Portal at https://portal.azure.com
Click the search bar, search for "Enterprise Applications" and click it
Find your application in the list and click to open it
Click "Provisioning" in the left menu
Under "Manage provisioning" click "Edit attribute mappings"
Expand "Mappings" and select "Provision Azure Active Directory Users"
Add, edit and remove the mapping from Active Directory to customappso. Lime CRM only supports the SCIM attributes mentioned in the Attribute Mapping above. Make sure that both username and emails[type eq "work"].value are mapped from attributes that contain the same email address.

Step 6. Add Permissions for Provisioned Groups (performed by Lime consultant)¶

Check if the provisioning has created any new user groups in LISA
Give permissions to those groups by updating the table and field policies in LISA

It is NOT possible to just add these new groups as subgroups to the preexisting Users group.

Troubleshooting¶

The test connection in the provisioning does not work¶

Check the scim config in the lime application config is enabled
The token from application config should be the same as what is entered in the provisioning test connection
Double check the url in the provisioning test connection
The length of the token should be 128 chars long

Warning

Only one Azure application can be mapped to one Lime application for provisioning. Using One application on the Azure side to provision users and groups into two Lime applications leads to overwriting data in the Lime users and groups. This happen as each Azure application keep a history of Lime users and groups data so that it can use them in future syncs.

Match between Azure Active Directory and Lime CRM fails¶

When receiving an EntrySynchronizationError error with ErrorCode DuplicateTargetEntries and a message reporting that a resource has already been matched with another entry, the solution is to:

Add the use_legacy_resource_ids: false to the application config under the scim section, like in Configuration
Reset Azure provisioning in the Azure portal

Azure Provisioning FAQ¶

Does the user provisioning work as expected if the username i.e. email address in either system uses capital letters?¶

No. It is important that email addresses in both Lime CRM and Azure AD are configured with lower case letters. [email protected] will likely cause issues while [email protected] works fine.

How is the user mapped to the AD logon if they change to SSO will they still have the same account and not get a new account in lime?¶

The sync process only synchronizes the users from AD to the lime database. So no new user is created but the user information transfers to the database and provisioning process is responsible for keeping them updated.

How are the groups matched/created in lime? Will it be the same, so the groups won't lose their member in lime?¶

The groups are synced based on the group’s name. Each group can have different members in the AD side. By the time of provisioning the deleted members are removed from lime database and the assigned members would be added.

If we change a user’s group, will it be moved in the lime system also or do, we need to do a manual move in lime?¶

Every changes in the azure side will be reflected in the lime database. Thus, any manual changes after activing the provisioning should be avoided.

Why can't I see the users in LISA when the provisioning is done?¶

Close down LISA and open it again.