Authenticating users using Azure AD¶

Lime CRM can be configured to authenticate users using Azure AD. 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 Azure AD and Lime CRM.

Requirements¶

The following is required for the Azure AD integration:

Lime CRM Server 2020.2 or later (for on-premises installations)
Users (i.e. entries in the user table) who wish to log on using Azure AD must have their username set to their Azure AD email address

In addition to this, the Azure AD integration must be configured correctly both on the Azure AD and Lime CRM sides.

Warning

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

Configuration - Azure AD side¶

Configuration of the integration on the Azure AD side consists of two steps:

Create an Enterprise Application
For that application, configure the App Registration

Creating an Enterprise Application¶

To create an Enterprise Application, you more or less need to follow this guide. Due to the changing nature of Azure, those docs will take precedence, but let's do it step by step as Azure looks today, to get everytone up to speed.

First, navigate to Enterprise Applications after logging on. Press New application.

List of applications

Select to add a Non-gallery application

Adding an Application

Name the application something descriptive

Naming the application

Then the application is created

Application created

Configuring the App Registration¶

The next step is to configure the App Registration.

Start by navigating to App registrations in Azure AD. You should see the registration for the Enterprise Application that you just created. Click the link for that item.

App registrations

On this screen, note the Tenant ID and Client ID. Then navigate to Certificates and Secrets.

Our app registration

On the Certificates and Secrets page, we want to create a new Client Secret, which is a shared secret between Azure and Lime CRM, which is one of the components that makes Lime CRM trust that a login request originates from Azure AD, not from anywhere else. Press New client secret.

Clients and secrets

Give the secret a name and select how long the secret should live. Then press Add.

NOTE: take note of the expiry time of the secret! When this secret times out, users won't be able to log on to Lime CRM!

New client secret

After the secret is registered, note the client secret's Value. The value will disappear the next time you see this screen, so copy it and keep it somewhere temporarily.

NOTE: This is the shared "password" that Lime CRM uses to trust Azure AD. Treat this as you treat any passwords. If the password is leaked, a hacker could use this to log on to Lime CRM.

Client secret created

The last step is to assign the registration a Redirect URI. On the Overview page, press the Add a Redirect URI link.

Add a Redirect URI

Press the Add a platform button

Add platform

Select Web platform

Web platform

Write your Redirect URI. The URI should be according to the format https://lime.yourcompany.com/client/oauth2/authorize. The domain name "lime.yourcompany.com" should be the domain name used by Lime CRM end users to access the Lime CRM installation, so insert your own domain name here. Press Configure at the bottom to save.

Configure Redirect URI

The Redirect URI is registered.

Redirect URI registered

At the end of this guide, you should have written three values down:
Application ID
Tenant ID
Client secret

All of those will be entered into the Lime CRM configuration.

Assigning Azure AD users to the Enterprise Application¶

Navigate back to the Enterprise Application you just created, and through to Users and Groups in the left panel. Assign the users that should be able to log on.

Assign users

Common Error codes¶

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.

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 Azure AD 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. - Consent for the multi tenant application hasn't been given.

Configuration - Lime CRM side¶

Configuring Lime CRM¶

If you did the above configuration, you should have three values:

Application ID
Tenant ID
Client secret

Depending on the version of Lime CRM, you will add the configuration into different configuration files. For Lime CRM "Keb", i.e. version 2020.2.371(2.76.0) we configure using the machine-level configuration file, config.yaml. For later versions, we configure using the application-level configuration file.

Configuration - 2020.2.371(2.76.0)¶

On your Lime CRM server, open up the configuration file. See the environment configuration docs for information about file location etc.

Then configure the Azure AD integration as follows:

my-app:
  config:
    authentication:
      azure:
        enabled: True
        tenant: <YOUR TENANT ID>
        application_id: <YOUR APPLICATION ID>
        client_secret: <YOUR CLIENT SECRET>

The enabled flag should be set to True and the three configuration items from the Azure AD set-up should be pasted into the respective rows.

Configuration - later versions¶

On your Lime CRM server, open (or create) the application configuration file.

You can configure the Azure AD integration for your application(s) as follows:

my-app:
  config:
    authentication:
      provider: azure
      azure:
        tenant: <YOUR TENANT ID>
        application_id: <YOUR APPLICATION ID>
        forced_username_password: false
  secrets:
    authentication:
      azure:
        client_secret: <YOUR CLIENT SECRET>

The provider flag should be set to azure and the three configuration items from the Azure AD set-up should be pasted into the respective rows. The forced_username_password is provided to optionally bypass the Azure AD login and it is explained in the Enabling Lime user login section.

Configuring the `user` table¶

Whenever a user logs on to Azure AD and is sent back to Lime CRM, Azure AD includes the user's email address in the request. Lime CRM takes that email address and does a lookup in the user table. Thus, in order to make this work, all users who wish to log on using Azure AD have to have their email address in the username column.

One way to do so is to create a user in the LISA with the same email address in Azure AD. The other way is to enable Azure AD user provisioning to import the users data from Azure AD to Lime CRM automatically.

Common Lime CRM config errors¶

Issue in the config like formatting, structures, or typo¶

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")

A user cannot log in¶

The Azure AD username is not linked to a user in Lime CRM. Double check this in LISA.
The user in the Azure AD is missing an email address. To verify this you can go to the Azure AD, find the user, click on the user name to go to the profile page and check if the email has value under the contact info section.

See the Lime User table config section

Usage¶

In a multi-application setup, the user is prompted to select an application prior to authentication:

Database selection

After selecting an application and pressing the "Sign-in" button, the user is redirected to the Microsoft login page where s/he is asked to select an account:

Account selection

Upon a successful authentication with Microsoft Azure AD, the user will be logged in to Lime CRM.

There are scenarios where we want to have the Azure AD integration enabled for all users while certain users still would be able to login into the system by entering the username and password. For example to let a maintenance user or administrator manage Lime without being members of your Azure AD tenant.

Info

This method is only available for the web client.