Use an External Directory Service to Authenticate Users

Overview

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 to configure your directory service. 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.

If you use Google user management, you might want to consider using OAuth to authenticate your users instead. This is the simplest solution for user management.

Acrolinx only supports the method described in this article for On-Premise or Standard Stack instances. For Acrolinx Private Cloud, we can set up your users with Enterprise Federated Authentication.

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 come with 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, you can also use these instructions as a reference when configuring login modules for other authentication technologies.

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 comes with 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 need to create a JAAS configuration file that includes configuration properties for the LDAP login module. A sample configuration file "login.config.sample" is comes 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:

    Property userProvider
    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

    Property userFilter
    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, LDAP Wiki has a helpful article on LDAP query basics.

    Property java.naming.security.principal
    Description
    If your LDAP server doesn’t allow 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"
    Property java.naming.security.credentials
    Description
    If your LDAP server doesn’t allow anonymous user lookups, update this property with the password of the account that performs user lookups.

    For example: 

    java.naming.security.credentials="user234password"
    Property useSSL
    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 an LDAP connection.

    Property com.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 trusted certificate

    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. To confirm that the certificate is trusted, move 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. Acrolinx will use the credentials for this user 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 comes 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’s 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 includes 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 needs to 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 Acrolinx Core Platform saves the authentication details in the authentication cache. Acrolinx can use the authentication cache to authenticate users locally, which means that Acrolinx doesn’t have contact to 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 need 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.