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 must exist in both Lime CRM and in Azure AD
Users who wish to log on using Azure AD must have their username set to their email address from Azure AD
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 Azure AD 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 Azure AD login prompt. You need to remove the SPN record OR create a registry entry per client computer, see Troubleshooting.

How It Works¶

When Azure AD 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 Azure AD 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 Azure AD user provisioning.

Configuration Steps¶

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

Create Azure AD Application
Assign Azure AD users to the Enterprise Application
Configure Lime CRM to use Azure AD

Step 1: Create Azure AD 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 Azure AD 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 Azure AD (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 Azure AD 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 Azure AD 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 Azure AD 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 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.
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 Azure AD 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 Azure AD 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 Azure AD 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 Azure AD 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 Azure AD login will be example.lime-crm.com/client/login/?database={application-name}&forced_username_password=True
At this point you cannot login using an Azure AD account, instead you should enter the username and password of a Lime user.

Trouble logging in with Lime user login?

Please note:

Only users member of the Administrator group can use this feature. The admin user in a Lime database is not member of Administrators per default.
User created by Azure AD user provisioning cannot use this feature (generally the scim users cannot use username/password to login)

Authenticating users using Azure AD¶

Requirements¶

How It Works¶

Configuration Steps¶

Step 1: Create Azure AD Application¶

Step 2: Assign Azure AD users to the Enterprise Application¶

Step 3: Configure Lime CRM to use Azure AD (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¶

FAQ¶

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

Does group access rules in Azure translate to access in Lime?¶

Authenticating users using Azure AD¶

Requirements¶

How It Works¶

Configuration Steps¶

Step 1: Create Azure AD Application¶

Step 2: Assign Azure AD users to the Enterprise Application¶

Step 3: Configure Lime CRM to use Azure AD (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¶

FAQ¶

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

Does group access rules in Azure translate to access in Lime?¶