====== Active Directory integration ======
<WRAP round important 60%>
Active Directory is set for end of life 2024-12-31 in favour of [[https://platform.docs.lime-crm.com/en/latest/configuration/azure-login/|Entra ID]] and [[https://platform.docs.lime-crm.com/en/latest/configuration/openid-login/|OpenID Connect]].
</WRAP>

Lime Active Directory Integration (LADI) is a component available in Lime CRM 10.9 and later versions. It has three main functions:

  * It provides **single sign on** (SSO) functionality. The Lime CRM user doesn't have to enter username and password when logging in. Instead the server looks up the user's current Windows login and uses that information to authenticate with the Lime CRM Server.
  * It automatically gives users in Active Directory **access to Lime CRM**. Group memberships are also synchronized according to current configuration.
  * It **synchronizes information** about the user stored in Active Directory with specific tables in the database, most importantly the [coworker] table.

<WRAP round info 60%>
**NOTE!**

Single sign on is currently only available when using Lime CRM Desktop Client.
</WRAP>

LADI is a one-way integration. It only reads from and never writes any information to Active Directory and there is no direct communication between Lime CRM Server and Active Directory.

===== How it works =====
When the Lime CRM client first contacts the Lime CRM Server, the user's security identifier is extracted from the session and Lime CRM Servers contacts LADI, which in turn makes a few LDAP calls to appropriate Active Directory server to retrieve information about the specific user such as name, email, phone, group membership and so on. This information is returned in XML format to the Lime CRM Server and then forwarded to SQL Server where it merges with existing information about the user. After that the user is authenticated to make sure he or she has access to Lime CRM.

{{:configuration:ladi_overview.png?nolink}}

It is also possible to synchronize all users at the same time from LISA. All users from specified groups will be synchronized. New users will be added and existing users will be updated if changes have been made. By default this is triggered manually, but it is easy to set it up as an automatic synchronization.

===== Login =====
There are two ways of logging into Lime CRM: Windows login and Lime CRM login. It is possible to disable one of these login types in LISA. E.g. by disabling Lime CRM Login on the database level no one can login to the database that way. This behavior is however overridable on a per user level. The following settings are available for Login Type on the user level.

^ Login Type ^ Description ^
| Database default | The login types allowed for this user is according to the database setting. |
| Windows and Lime CRM Authentication | The user can login using both Windows and Lime CRM authentication. The database setting is ignored. |
| Windows Authentication | The user can login only using Windows authentication. The database setting is ignored. |
| Lime CRM Authentication | The user can login only using Lime CRM authentication. The database setting is ignored. |

==== Windows login ====
There are two ways of logging in using Windows authentication:

  * Without specifying username or password. Lime CRM will then use the Windows account for the current user.
  * The user specifies his or her Windows username and password. The format for the username is domain\user, e.g. lundalogik\js.

When authenticating with an Active Directory account, the user //must// be a member of a group that has the property Synchronize set to Yes. Otherwise Lime CRM will thinks it's a deleted account and mark it as inactive. Please note that LADI will never remove any users from the Lime CRM database. It will only mark them as inactive.

Authenticating with local Windows accounts is allowed, but no synchronizations will be made.

If the second type of logins will be frequently used, it is recommended to enable encryption for DCOM. DCOM is a binary protocol and by default traffic is unencrypted. Encryption is enabled in Component Services by selecting Properties on the Lundalogik Data Components application. On the Security tab, select Packet Privacy in the Authentication Level for Calls box. Encryption will then be enabled after the Lundalogik Data Components application is restarted.

==== Lime CRM login ====
This type of login uses the username and password that is specifically stored in the Lime CRM database. No synchronizations will be made when this type of login is used.

===== Synchronization =====
Synchronization from Active Directory to Lime CRM occurs when:

  * A user logs into Lime CRM using Windows authentication. Only the specified user will be synchronized. This behavior can be disabled for a database in the registry by creating a DWORD value named ''SynchronizeLoginUser'' under ''HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Lundalogik\Lundalogik Data Components\Databases\<<databasename>>'' and setting it to 0.

  * An administrator triggers the Active Directory synchronization in Lime CRM Server Administration. All users will be synchronized.

Synchronization can also be scripted and scheduled in different ways. The following code show how to synchronize all users using JavaScript.

<code javascript>
try {
  var server = "LimeServerName";
 
  var ldcSession = new ActiveXObject("LDC.Session", server);
  var sid = ldcSession.Login("admin", "password", "LimeDatabase", "", true, "");
 
  var ldcDatabase = new ActiveXObject("LDC.Database", server);
  ldcDatabase.SessionIdentifier = sid;
  ldcDatabase.SynchronizeADUsers(true);
 
  ldcSession.Logout("");
}
catch(err) {
  WScript.echo("Exception: " + err.name + ", " + err.message);
}
</code> 

Local Windows users will however never be synchronized, and synchronization will never occur for clients running Lime CRM offline (Lime CRM Server 10.11 and earlier).

If you would like Windows Task Scheduler to run your above script you can create a .bat file that contains this:

<code>
cscript //Nologo //E:jscript RunLADI.js
</code>

RunLADI.js is the name of the .js-file with the sync code. One important thing is that you set the correct folder where the program starts in  ('Start in' in Edit Action). Need to be the same as the scripts are located. 

=== Groups ===
In order to use the Lundalogik Active Directory Integration (LADI) a Windows group must be mapped to a Lime CRM group with Auto-create activated. LADI will make sure that a user that is member of this Windows group is created or up-to-date on login or when the synchronization feature is used. This is the Windows group that is used to give users access to Lime CRM. Note that it is possible to create multiple mappings like this.

It is also possible to map a Windows group to the database itself. In this case LADI will make sure that a user that is a member of this Windows group is created or up-to-date when the synchronization feature is used. Membership of this group does not grant a user access to Lime CRM.

==== Users ====
>Jane is a member of the Windows groups Sales and Stockholm and she is supposed to have access to Lime CRM and be available as a coworker.

>John is also a member of the Windows groups Sales and Stockholm but he isn't supposed to have access to Lime CRM or to be available as a coworker.

>Jim is a member of the Windows groups Employees, Sales and Stockholm he should not have access Lime CRM but he should be available as a coworker.

>Lime CRM is installed and the Lime CRM groups Sales and Stockholm are created and mapped to their corresponding Windows groups. A Windows group called Lime CRM Users is created and is mapped to the Lime CRM group Users with Auto-create activated and the Windows group Employees is mapped to the database. Jane is then added to the Windows group Lime CRM users while John and Jim are not. After synchronizing only Jane will have access to Lime CRM but both Jane and Jim will be available as coworkers. John will not appear at all in Lime CRM.

The user doesn't however have to be a direct member of the group. If the user is a member of the group Sweden and Sweden is a member of the group Lime CRM users which has Auto-create users set to true it will work just fine.

When a user is removed from the Windows group Lime CRM users the corresponding Lime CRM user will no longer have permission to access Lime CRM through Windows login. However, the user is not set as inactive in Lime so this must be handled manually, both setting the coworker card inactive as well as the user in LISA.

=== User information ===
In Active Directory all users are identified by a Security Identifier (SID). The SID is used in the Lime CRM database to map Lime CRM users and group to Active Directory users and groups.

The following rules apply when a user is synchronized.

  * If neither the username nor the SID exists in the database a new user will be added.
  * If the username exists in the database but the SID doesn't the SID will be added to the specific user.
  * If the username doesn't exist but the SID does the username will be changed for the specific user.
  * If the SID is already mapped to a different username, it will be remapped to the user with the specific username.

The user's full name will also be updated if it has changed.

=== Group membership ===
The user will be a member of the same groups in Lime CRM if these are connected to the Active Directory groups. However the group hierarchy will not be inherited. Instead the user will be a direct member of all the groups. For example:

If John Smith is a member of the group Stockholm and Stockholm is a member of the group Sweden, John Smith will be member of both groups in Lime CRM.

==== Groups ====
In Lime CRM groups will never be synchronized from Active Directory. They can be mapped to groups but group names etc will remain the same in Lime CRM even if they are changed in Active Directory.

==== Coworkers ====
The synchronization of coworkers between Active Directory and Lime CRM is a one-way synchronization. No information is ever added, deleted or changed in Active Directory.

The field mapping is done with the property Active Directory Label. This property is available in text fields, formatted text fields, link fields and option fields. The following table lists all the available labels.

^ Value ^ Name ^ LDAP Name ^ Comment ^
|0   |None   |none   |Default. This field will not be synchronized with Active Directory.    |
|1   |Object GUID   |objectGUID   |The unique identifier for the user, e.g. "S-31-273883853792579-1459739776-1418611189".    |
|2   |Distinguished name   |distinguishedName   |The path to the user in Active Directory, e.g. "CN=John Smith,OU=Coworker,DC=Lundalogik,DC=se"    |
|3   |SID   |objectSID   |The security identifier for the user, e.g. ""-1-5-21-583907252-343818398-1801674531-1117".    |
|4   |User logon name   |userPrincipalName   |The user's full logon name, e.g. "js@lundalogik.se".    |
|5   |Logon Name (Pre-Windows 2000)   |sAMAccountName   |The short version of the logon name, e.g. "js".    |
|6   |First name   |givenName   |The user's first name, e.g. "John".    |
|7   |Initials   |initials   |The user's initials, e.g. "JS".    |
|8   |Last name   |sn   |The user's last name, e.g. "Smith".    |
|9   |Full name   |cn   |The user's full name, e.g. "John Smith".    |
|10   |Name   |name   |Usually the same as Full Name.    |
|11   |Display name   |displayName   |An alternate full name to show, e.g. "John K. Smith".    |
|12   |Description   |description   |A description for the user.    |
|13   |Office   |physicalDeliveryOfficeName   |The name of the office that the user belongs to.    |
|14   |Telephone number   |telephoneNumber   |The user's telephone number.    |
|15   |E-mail   |mail   |The user's email address, e.g. "john.smith@lundalogik.se".    |
|16   |Web page   |wWWHomePage   |The user's home page, e.g. "http://www.lundalogik.se/hej".    |
|17   |Street   |streetAddress   |The street address of the user.    |
|18   |P.O. Box   |postOfficeBox   |The P.O. box for the user if any.    |
|19   |City/Location   |l   |The city the user resides in.    |
|20   |State/Province   |st   |The state/province the user resides in.    |
|21   |Postal Code   |postalCode   |The postal code for the area the user resides in.    |
|22   |Country/Region   |co   |The country the user resides in.    |
|23   |Telephone - Home   |homePhone   |The user's home phone number.    |
|24   |Telephone - Pager   |pager   |The user's pager number.    |
|25   |Telephone - Mobile   |mobile   |The user's mobile phone number.    |
|26   |Telephone - Fax   |facsimileTelephoneNumber   |The user's fax number.    |
|27   |Telephone - IP Phone   |ipphone   |The user's ip phone number.    |
|28   |Notes   |notes   |Various notes.    |
|29   |Title   |title   |The title of title, e.g. "Salesman".    |
|30   |Department   |department   |The department where the user works, e.g. "Sales".    |
|31   |Company   |company   |The company the user works at, e.g. "Lundalogik".    |

The key when synchronizing a coworker is always the user field. The integration does not try to match the the information from Active Directory with for example the user's full name. If a coworker already exists without a corresponding user, a new coworker will be added if the user is synchronized.

It is however possible to modify the changes that will be made during synchronization. More about this in Modifying synchronized values.

====  Minimum permissions ==== 

Make sure the LDC user have permission to fetch the AD attributes that are needed. 
These attributes are always fetched:

  * cn
  * displayName
  * distinguishedName
  * name
  * objectSid
  * sAMAccountName
  * memberOf

These extra attributes are default in the Lime Basic database version 5:

  * givenName
  * sn
  * telephoneNumber
  * mail
  * mobile

To get the extra attributes of your database, run exec lsp_adgetattribute in SQL Management Studio. 


===== Configuration =====
The configuration of LADI is made in LISA. In some cases it might also be necessary to make som changes to the registry. The basic configuration for the Lundalogik Active Directory Integration is all about mapping a few groups.

The recommended Lime CRM configuration is to have a specific group in Active Directory which contains all the Lime CRM users. Locate this account for the Users group in the Group Properties dialog in LISA and set Synchronize to Yes. This means that all the members of this Active Directory will have access to Lime CRM.

If more groups will be used for access control and other tasks, just create the corresponding groups in LISA and map them to that group account. This could be group accounts like Administrators, Super Users, Sweden, Germany, Sales, Marketing and so on.

==== Modifying synchronized values ====
It is possible to modify the changes that will be made to coworker by creating a stored procedure called csp_adsynchronizecoworker. This procedure will be called right before each coworker is about to be updated and all the fields are available in a temporary table called #adfield. This table has the following structure.

^ Column name ^ Data type ^ Description ^
|table   |sysname   |The name of the table (if any) where the synchronized field exists.    |
|idfield   |int   |Idfield for the synchronized field.    |
|field   |sysname   |The name of the synchronized field.    |
|fieldtype   |int   |The fieldtype for the synchronized field.    |
|idcategory   |int   |Idcategory for the synchronized field. Always exists for option fields.    |
|defaultvalue   |nvarchar(128)   |The default value for the synchronized field.    |
|length   |int   |The length of the synchronized field.    |
|adlabel   |nvarchar(128)   |The label for the synchronized field. The LDAP name is used for this column.    |
|value   |nvarchar(max)   |The current value.    |
|advalue   |nvarchar(max)   |The value from Active Directory.    |
|newvalue   |nvarchar(max)   |The new value that will be written to the field.    |

Only the synchronized fields in the database will be available in #adfield. If the labels First name (givenName), Last name (sn) and Full name (cn) are set in a database, the following procedure will change places for the first and last name in the full name for the user. E.g. "Joe Smith" will be "Smith, Joe".

<code tsql>
CREATE PROCEDURE csp_adsynchronizecoworker
  @@transactionid uniqueidentifier,
  @@idrecord int,
  @@iduser int
AS
  DECLARE @firstname sysname
  DECLARE @lastname sysname
  DECLARE @fullname sysname

  -- Retrieve first name
  SELECT @firstname = ISNULL([advalue], N'')
    FROM #adfield
    WHERE [adlabel] = N'givenName'

  -- Retrieve last name
  SELECT @lastname = ISNULL([advalue], N'')
    FROM #adfield
    WHERE [adlabel] = N'sn'

  -- Put together full name
  SET @fullname = @lastname + N', ' + @firstname

  -- Update temporary table
  UPDATE #adfield
    SET [newvalue] = @fullname
    WHERE [adlabel] = N'cn'

RETURN 0
</code>

==== Additional settings ====
There are a few settings in the registry that can be set to modify the behavior. Most of the settings can be found in ''HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Lundalogik\Lundalogik Active Directory Integration'' and affect all databases on the server.

^ Vaule ^ Type ^ Description ^
| Debug | DWORD | If set to 1 debug information will be saved to C:\ProgramData\Lundalogik\ladi.log. Default is 0. |
| Domains | Multi-string | A list of all Active Directory domains that will be searched when looking Lime CRM Users. If not specified all two-way trusted domains will be searched. Use this setting to limit the number of searches and get better performance if there are several domains that don't contain any Lime CRM Users, or if one or a few domains are very slow. Use the fully qualified domain name, for example ad.mycompany.com |
| Timeout | DWORD | The number of seconds that the search result from Active Directory should be cached. Default is 300 seconds. If set to 0 no information will be cached. The value itself is cached for 1 minute, so if you change CacheTimeout it might take up to a minute before the change is reflected. Restart Lundalogik Data Components if you want the apply the changes immediately. |

For each database there is also a setting in ''HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Lundalogik\Lundalogik Data Components\Databases\<<database name>>'':

^ Value ^ Type ^ Description ^
| SynchronizeLoginUser | DWORD | If set to 0 no synchronizations will be made when users are logging in. Default is 1. |

===== Upgrading From Lime CRM Server < 12 =====
It's possible to map an AD group to the database itself. This allows AD users to be added as Lime CRM users without giving them login permission.

Consider the following scenario:

>The AD group //Employees// is currently mapped to the Lime CRM group //Users// with the auto-create option enabled in order to add them as users in Lime CRM using the synchronization feature. The reason for this is to get all employees into Lime CRM so that they can be assigned e.g. a helpdesk ticket even though they don't use Lime CRM themselves. Another AD group //Lime CRM Users//, containing all users that should be able to use Lime CRM is then included in the //Distributed COM Users// Windows group which controls login permissions. This means that all members of //Employees// will be imported, but those not in //Lime CRM Users// will not be able to log in.

Since authorization starting with Lime CRM Server version 12 no longer uses the //Distributed COM Users// group this means that the above setup will no work since all users in //Employees// will be able to log in to Lime CRM. To fix this some changes must be made to keep the previous behavior:

  * The AD group //Employees// must be mapped to the database. This is done in the Security Overview in LISA.
  * The AD group //Lime CRM Users// must be mapped to the Lime CRM group //Users// with auto-create activated.

Now everything will work in the same way as before, minus the extra complexity of the //Distributed COM Users// group.