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:
- 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:
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:
- 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 Caseis contained with in the nodeCS=Users, andCN=Userscontained within the nodeDC=acrolinx,DC=local. These identifiers are then combined in a comma-separated list to form the DN. - 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. - 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=localwhere DC indicates a domain component. - 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
mailNicknameis 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.
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:
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: