[en] If you don't want to recreate users in the Dashboard, you can configure Acrolinx to search for user authentication information in your directory service. This is useful if you use a directory service for centralized management of the users in your organization.
[en] Before you use external authentication with Acrolinx, all users in your directory service must have a password configured.
[en] To configure external user authentication on the Acrolinx 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.
[en] 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 set up Acrolinx for single sign-on.
Tipp
[en] 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.
[en] Acrolinx only supports the method described in this article for Standard Stack instances. For Acrolinx Private Cloud, we can set up your users with Enterprise Federated Authentication.
[en] Acrolinx prefers to use the Java Authentication and Authorization Service (JAAS) to authenticate 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 Platform.
[en] LDAP is the authentication protocol that is most commonly used with Acrolinx. That's why the configuration instructions for external authentication with JAAS use examples for the Oracle LDAP login module. However, you can also use these instructions as a reference if you plan to configure login modules for other authentication technologies.
[en] It's possible to 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.
[en] 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" comes a container your Acrolinx Platform installation to help you get started. You need to save a copy of the sample configuration file in your configuration directory and update the properties with the correct values for your LDAP implementation.
[en] To configure the JAAS settings, follow these steps:
-
[en] Run the following command to save the JAAS configuration file to your configuration directory:
kubectl cp -n acrolinx acrolinx-core-server-0:/opt/server/bin/login.config.sample /home/acrolinx/config/server/bin/login.config.sample
-
[en] Update the following properties with the correct values for your LDAP implementation:
[en] Property
[en] userProvider
[en] Description
[en] Update the property according to the following syntax:
ldap://<LDAP_SERVER_ADDRESS>/<SEARCH_BASE>,
[en] For example:
ldap://demo-inc.com/DC=demo-inc,DC=COM
[en] Property
[en] userFilter
[en] Description
[en] Update this property with the filter that you want to use to find the correct LDAP entry for the user.
[en] The variable
{USERNAME}
is the username that users enter when logging on to Acrolinx.[en] 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}"
[en] The server then looks for users with an email address that matches the username used to sign in to Acrolinx.
[en] 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":
[en] Example
userFilter="(&(cn={USERNAME})(objectClass=person) (|(memberOf=cn=marketing,cn=groups,o=demo-inc,dc=demo-inc,dc=com) (memberOf=cn=sales,cn=groups,o=demo-inc,dc=demo-inc,dc=com)))"
[en] Property
[en] java.naming.security.principal
[en] Description
[en] If your LDAP server doesn’t allow anonymous user lookups, update this property with the distinguished name (DN) of the account that does user lookups. Example
java.naming.security.principal="cn=user234,dc=acrolinx,dc=com"
[en] Property
[en] java.naming.security.credentials
[en] Description
[en] If your LDAP server doesn’t allow anonymous user lookups, update this property with the password of the account that does user lookups.
[en] For example:
java.naming.security.credentials="user234password"
[en] Property
[en] useSSL
[en] Description
[en] 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
[en] 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.
[en] Property
[en] com.sun.security.auth.module.LdapLoginModule
[en] Description
[en] If you have multiple LDAP servers, then you'll need multiple JAAS configurations in your
login.config
file. Only Acrolinx Platform version 2019.05.1 and later support multiple LDAP servers.[en] With multiple JAAS configurations, make sure that each configuration includes the following line:
com.sun.security.auth.module.LdapLoginModule Sufficient
[en] If you have multiple JAAS configurations and
com.sun.security.auth.module.LdapLoginModule
is set toRequisite
orRequired
, users will run into authentication problems.Tipp
[en] Tip: You can find more information about the JAAS configuration properties in the Oracle Java documentation.
-
[en] Save your changes.
[en] 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.
[en] To enable JAAS, follow these steps:
-
[en] Open your
coreserver.properties
. -
[en] Add the following properties and save the core server properties file:
authentication.useExternal=true authentication.external=jaas
-
[en] Save your changes and restart the Acrolinx Platform.
[en] If you use a secure connection to connect to your LDAP server, confirm that the LDAP server uses a trusted certificate.
[en] In most cases, you'll need to follow this step for self-signed certificates. If your directory server uses a certificate from an untrusted source, you'll first need to confirm that the certificate is trusted before you can authenticate users.
[en] When Acrolinx detects an untrusted certificate on the directory server, it downloads the certificate to the configuration directory. If you want to confirm that the certificate is trusted, move the downloaded certificate file to a trusted location in the configuration directory.
[en] To confirm that Acrolinx has detected an untrusted certificate, review the log files for the following message:
A communication partner provided a certificate that is not trusted.
[en] It's possible to 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.
[en] The following recommendations and examples are specific to Active Directory. They also provide a general summary of the configurations described in the standard LDAP configuration procedures.
-
[en] In your Active Directory, configure a limited user 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.
-
[en] 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.
[en] Active Directory Tree with Distinguished Name and Search Key Highlighted
[en] 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:
-
[en] The location of a user in the directory tree.
[en] Note that most nodes in the directory tree are identified by a common name (CN).
[en] 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 in the nodeCS=Users
, andCN=Users
in the nodeDC=acrolinx,DC=local
. These identifiers are then combined in a comma-separated list to form the DN. -
[en] 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
. -
[en] 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. It has the DN
DC=acrolinx,DC=local
where DC indicates a domain component. -
[en] 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 have any special characters. Acrolinx uses the search key to get the DN and passes the DN to the directory service for authentication.
[en] 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.
[en] Example
other { com.sun.security.auth.module.LdapLoginModule Requisite userProvider="ldaps://ldapserver.acrolinx.local" useSSL="true" userFilter="(&(mailNickname={testcase})(objectClass=person)(|(memberOf=cn=.Sales,cn=groups,dc=acrolinx,dc=local)(memberOf=cn=.Marketing,cn=groups,dc=acrolinx,dc=local)))" java.naming.security.principal="cn=lookupuser,dc=acrolinx,dc=com" java.naming.security.credentials="M3pruhUG" ; };
[en] Note that the domain acrolinx.local
is defined as the "base" node for all LDAP queries. It's 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. To ensure that Acrolinx can successfully query your Active Directory, you can add the domain to the list of domains in the hosts file on the computer where your Acrolinx Platform is installed.
[en] Additionally, the previous example also includes filter criteria for group membership. If you look at the userFilter
line, you can see the following criteria:
(|(memberOf=cn=.Sales,cn=groups,dc=acrolinx,dc=local)(memberOf=cn=.Marketing,cn=groups,dc=acrolinx,dc=local))
[en] These criteria ensure that only users in the group .Sales
or .Marketing
can access Acrolinx.
[en] It's possible to update the authentication settings to change how long Acrolinx should authenticate users locally or when the saved credentials for a user should expire.
[en] After a user enters their password for the first time, the Acrolinx 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. Acrolinx also saves an authentication token is saved for each user. It uses this token to authenticate users with your LDAP server without having to prompt users for their credentials again.
[en] You can use the authentication timeout setting to configure how often users need to re-enter their external authentication details when they connect to Acrolinx.
[en] 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.
[en] You might change this setting if you want your users to have to re-enter their credentials more often.
[en] To configure the authentication timeout, follow these steps:
-
[en] Open your
coreserver.properties.
-
[en] Add the following property:
license.authTokenExpireTimeMinutes=<MINUTES>
[en]
Specify in minutes how often users should be prompted for their authentication details.
[en] For example, to specify a timeout of ten days, enter the property as follows:
[en] Example
license.authTokenExpireTimeMinutes=14400
-
[en] Save your changes and restart the Acrolinx Platform.
[en] The internal authentication cache reduces the number of LDAP transactions required to authenticate a user. To do so, it stores 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.
[en] To configure the internal authentication cache, follow these steps:
-
[en] Open your
coreserver.properties.
-
[en] Add the following property:
authentication.external.ldap.localAuthenticationLifetimeMinutes=<MINUTES>
[en] Specify the lifetime for the internal authentication cache in minutes.
[en] Example
authentication.external.ldap.localAuthenticationLifetimeMinutes=30
[en] The default value for the property
authentication.external.ldap.localAuthenticationLifetimeMinutes
is 5 minutes. -
[en] Save your changes and restart the Acrolinx Platform.