Skip to content

Single Sign-On 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 Cloud or Lime CRM On-prem 2020.2 or later
  • Users must exist in both Lime CRM and in Entra ID. It is recommended to use Microsoft Entra ID User Provisioning
  • 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 log in to Lime CRM they must be given a user in the Entra ID or be invited as a guest user

Warning

The Entra ID integration is not compatible with the old Lime Active Directory Integration ("LADI").

Warning

If the customer has been using LADI 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 Admin or imported using Microsoft Entra ID User Provisioning.

Configuration Steps

All steps should be carried out by the Entra Administrator, who will need admin access to Lime CRM to complete the configuration.

  1. Create a backup user (if it does not already exist)
  2. Create Enterprise Application
  3. Assign Entra ID users to the Enterprise Application
  4. Configure Lime CRM to use Entra ID

🎬 Watch: Setting up Entra Single Sign-On and User Provisioning (Vimeo)

Step 1: Create a backup user

  1. Log in to Lime CRM with admin privileges
  2. Navigate to the Administrators Page
  3. Navigate to System > Security > Users
  4. Create a user with your email address as Username
  5. Set User type to Administration
  6. Add the user to the Administrators group
  7. Navigate to the Lime CRM web client
  8. Create a coworker and connect the user to it

Step 2: Create Enterprise Application

  1. Head to the Azure Portal at https://portal.azure.com
  2. Click the search bar, search for Enterprise applications and click it
  3. Click New application and then choose to Create your own application
  4. Fill in a name such as "Lime CRM AD" and choose "Integrate any other application you don't find in the gallery (Non-gallery)"
  5. Click Create
  6. Click the search bar, search for "App registrations" and click it
  7. Find your application in the list and click to open it
  8. Copy:
    • client_id ("Application (client) ID") and
    • tenant ("Directory (tenant) ID")
  9. Open a new browser tab and log in to Lime CRM with admin privileges.
  10. Navigate to the Administrators Page.
  11. Navigate to System > Security > Authentication.
  12. Pick Entra ID as Provider.
  13. Paste (from Copy step above):
    • Application (client) ID
    • Directory (tenant) ID
  14. Navigate back to Azure Portal.
  15. Add a client secret in "Client credentials" (Manage > Certificates & secrets > Client secrets)
  16. Give it a suitable name, for instance "Lime CRM", and set an expiry date. Suggested: 24 months.
  17. Copy the value from the "Value" column in the secrets list, not the value in the "Secret ID" column.
  18. Navigate back to Lime Admin and paste the secret value as the Client Secret Value.
  19. Enter the same expiration date set above as Client Secret Expiration Date
  20. Copy the Web - Redirect URI.
  21. Navigate back to Azure Portal.
  22. Add a redirect URI in "Redirect URIs" (Manage > Authentication)
  23. Click Add a platform
  24. Select Web
  25. Paste the URI copied from Lime Admin as Redirect URI.
  26. Click Configure at the bottom.
  27. Click "API permissions" in the left menu to start adding required permissions (Manage > API permissions).
  28. Click "Add a permission" and choose "Microsoft Graph" followed by "Delegated permissions".
  29. Search for User.Read and select it.
  30. Click Add permissions at the bottom of the page.
  31. Click "Grant admin consent for <domain>" in the toolbar.
  32. Navigate back to Lime Admin and click Check configuration.
  33. If everything works, click Save.

Step 3: Setup Users and Groups

  1. In Azure Portal, click the search bar, search for Enterprise applications and click it
  2. Find your application in the list and click to open it
  3. 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 Lime Admin before they can access Lime CRM.

As stated before, it is recommended to use Microsoft Entra ID User Provisioning to add users to Lime CRM.

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.

  1. Go to the Azure Portal at https://portal.azure.com
  2. Click the search bar, search for Users and click it
  3. Click New guest user
  4. Choose Invite user (for external email-domain)
  5. Fill in the form with the correct details
  6. Add the user to the group with access to Lime CRM
  7. 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 Lime Admin.

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

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 Lime CRM, 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 Lime CRM.

Warning

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

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

Microsoft Entra ID

Change Schema Mappings
  1. Go to the Azure Portal at https://portal.azure.com
  2. Click the search bar, search for "Enterprise Applications" and click it
  3. Find your application in the list and click to open it
  4. Go to Manage > Provisioning (left menu)
  5. Under Mappings, open Provision Microsoft Entra ID Users
  6. Find externalId in customappsso Attribute column and click Edit
  7. Set the Source attribute value to objectId
  8. Set the Match attribute using this attribute value to Yes
  9. Set the Matching precedence value to 2
  10. Click Ok
  11. Find userName in customappsso Attribute column and click Edit
  12. Set the Match attribute using this attribute value to No
  13. Click Ok
  14. Find externalId in customappsso Attribute column and click Edit
  15. Set the Matching precedence value to 1
  16. Click Ok
  17. Click Save
Update Users data
  1. Go to Provisioning
  2. 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 Lime Admin without affecting the user's ability to log in.

Warning

After changes in Schema Mappings are made DO NOT change the user's username in Lime Admin. Just restart provisioning. If the user's username is modified in Lime CRM before provisioning, the user will be duplicated in the system.

Warning

The default value assigned to a Lime CRM user's external_id is the oid claim, which refers to the Entra ID objectId claim. It is possible to use other Entra ID attribute as external_id by declaring it in the 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 must be unique for each user. Changing the claim used is possible, but it is not recommended.

Authenticating users by username or external_id is possible with claims other 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": {
        "tenant": "<tenant_id>",
        "client_id": "<client_id>",
        "claims": {
          "username": "name"
        }
      }
    }
  }
}

<solution-name>:
  config:
    authentication:
      provider: azure
      azure:
        tenant: <tenant_id>
        client_id: <client_id>
        claims:
          username: name

Example: authenticate user by external_id using preferred_username claim

{
  "<solution-name>_config": {
    "authentication": {
      "provider": "azure",
      "azure": {
        "tenant": "<tenant_id>",
        "client_id": "<client_id>",
        "claims": {
          "external_id": "preferred_username"
        }
      }
    }
  }
}

<solution-name>:
  config:
    authentication:
      provider: azure
      azure:
        tenant: <tenant_id>
        client_id: <client_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 claims, for example upn and 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 Lime CRM.

How to add optional claims in Azure Portal?

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

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

Guest Users

In order to get the UPN claim in the id-token also for guest users, the optional UPN claim has to be added, and then edited to have "Externally authenticated" turned on.

Note

If you plan to map UPN to the username, make sure to use originalUserPrincipalName instead of userPrincipalName in the attribute mapping for the SCIM provisioning configuration. This ensures that the correct UPN is provided for both regular and guest users.

Configuration Structure

This section covers the raw configuration structure for Entra ID authentication in Lime CRM. Below is a complete example showing what the configuration might look like with all available options. Each configuration field and option is described in detail in the sections that follow.

{
  "<solution-name>_config": {
    "authentication": {
      "provider": "azure",
      "azure": {
        "tenant": "<tenant_id>",
        "client_id": "<client_id>",
        "client_secret_expiration_date": "2026-12-31",
        "forced_username_password": false,
        "login_prompt_behavior": "select_account",
        "token_validation_enabled": false,
        "time_to_expiration": null,
        "authority_base_url": null,
        "claims": {
          "username": "email",
          "external_id": "oid",
          "logout_hint": "login_hint"
        }
      }
    }
  },
  "<solution-name>_secrets": {
    "authentication": {
      "azure": {
        "client_secret": "<your_client_secret_value>"
      }
    }
  }
}

<solution-name>:
  config:
    authentication:
      provider: azure
      azure:
        tenant: <tenant_id>
        client_id: <client_id>
        client_secret_expiration_date: "2026-12-31"
        forced_username_password: false
        login_prompt_behavior: select_account
        token_validation_enabled: false
        time_to_expiration: null
        authority_base_url: null
        claims:
          username: email
          external_id: oid
          logout_hint: login_hint
  secrets:
    authentication:
      azure:
        client_secret: <your_client_secret_value>

Configuration Fields

Required Fields

  • tenant (string): The tenant ID (Directory ID) from your Entra ID application registration
  • client_id (string): The client ID (Application ID) from your Entra ID application registration
  • client_secret (string): The client secret value generated in Azure Portal for your application registration (stored in secrets section)

Authentication Behavior

  • login_prompt_behavior (string, default: "select_account"): Controls the login prompt behavior. See Microsoft documentation for details.
    • "default": Uses the default prompt behavior ("none"), which may silently log in the user if already authenticated
    • "login": Always asks for user credentials, negating single sign-on
    • "consent": Like "login" but also shows a permission approval screen asking "Do you allow this app to access your data?" after the user enters their credentials
    • "select_account": Lets user pick between Entra accounts already logged in, interrupting single sign-on to provide account selection experience
  • forced_username_password (boolean, default: false): Allows bypassing Entra ID login with Lime username/password. Warning!: Only use temporarily for troubleshooting

Token Configuration

  • token_validation_enabled (boolean, default: false): Whether to validate ID tokens from Entra ID
  • time_to_expiration (integer, optional): Custom token expiration time in seconds. If null, uses Entra ID default
  • authority_base_url (string, optional): Custom authority base URL

Client Secret Management

  • client_secret_expiration_date (date, optional): When the client secret expires (format: "YYYY-MM-DD"). Used for monitoring and alerts

Claims Configuration

The claims section maps Entra ID token claims to Lime CRM user identification:

  • username (string/boolean, default: "email"): Token claim used for username mapping, false disables the username claim mapping
  • external_id (string, default: "oid"): Token claim used for external ID mapping
  • logout_hint (string, default: "login_hint"): Token claim used for logout hint

Security Recommendation

Use "oid" (object ID) for the external_id claim instead of mutable claims like "email" or "preferred_username" for better security and reliability.

ADFS Configuration

When authenticating against ADFS, set tenant: "adfs" and provide a valid authority_base_url pointing to your ADFS server. The authority_base_url field is required for ADFS authentication.

Troubleshooting

Doesn't work for any users

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

  1. Check that Entra ID login is enabled in the application config
  2. Attempt to log in 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
  3. In Lime Admin
    • Check that the user exists
    • Check that the user's username matches the email used to log in
    • Check that the user belongs to a group that has access to Lime CRM, for example "Users"
  4. 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 Lime Admin
    • Check that the user's email (under contact info) is the same as the username in Lime Admin
  5. In Azure, check that consent has been given

  6. Check for configuration issues (on-premise)

    • Make sure that there is only one application_config.yaml in %programdata%\Lundalogik\LIME Pro Server\ and all subdirectories
    • 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 types of issues if the application is on-premise 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 shows all the config and secrets. To get specific configuration:

    lime_config.get_app_config("<app_id>", "config.authentication.azure.tenant")
lime_config.get_app_config("<app_id>", "config.authentication.azure.client_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:

  1. In Lime Admin
    • Check that the user exists
    • Check that the user's username matches the email used to log in
    • Check that the user belongs to a group that has access to Lime CRM, for example "Users"
  2. 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 Lime Admin
    • Check that the user's email (under contact info) is the same as the username in Lime Admin
  3. 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

Azure login screen is not visible in desktop client

If the customer has been using SSO with LADI 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
Registered 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

Enabling Lime user login

In the rare circumstance the Entra ID integration is enabled for all users but there still is a need to temporarily log in with a user that isn't a member of the Entra ID tenant it is possible to do so. The administrator could then log in to 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

    {
  "<solution-name>_config": {
    "authentication": {
      "provider": "azure",
      "azure": {
        "tenant": "<tenant_id>",
        "client_id": "<client_id>",
        "forced_username_password": true
      }
    }
  }
}

    <solution-name>:
  config:
    authentication:
      provider: azure
      azure:
        tenant: <tenant_id>
        client_id: <client_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 log in 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 built-in admin user in a Lime database does not have the Administration type, so it cannot use this feature
  • Users created by Microsoft Entra ID User Provisioning cannot use this feature (generally the scim users cannot use username/password to login)

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 Lime Admin after switching to externalId authentication?

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

What happens 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 Lime CRM.