Authenticating users using Entra ID (formerly Azure AD)¶

Lime CRM can be configured to authenticate users using Entra ID. Note that this feature only considers Authentication, i.e. logging on to Lime CRM. Not Authorization, i.e. what you may see/change in Lime CRM nor synchronization of users and groups between Entra ID and Lime CRM.

Requirements¶

The following is required for the Entra ID integration:

Lime CRM Server 2020.2 or later (for on-premises installations)
Users must exist in both Lime CRM and in Entra ID
For configurations where externalId is not mapped to objectId (Microsoft Entra ID Attribute Mappings), users who wish to log on using Entra ID must have their username set to their email address from Entra ID
For Lime employees (e.g. Support or Consultants) to be able to login to Lime CRM they must be given a user in the AD or be invited as a guest user

Warning

The Entra ID integration is not compatible with the old Lime CRM/Active Directory integration ("LADI AD Sync").

Warning

If the customer have been using the old AD integration with SSO, the desktop client will NOT show you the Entra ID login prompt. You need to remove the SPN record OR create a registry entry per client computer, see Troubleshooting.

How It Works¶

When Entra ID login is enabled the user is redirected to Microsoft instead of the normal login screen when accessing Lime CRM. Microsoft's service verifies that the account exists in the Entra ID application and that the credentials are correct.

If the login is successful, Microsoft redirects the user back to Lime CRM using a "Redirect URI" and the user's email address as a key. If that email exists in the user table in Lime CRM a session is created. This means the user's email address must also be their username in Lime CRM.

Users are either manually created in Lime using LISA or imported using Microsoft Entra ID User Provisioning.

Configuration Steps¶

Steps 1-2 are performed by the customer's Entra ID admin. Step 3 is performed by a Lime consultant.

Create Enterprise Application
Assign Entra ID users to the Enterprise Application
Configure Lime CRM to use Entra ID

Step 1: Create Enterprise Application¶

Before starting this guide, please make sure you have received a Redirect URI from Lime. It typically follows the format https://[lime-server].[your-domain].com/client/oauth2/authorize for on-premise and https://[yourcompany].lime-crm.com/client/oauth2/authorize in cloud.

Go to the Azure Portal at https://portal.azure.com
Click the search bar, search for Enterprise applications and click it
Click New application and then choose to Create your own application
Fill in a name such as "Lime CRM AD" and choose "Integrate any other application you don't find in the gallery (Non-gallery)"
Click Create
Click the search bar, search for "App Registrations" and click it.
Find your application in the list and click to open it
Write down the
- application_id ("Application (client) ID") and
- tenant ("Directory (tenant) ID")
Add a client secret in "Client credentials"
Give it a suiting name, for instance "Lime CRM", and set an expiry date. Suggested: 24 months.
Write down what is the "Value" column in the secrets list. NB! Not the value in the "Secret ID" column.
Add a redirect URI in "Redirect URIs"
Click Add a platform
Select Web
Fill in the Redirect URI given to you by Lime
Click Configure at the bottom
Click "API permissions" in the left menu to start adding required permissions
Click "Add a permission" and choose "Microsoft Graph" followed by "Delegated permissions"
Search for User.Read and select it
Click Add permissions at the bottom of the page
Click "Grant admin consent for <domain>" in the toolbar

By now, you should have written down the following:

Application (client) ID
Tenant (tenant) ID
Secret
Expiry date for the secret

Please contact your contact person at Lime to let them know you are done and they will arrange a secure way for you to send them this information.

Step 2: Assign Entra ID users to the Enterprise Application¶

Click the search bar, search for Enterprise applications and click it
Find your application in the list and click to open it
Click Users and groups in the left menu to start adding users

Users added in this way must also be added to Lime CRM through LISA before they can access Lime CRM.

Step 3: Configure Lime CRM to use Entra ID (performed by Lime consultant)¶

Info

For Lime CRM releases prior to "Hoverla" 2022.2.739 (2.308.3) the setup steps were different. Follow the older documentation for configuration of Lime CRM.

Before starting this guide, please make sure you have received Application (client) ID, Directory (tenant) ID and Secret from the customer.

Cloud setup¶

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

Configuration:

authentication:
  provider: azure
  azure:
    application_id: <YOUR CLIENT ID>
    tenant: <YOUR TENANT ID>

Secret:

authentication:
  azure:
    client_secret: <YOUR SECRET>

On-prem setup¶

Create or open config.yml (or config.yaml if config.yml doesn't exist), which is found in %programdata%\Lundalogik\LIME Pro Server\{service name}\configs for the webserver, eventhandler and taskhandler.
Update the files with the following:

features:
  application_configuration: true

Create or 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:
    authentication:
      provider: azure
      azure:
        application_id: <YOUR CLIENT ID>
        tenant: <YOUR TENANT ID>

  secrets:
    authentication:
      azure:
        client_secret: <YOUR SECRET>

Create Guest User¶

Lime employees (e.g. Support or Consultants) need to access the Lime CRM application to be able to give support and help out with solution development. To give Lime employees access, guest users should be created.

Go to the Azure Portal at https://portal.azure.com
Click the search bar, search for Users and click it
Click New guest user
Choose Invite user (for external email-domain)
Fill in the form with the correct details
Add the user to the group with access to Lime CRM
Click Invite at the bottom of the page

If Entra ID user provisioning is enabled it can take up to 40 minutes for the user to be created in Lime CRM. Once created, add it to the administrators group using LISA.

If Entra ID user provisioning is not enabled the user must also be created manually in Lime CRM using LISA, make sure to enter the same email adress as both username and email, then adding the user to the appropriate groups.

Troubleshooting¶

Doesn't work for any users¶

If the login process doesn't work for any users, follow these steps:

Check that Entra ID login is enabled in the application config
Attempt to login using the Web Client
- Error: AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the application: The Redirect URI is not correct. Check that it follows the format https://[lime-server].[your-domain].com/client/oauth2/authorize and that you are using https://[lime-server].[your-domain].com/client/ to access Lime CRM.
- Error: Selected user account does not exist in tenant '[XYZ]' and cannot access the application '[ABC]' The username is not assigned to the application on the Entra ID side.
- Error: AADSTS700016: Application with identifier '[ABC]' was not found in the directory '[XYZ]' This can be due to:
  - The client ID is incorrect.
  - The tenant ID is incorrect.
- Sign in failed. Unable to authenticate through Microsoft Entra ID Identity. Please ask your administrator for help. The secret in Lime CRM is incorrect or in the wrong place.
In LISA
- Check that the user exists
- Check that the user's username matches the email used to login
- Check that the user belongs to a group that has access to Lime CRM, for example "Users"
In Azure
- Check that the user exists
- Check that the user has been added to the Enterprise Application
- Check that the user's username is the same as the username in LISA
- Check that the user's email (under contact info) is the same as the username in LISA
In Azure, check that consent has been given.
Check for configuration issues (on-premise)
- For on-premises make sure that there is only one application_config.yaml in the programdata/lundalogik/lime pro server and all the sub directories.
- The application name in the yaml file should be the same as the real lime application. Spaces are allowed.
- The secret in the configuration has a typo.
To verify these type of the issues if the application is on-premises you can do as follows:

Run python in the virtual env
```
import lime_config
lime_config.load_config("Web Server")
lime_config.get_app_config("")
```
this show all the config and secrets. To get specific configuration:
```
lime_config.get_app_config("<app_id>", "config.authentication.azure.enabled")
lime_config.get_app_config("<app_id>", "config.authentication.azure.tenant")
lime_config.get_app_config("<app_id>", "config.authentication.azure.application_id")
lime_config.get_app_config("<app_id>", "secrets.authentication.azure.client_secret")
```

Doesn't work for a particular user¶

If the login process works for some users but not all, follow these steps:

In LISA
- Check that the user exists
- Check that the user's username matches the email used to login
- Check that the user belongs to a group that has access to Lime CRM, for example "Users"
In Azure
- Check that the user exists
- Check that the user has been added to the Enterprise Application
- Check that the user's username is the same as the username in LISA
- Check that the user's email (under contact info) is the same as the username in LISA
Verify that the user reporting the problem is accessing Lime CRM using the same domain as the Redirect URI that is configured in the App Registration in Azure

If the customer have been using SSO with the old AD Integration the desktop client will not show the Entra ID login screen. Check if a SPN record exists for the URL you are trying to connect to. To see SPN records, open a CMD window and write this:
```
setspn -l <domain>\<serviceaccount>
```
<domain>\<serviceaccount> is the user account running the Lime CRM Web Server service. (e.g. "COMPANYDOMAIN\limeservice"
```
setspn -l COMPANYDOMAIN\limeservice
Registred ServicePrincipalNames for CN=limeservice,OU=ServiceAccounts,OU=Company Name,OU=Company,DC=company:
  lime\lime.company.com
```
If you get a result similar to above you need to EITHER remove the SPN record OR create a registry entry per client computer (good for troubleshooting)
- To remove the SPN globally:
  
  Remove the record by using this command with a user with Domain Administrator privileges (this will shut down the SSO function towards the old AD):
```
setspn -d lime\<hostname> <domain>\<serviceaccount>
```
  In this example hostname is lime.company.com
- Disable SSO per client: Add a record with the name "SSPILogin" as a DWORD with value 0 on this path in regedit: Computer\HKEY_CURRENT_USER\SOFTWARE\Lundalogik\Lime\Login\lime.company.com

In the rare circumstance the Entra ID integration is enabled for all users but there still is a need to temporarily login with a user that isn't a member of the Entra ID tenant it is possible to do so. The administrator could then login into the system entering the username and password stored in Lime CRM.

Info

This method is only available for the web client.

Warning

Using this feature will remove the extra security that the Entra ID integration can provide. This feature must be set to False as soon as it is not required.

Follow these steps to use this feature.

Make sure the forced_username_password setting exists in the application configuration and that it is set to True

authentication:
  provider: azure
  azure:
    application_id: <YOUR CLIENT ID>
    tenant: <YOUR TENANT ID>
    forced_username_password: true

Add the argument forced_username_password=True to the URL. If the application URL is example.lime-crm.com, the URL for bypassing the Entra ID login will be example.lime-crm.com/client/login/?database={application-name}&forced_username_password=True
At this point you cannot login using an Entra ID account, instead you should enter the username and password of a Lime user.

Trouble logging in with Lime user login?

Please note:

Only users of the type Administration can use this feature. The admin user in a Lime database is not of this type.
User created by Microsoft Entra ID User Provisioning cannot use this feature (generally the scim users cannot use username/password to login)

User authentication based on token claims¶

In the context of Open ID Providers, like Microsoft Entra ID, tokens are used to securely transmit information about the authenticated user and the authentication process itself. These tokens typically contain a set of claims, which are statements about the user or the token itself.

In LimeCRM, we use token claims to authenticate users during the initial login. This allows us to ensure that the user is who they claim to be and has the appropriate permissions for the requested operation.

How it works¶

When a user logs in, the authentication service issues a token that contains the user's claims. The selected claim is then used to authenticate the user in LimeCRM.

Warning

Before LimeCRM v2.831.0 the default and only claim used for authentication was the email claim. Using it means that the user's LimeCRM username has to be set to Microsoft Entra ID user email address, which is not required when using oid claim. Additionally, for the security reasons mutable claims like for example: email, preferred_username, unique_name should not be used to identify user in the system.

How to use object id (`oid`) instead of mutable claims?¶

Microsoft Entra ID¶

Change Schema 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
Go to Provisioning/Provisioning (left menu)
Under Mappings, open Provision Microsoft Entra ID Users
Find externalId in customappsso Attribute column and click Edit
Set the Source attribute value to objectId
Set the Match attribute using this attribute value to Yes
Set the Matching precedence value to 2
Click Ok
Find userName in customappsso Attribute column and click Edit
Set the Match attribute using this attribute value to No
Click Ok
Find externalId in customappsso Attribute column and click Edit
Set the Matching precedence value to 1
Click Ok
Click Save

Update Users data¶

Go to Provisioning
Click Restart provisioning. The provisioning will be automatically scheduled and run for all users and groups. By default, it synchronizes data every 40 minutes.

After provisioning is done, no further steps are needed. Users identification will be made based on external_id. Now, it's possible to change the username in LimeAdmin without affecting the user's ability to log in.

Warning

After changes in Schema Mappings are made DO NOT change the users username in LimeAdmin. Just restart provisioning. If the user username will be modified in LimeCRM before provisioning, user will be duplicated in the system.

Warning

The default value assign to LimeCRM User external_id is oid which refers to EntraID objectId. It is possible to use other EntraID attribute as external_id by declaring it in application configuration, but it is not recommended.

How to use other token claims for authentication?¶

Warning

By selecting a claim other than email or oid you need to be aware that the claim should be unique for each user. Changing claim to use is possible but not recommended.

In both cases:

authenticate user by username and
authenticate user by external_id it is possible to use other claims than email and oid respectively. To do so, you need to declare the claim in the application configuration. If the claim is not a standard claim, it needs to be added as an optional claim in Azure Portal.

Example authenticate user by username using name claim:

<solution-name>:
  config:
    authentication:
      provider: azure
      azure:
        enabled: true
        tenant: <tenant_id>
        application_id: <application_id>
        claims:
          username: name

Example authenticate user by external_id using preferred_username claim:

<solution-name>:
  config:
    authentication:
      provider: azure
      azure:
        enabled: true
        tenant: <tenant_id>
        application_id: <application_id>
        claims:
          external_id: 'preferred_username'

ID Token - Standard Claims¶

According to the OpenID Connect Core 1.0 specification, the following claims are standard:

iss (Issuer)
sub (Subject)
aud (Audience)
exp (Expiration Time)
iat (Issued At)
auth_time (Authentication Time)
nonce (Nonce)

all other ones like for example upn or verified_primary_email are optional and if needed should be added to the token in the Azure Portal. The only exception is the email claim which is added by default by us.

How to add optional claims in Azure Portal?¶

Go to the Azure Portal at https://portal.azure.com
Click the search bar, search for "App registration" and click it
Find your application in the list and click to open it
Go to Manage/Token configuration (left menu)
Open Add optional claim
Select ID
Select claims you want to add
Click Add

Now the selected claims will be added to the token and can be used for authentication in LimeCRM.

FAQ¶

Is it possible to log in with both Microsoft Entra ID and form at the same time?¶

When using Entra ID Login all user logins must be done using Azure.

Does group access rules in Entra ID translate to access in Lime?¶

All permissions are managed in Lime.

Can I change the username in LimeAdmin after switching to externalId authentication?¶

Yes. After changing from email to external_id, you can change the username in LimeAdmin. The externalId will be used for authentication now. Changing the username will not affect authentication.

What happen if the Microsoft Entra ID Schema externalId is not set?¶

If the externalId is not set, the system will try to authenticate user by username. To make it possible the claim declared for username in application configuration will be used [default email]. If both tries, authentication through external_id or username will fail, user will not be able to log in to LimeCRM.

Authenticating users using Entra ID (formerly Azure AD)¶

Requirements¶

How It Works¶

Configuration Steps¶

Step 1: Create Enterprise Application¶

Step 2: Assign Entra ID users to the Enterprise Application¶

Step 3: Configure Lime CRM to use Entra ID (performed by Lime consultant)¶

Cloud setup¶

On-prem setup¶

Create Guest User¶

Troubleshooting¶

Doesn't work for any users¶

Doesn't work for a particular user¶

Azure login screen is not visible in desktop client¶

Enabling Lime user login¶

User authentication based on token claims¶

How it works¶

How to use object id (oid) instead of mutable claims?¶

Microsoft Entra ID¶

Change Schema Mappings¶

Update Users data¶

How to use other token claims for authentication?¶

ID Token - Standard Claims¶

How to add optional claims in Azure Portal?¶

FAQ¶

Is it possible to log in with both Microsoft Entra ID and form at the same time?¶

Does group access rules in Entra ID translate to access in Lime?¶

Can I change the username in LimeAdmin after switching to externalId authentication?¶

What happen if the Microsoft Entra ID Schema externalId is not set?¶

How to use object id (`oid`) instead of mutable claims?¶