Configure the Legacy LDAP Implementation

If you prefer to use the legacy Acrolinx LDAP implementation instead of the JAAS LDAP login module, you must update your overlay of the coreserver.properties file with two sets of LDAP configuration properties:

  • Properties that define the connection to the LDAP server.
  • Properties that define how users are authenticated.

Configuring the Legacy LDAP Server Connection Properties

The LDAP server connection properties configure the legacy LDAP authentication module that is implemented by Acrolinx. The preferred way to configure LDAP is with JAAS. However, you can still use these legacy properties if JAAS doesn’t suit your requirements.

To configure the LDAP server connection properties, follow these steps:

  1. Open your overlay of the core server properties file.

    You find the overlay for the core server properties file in the following location: 

    %ACROLINX_CONFIGURATION_ROOT%\server\bin\coreserver.properties
  2. Add the following properties:

    TABLE 1. LDAP SERVER CONNECTION PROPERTIES

    PropertyDescription
    authentication.useExternal=true

    Enable external authentication.

    The default value is false. If this property is absent or set to false, all other properties related to external authentication are ignored.
    authentication.external=ldapSpecify the 'ldap' method for external authentication.
    authentication.external.ldap.protocolSpecify the level of security that you require for LDAP transactions. You can use the following values with this property:
    • ldap - Use unencrypted transactions for both the distinguished name lookup and user authentication.

      You might use this value for test environments or environments that don’t accept encrypted transactions.

    • ldap,ldaps - Perform distinguished name lookups with unencrypted transactions but use secure transactions to authenticate users.

      This value is the default value if the property isn’t specified. You might use this value to ensure that the most important transactions are secure while also minimizing the network bandwidth required for distinguished name lookups.

    • ldaps - Use secure transactions for both the distinguished name lookup and user authentication.

      Because secure transactions contain more data, this option is the most secure but requires the most network bandwidth.

    authentication.external.ldap.ldapUrlSpecify the URL of the LDAP server which handles distinguished name resolution and group membership checking.
    (optional) authentication.external.ldap.userName

    (optional) authentication.external.ldap.password

    Specify log-in credentials for the LDAP server which handles distinguished name resolution and group membership checking. For any user name, you must also specify a password. You can only use log-in credentials with both a user name and a password.

    If you do not specify any log-in credentials, the Acrolinx Server attempts to use an anonymous connection.

    Example:


    authentication.external.ldap.userName=acrolinx
    
    authentication.external.ldap.password=test
    authentication.external.ldap.base
    Specify the LDAP base for searches on the LDAP server.

    Example:

    authentication.external.ldap.base=directoryname=maindir,companydivision=company.com
    authentication.external.ldap.secureUrl
    Specify the URL of the secure LDAP server which handles the authentication.

    Example:

    authentication.external.ldap.secureUrl=ldaps://ldapserver.company.com

    The following example contains sample values for all of the properties described in the previous table:

    authentication.useExternal=true
                                authentication.external=ldap
                                authentication.external.ldap.protocol=ldap,ldaps
                                authentication.external.ldap.ldapUrl=ldap://ldapserver.company.com
                                authentication.external.ldap.userName=acrolinx
                                authentication.external.ldap.password=test
    authentication.external.ldap.base=directoryname=maindir,companydivision=company.com
                                authentication.external.ldap.secureUrl=ldaps://ldapserver.company.com
  3. Save your changes and restart the core server.

Configuring Distinguished Name Detection

Most LDAP servers require a distinguished name (DN) to authenticate a user. The DN is the unique identifier for each an entry in the directory.

Example of a DN for a user: CN=Alex Lee,CN=User,DC=company,DC=local

Users can enter their distinguished name as their Acrolinx user ID, or you can configure the Acrolinx Server to resolve the DN for each user based on another identifier that a user enters as their Acrolinx user ID.

If your LDAP server doesn’t require a DN for authentication, or if you prefer your users to enter their distinguished names as their user ID, you must disable distinguished name detection.

To configure DN detection, follow these steps:

  1. Open your overlay of the core server properties file.

    You find the overlay for the core server properties file in the following location:

    %ACROLINX_CONFIGURATION_ROOT%\server\bin\coreserver.properties
  2. Add the following properties:
    • authentication.external.ldap.distinguishedNameEntrySearchKey=<FIELD_NAME>

      This property defines the type of information that users must enter as their user ID when logging on to Acrolinx. The information entered for the Acrolinx user ID is then used to find the correct LDAP entry for the user.

      For example, if your users enter their e-mail address as the Acrolinx user ID, add the line:

      authentication.external.ldap.distinguishedNameEntrySearchKey=e-mailaddress

      In this example, when a user logs on to Acrolinx with the user ID jsmith@company.comthe Acrolinx server searches for LDAP entries where the field e-mailaddress has the value jsmith@company.com and finds the entry for "Jane Smith".


    • authentication.external.ldap.distinguishedNamePattern

      This property defines the pattern of the DN used to log on to your LDAP server. This pattern consists of fields in the LDAP user entry. The variables in the pattern take the following form, separated by a comma:

      <FIELD_NAME>=%<FIELD_NAME>%

      During authentication, the variables are replaced with the value of field found in the user entry. For DN detection to work correctly, every field in the pattern must only occur once within each user entry.

      For example, if your login DN consists of the user identifier, country, and employee code, add the line:

      authentication.external.ldap.distinguishedNamePattern=uid=%uid%,country=%country%,employeecode=%employeecode%

      In a previous example, the e-mail address of the user "Jane Smith" was used to detect her LDAP entry. When detecting the login DN for Jane Smith, the Acrolinx Server looks in the entry for her uid,country, and employeecode and generates the login DN uid=jsmith,country=US,employeecode=JS153672.

      By default, the server escapes any special characters in the resolved field values. If a field value contains special characters that must be treated literally, you must prefix the field name with an equals sign.

      For example, suppose you have a user entry that contains the following field and value pair seeAlso=ou=system

      The field contains a reference to the organizational unit field "ou". This reference uses the equals sign to indicate that "system" is the value for the "ou" field. However, the equals sign is also part of the value for the seeAlso field and would be escaped by default.

      To ensure that the equals sign is correctly interpreted as being part of the reference, you must add the seeAlso field using the following syntax.

      seeAlso=%=seeAlso%
      

      The equals sign before the field name variable ensures that all special characters in the resolved field values are treated literally.

  3. Save your changes and restart the core server.

Disabling Distinguished Name Detection

You might want to disable the automatic distinguished name (DN) detection if your LDAP server doesn’t require a DN for authentication, or if you prefer your users to enter their DN when logging in.

To disable distinguished name detection, follow these steps:

  1. Open your overlay of the core server properties file.

    You find the overlay for the core server properties file in the following location:

    %ACROLINX_CONFIGURATION_ROOT%\server\bin\coreserver.properties
  2. Add the following property:

    authentication.external.ldap.useUserNameMapping=false
  3. Save your changes and restart the core server.

Configuring Group Membership

You configure LDAP user authentication to restrict Acrolinx Server access to members of specific LDAP groups.

To configure authentication based on group membership, follow these steps:

  1. Open your overlay of the core server properties file.

    You find the overlay for the core server properties file in the following location:

    %ACROLINX_CONFIGURATION_ROOT%\server\bin\coreserver.properties
  2. Add the following properties:
    • authentication.external.ldap.requireGroupMembership=true

      to activate group membership authentication.

    • authentication.external.ldap.groupAttributes

      to enter a semicolon-separated list of LDAP entry attributes which contain information about which groups a user belongs to:

      Example: authentication.external.ldap.groupAttributes=maingroups;secondarygroups

    • authentication.external.ldap.permittedGroups

      to enter a semicolon-separated list of the distinguished names for each permitted group. The user must be a member of at least one of the listed groups. Example:

      authentication.external.ldap.permittedGroups=commonName=TechDoc,orgUnit=usergroup,org=company.com;commonName=Marketing,orgUnit=usergroup,org=company.com .
  3. Save your changes and restart the core server.
  4. After you've configured the legacy LDAP settings, configure the general authentication settings.