Use an External Directory Service to Authenticate Users

If you use a directory service to centrally manage users in your organization, you can configure the Acrolinx Core Platform to search for user authentication information in your directory service instead of recreating users in the Dashboard.

Before you use external authentication with Acrolinx, all users in your directory service must have a password configured.

To configure external user authentication on the Acrolinx Core Platform, you must have a thorough knowledge of how your directory service is configured. External authentication is only suitable for organizations that have more than 100 Acrolinx users.

Note that external authentication doesn't necessarily ensure single sign-on from all Acrolinx Integrations. If you use Acrolinx in web editors such as CKEditor, you need to configure Acrolinx for single sign-on.

External Authentication Methods

External Authentication with JAAS

The Acrolinx Core Platform uses the Java Authentication and Authorization Service (JAAS) as the preferred method for authenticating users. JAAS supports many authentication technologies through the use of interchangeable login modules that anyone can implement. Many login modules for protocols such as LDAP and Kerberos are included in the Oracle Java Runtime Engine (JRE) that is bundled with the Acrolinx Core Platform.

Because LDAP is the authentication protocol that is most commonly used with Acrolinx, the instructions for configuring external authentication with JAAS use examples for the Oracle LDAP login module. However, these instructions can also be used as a reference when configuring login modules for other authentication technologies. 

External Authentication with the Legacy LDAP Implementation

As an alternative to using JAAS to authenticate with LDAP, you can configure Acrolinx to use the legacy LDAP authentication module that is implemented by Acrolinx. You use the legacy LDAP implementation if you require more fine-grained LDAP configuration options such as the ability to configure an internal authentication cache.

The legacy LDAP implementation is limited to one directory information tree (DIT). If your Acrolinx users are stored across multiple DITs, use JAAS instead.

Configuring LDAP Authentication with JAAS

You can configure Acrolinx to use the Java Authentication and Authorization Service (JAAS) to authenticate users against an LDAP server with the LDAP login module. This method is the preferred way to configure LDAP authentication in Acrolinx.

A JAAS login module for LDAP is included in the Oracle Java Runtime Engine (JRE). You configure LDAP authentication by creating a JAAS configuration file in the "bin" directory of your Acrolinx Core Platform installation. A sample configuration file "login.config.sample" is included in the same directory to help you get started.

If you use a JRE other than the Oracle JRE, check that your JRE includes a similar LDAP login module. These instructions are specific to the Oracle LDAP login module but might be helpful when configuring a similar login module.

Configuring the JAAS Properties and Enabling JAAS

To configure an LDAP connection you must create a JAAS configuration file that contains configuration properties for the LDAP login module. A sample configuration file "login.config.sample" is in included in the "bin" directory of your Acrolinx Core Platform installation to help you get started. You can save a copy of the sample configuration file in your configuration directory and update the properties with the correct values for your LDAP implementation.

To configure the JAAS settings, follow these steps:

  1. Open sample JAAS configuration file from the following location:

    <INSTALL_DIR>\server\bin\login.config.sample
  2. Save the file with the name login.config in the following location:

    %ACROLINX_CONFIGURATION_ROOT%\server\bin\

    If this location doesn’t yet exist, create the required subdirectories first.

  3. Update the following properties with the correct values for your LDAP implementation:

    PropertyuserProvider
    Description

    Update the property according to the following syntax:

    ldap://<LDAP_SERVER_ADDRESS>/<SEARCH_BASE>,

    For example: ldap://demo-inc.com/DC=demo-inc,DC=COM

    PropertyuserFilter
    Description
    Update this property with the filter that you want to use to find the correct LDAP entry for the user.

    The variable {USERNAME} is the username that users enter when logging on to Acrolinx.

    For example, if you want your users to enter their e-mail address as the Acrolinx username, update the line to the following:


    userFilter="mail={USERNAME}"


    The server then looks for users with an email address that matches the username that was entered to sign in to Acrolinx.

    To ensure that the user is a member of a specific group, enter a full LDAP query that matches the required groups. The following example is an LDAP query that filters for users who are in the departments "sales" or "marketing":

    Example
    userFilter="(&(cn={USERNAME})(objectClass=person)
    (|(member=cn=marketing,cn=groups,o=demo-inc,dc=demo-inc,dc=com)
    (member=cn=sales,cn=groups,o=demo-inc,dc=demo-inc,dc=com)))"

    If you require more information on the syntax of LDAP queries, Microsoft TechNet has a helpful article on LDAP query basics.

    Propertyjava.naming.security.principal
    Description
    If your LDAP server doesn’t permit anonymous user lookups, update the property this with the distinguished name (DN) of the account that performs user lookups.


    Example
    java.naming.security.principal="cn=user234,dc=acrolinx,dc=com"
    Propertyjava.naming.security.credentials
    Description
    If your LDAP server doesn’t permit anonymous user lookups, update this property with the password of the account that performs user lookups.

    For example: 

    java.naming.security.credentials="user234password"
    PropertyuseSSL
    Description

    If you don’t want Acrolinx to communicate with your LDAP server over a secure connection, set this property to false like in the following example:

    useSSL=false

    By default, the LDAP login module uses SSL to communicate with the LDAP server. You might temporarily disable SSL to test or troubleshoot a LDAP connection.

    Propertycom.sun.security.auth.module.LdapLoginModule
    Description

    If you have multiple LDAP servers then you'll need multiple JAAS configurations in your login.config file. Multiple LDAP servers are only supported from Acrolinx Core Platform version 2019.05.1 and later.

    With multiple JAAS configurations, make sure that each configuration contains the following line:

    com.sun.security.auth.module.LdapLoginModule Sufficient

    If you have multiple JAAS configurations and com.sun.security.auth.module.LdapLoginModule is set to Requisite or Required, users will run into authentication problems.

    Tip: You can find more information about the JAAS configuration properties in the Oracle Java documentation.
  4. Save your changes.

After you've configured an LDAP connection with JAAS, you must then enable JAAS as an authentication method. You do this in the core server properties.

To enable JAAS, 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 and save the core server properties file:

    authentication.useExternal=true 
    authentication.external=jaas
  3. Save your changes and restart the core server.
    If you use a secure connection to connect to your LDAP server, confirm that the LDAP server uses a certificate that is trusted

    In most cases, this step is required for self-signed certificates. If your directory server uses a certificate from an untrusted source, you must first confirm that the certificate is trusted before you can authenticate users.

    When Acrolinx detects an untrusted certificate on the directory server, it downloads the certificate to the configuration directory. You confirm that the certificate is trusted by moving the downloaded certificate file to a trusted location in the configuration directory.

    You can confirm that Acrolinx has detected an untrusted certificate by reviewing the log files for the following message:

    A communication partner provided a certificate that is not trusted.

LDAP and Active Directory

You can use the LDAP protocol to authenticate Acrolinx users against Microsoft Active Directory. An installation scenario where Acrolinx authenticates users against Active Directory also provides a good case study of how to configure the LDAP settings for Acrolinx in general.

The following recommendations and examples are specific to Active Directory but they also provide a general summary of the configurations that are described in the standard LDAP configuration procedures.

Recommendations

  • Configure a limited user in your Active Directory who has read-only access to your directory tree. The credentials for this user will be used by Acrolinx to query the Active Directory. The user should have limited access because the password for this user is saved in cleartext in the core server properties file.
  • Use an Active Directory tool to browse your directory tree. A visual representation of your Active Directory tree will help you understand your directory structure and identify the DNs of your users.

Example

Active Directory Tree with Distinguished Name and Search Key Highlighted

The previous screen is taken from an Apache LDAP Browser plug-in in Eclipse and shows the LDAP entry for the user "Test Case". In the screenshot you can see:

  1. The location of a user in the directory tree.

    Note that most nodes in the directory tree are identified by a common name (CN).

    This information is important for understanding how DNs are constructed in your directory tree. User DNs are constructed from the bottom up by combining the identifiers for each node in the tree. For example, the user node CN=Test Case is contained with in the node CS=Users, and CN=Users contained within the node DC=acrolinx,DC=local. These identifiers are then combined in a comma-separated list to form the DN.

  2. The DN of the user "Test Case". This DN is displayed as part of the user entry. You can see how user DNs follow the pattern CN=<COMMON_NAME>,CN=User,DC=acrolinx,DC=local.
  3. The base node where users are located in the directory tree. The "base" node is usually the name of the domain that your users belong to and has the DN DC=acrolinx,DC=local where DC indicates a domain component.
  4. A possible search key candidate. The search key is what your users would enter as their Acrolinx username instead of the distinguished name. The attribute mailNickname is a good candidate because it is short and doesn’t contain any special characters. Acrolinx uses the search key to get the DN and passes the DN to the directory service for authentication.

The following example contains a configuration that is based on the information in the previously illustrated directory tree. You can use this example to update the JAAS configuration file for your environment.

Example
other {
 com.sun.security.auth.module.LdapLoginModule Requisite
	userProvider="ldaps://ldapserver.acrolinx.local"
	useSSL="true"
	userFilter="(&(mailNickname={testcase})(objectClass=person)(|(member=cn=.Sales,cn=groups,dc=acrolinx,dc=local)(.Marketing,cn=groups,dc=acrolinx,dc=local)))"
	java.naming.security.principal="cn=lookupuser,dc=acrolinx,dc=com"
	java.naming.security.credentials="M3pruhUG"
	;
};

Note that the domain acrolinx.local is defined as the "base" node for all LDAP queries and is referred to by the DN dc=acrolinx,dc=local. To run queries successfully, Acrolinx must be able to resolve this domain to an IP address. You can ensure that Acrolinx can successfully query your Active Directory by adding the domain to the list of domains in the hosts file on the computer where your Acrolinx Core Platform is installed.

Additionally, the previous example also includes filter criteria for group membership. If you look at the userFilter line, you can see the following criteria: 

(|(member=cn=.Sales,cn=groups,dc=acrolinx,dc=local)(.Marketing,cn=groups,dc=acrolinx,dc=local))

These criteria ensure that only users in the group .Sales or .Marketing can access Acrolinx.

Configuring the Authentication Settings

You can update the authentication settings to change how long Acrolinx should authenticate users locally or when the saved credentials for a user should expire.

After a user enters their password for the first time, the authentication details are saved by the Acrolinx Core Platform in the authentication cache. Acrolinx can use the authentication cache to authenticate users locally, which means that Acrolinx doesn’t have contact your LDAP server for every user transaction. Additionally, an authentication token is saved for each user. Acrolinx uses this token to authenticate users with your LDAP server without having to prompt users for their credentials again.

The authentication settings apply for both the JAAS and the legacy LDAP methods.

Configuring the Authentication Timeout

You can use the authentication timeout setting to configure how often users are required to re-enter their external authentication details when connecting to Acrolinx.

To avoid a mismatch between the password saved in Acrolinx and the password in your directory service, the saved password times out after a default period of thirty days. After thirty days, users are prompted to re-enter their authentication details again when accessing Acrolinx.

You might change this setting if you want your users to have to re-enter their credentials more often.

To configure the authentication timeout, 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

    Add the following property:

    license.authTokenExpireTimeMinutes=<MINUTES>

    Specify in minutes how often users should be prompted for their authentication details.

    For example, to specify a timeout of ten days, enter the property as follows:

    Example
    license.authTokenExpireTimeMinutes=14400
  2. Save your changes and restart the core server.

Configuring the Internal Authentication Cache

The internal authentication cache reduces the number of LDAP transactions required to authenticate a user by storing authentication details after the user is successfully authenticated for the first time. The user is again authenticated externally after the lifetime of the internal authentication cache has lapsed.

To configure the internal authentication cache, 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.localAuthenticationLifetimeMinutes=<MINUTES>

    Specify the lifetime for the internal authentication cache in minutes.

    Example
    authentication.external.ldap.localAuthenticationLifetimeMinutes=30

    The default value for the property authentication.external.ldap.localAuthenticationLifetimeMinutes is 5 minutes.

  3. Save your changes and restart the core server.