We strongly recommend that you use LDAP as the authentication backend for REM to enhance security.

A centralized LDAP service for user accounts, which provides security features such as password policy enforcement and automatic account locking, should be used.

Before getting to configuration, we need to discuss how REM users and roles interact with LDAP, and the two methods that can be used to authenticate users using LDAP.

REM users and roles when LDAP is used

REM uses LDAP strictly as an authentication service. Authorisation is handled solely by REM’s understanding of user roles, as follows:

  • LDAP users without corresponding REM user accounts are entirely unauthorized and cannot log in to REM. User accounts must be created in REM using the 'Users and Roles' management interface for every LDAP user who needs access to REM.

  • REM user accounts, not LDAP user accounts, provide the set of REM roles used to enable or disable particular REM views and actions. Any required REM role changes must be made via the REM 'Users and Roles' management interface.

LDAP authentication methods

REM can use either "direct mode" or "search mode" to authenticate users against LDAP. The direct mode is simpler, while the search mode is more flexible.

Direct mode

The direct mode is the simplest, safest, but most restricted LDAP authentication method. REM is configured with a DN template string, and when a user tries to log in, the user name provided by the user is inserted into that template to generate a DN. REM then attempts an LDAP bind against the generated DN with the password provided by the user. If the bind succeeds, the user is successfully authenticated. If the bind fails, REM denies access to the user.

Search mode

The search mode provides more flexibility at the cost of additional configuration. In this mode, REM is configured with LDAP authentication credentials of its own plus some search parameters for locating users. When a user tries to log in, REM binds to LDAP with its configured authentication credentials and searches for the correct DN by combining search parameters with the user name provided by the user. If a DN is successfully located, REM attempts an LDAP bind using that DN and the password provided by the user. If both the DN search and a bind using that DN succeed, then the user is successfully authenticated. If either the DN search or the bind fails, REM denies access to the user.

Configuring REM to use LDAP authentication

Follow these steps to configure REM to use LDAP authentication. These instructions assume a fresh, empty REM installation.

1. Create an LDAP-backed REM administration account

Before doing anything else, create an LDAP-authenticated REM administration account. Pick one of these two approaches:

  • Create an LDAP user entry matching the default REM administrator account name emadm. To do so:

    1. Create an LDAP user entry for emadm. Step-by-step instructions for doing this are beyond the scope of this manual; for those instructions, see your LDAP server vendor’s documentation.

    2. Start REM.

    3. Log in using the default REM administrator credentials: user emadm with the password of password.

    4. Select Edit Element Manager Users and Roles.

    5. Change the password for the emadm user to a strong password. This is a precaution in case LDAP authentication is accidentally disabled at some point in the future and REM is left using its own internal password database.

    6. Either delete the user user or change its password to a strong password.

    7. Stop REM.

  • Replace REM’s default administrator account with one already present in your LDAP service. To do so:

    1. Start REM.

    2. Log in using the default REM administrator credentials: user emadm with the password of password.

    3. Select Edit Element Manager Users and Roles.

    4. Click Add User and set:

      1. Username to match the desired LDAP entry, after template expansion (for direct mode), or search (for search mode).

      2. Real name as you wish.

      3. New Password and New Password (again) to a strong password. This is a precaution in case LDAP authentication is accidentally disabled at some point in the future and REM is left using its own internal password database.

      4. Roles to include at least em-adm so that this account can manage other REM users. Add any other roles as desired.

    5. Save the new user.

    6. Select and delete the default REM accounts: emadm and user. This is a precaution to prevent unintended access if your LDAP service already contains those user names.

    7. Stop REM.

2. Add your LDAP CA root certificate to rhino-ems.truststore

The only TLS certificates which will be trusted by REM are those that appear in rhino-ems.truststore, so the root certificate for your LDAP server’s TLS certificate must be added to it. Acquiring the root certificate is beyond the scope of this manual, but possibilities include:

  • Acquire the certificate from the certificate authority who provided your LDAP server’s TLS certificate, either as a download or through their support team.

  • Extract the certificate from your JDK’s lib/security/cacerts keystore.

  • Use the LDAP server’s certificate directly, or one of the intermediate certificates in its chain.

    Note This approach is prone to causing REM to reject the LDAP server whenever the LDAP server gets a new TLS certificate.

Once you’ve acquired the certificate in the PEM format, locate your rhino-ems.truststore file and change the current directory to where it is:

  • For stand-alone REM, the rhino-ems.truststore will be in the top-level Rhino element manager installation directory.

  • For Tomcat-based REM, the rhino-ems.truststore will be in the rem_home directory within Tomcat’s top-level installation directory.

Then use this command, with $PATH_TO_YOUR_CA_CERT replaced with the correct path to your CA certificate, to add the certificate to the rhino-ems.truststore file:

keytool -importcert -noprompt -alias ldap-server-ca-cert -file $PATH_TO_YOUR_CA_CERT -keystore rhino-ems.truststore

You will be prompted for a keystore password, which can be found in the rhino.remote.ssl.trustStorePassword property of the rem.properties file.

Note The password in the properties file may include backslash escape sequences that you must manually unescape before entering the passphrase into keytool. If you see a lengthy error message that ends with Failed PKCS12 integrity checking, then you have entered the wrong password, possibly because you unescaped the password incorrectly, or forgot to unescape it.

3. Enable JAAS in REM

The Java Authentication and Authorization Service is a Java-standard mechanism for configuring flexible authentication and authorisation services, and is how REM is instructed to use LDAP.

The procedure for enabling JAAS in REM differs for stand-alone REM installations and Tomcat-based installations. Select the relevant procedure from the two below.

Enable JAAS in stand-alone REM

  1. Edit the script you are using to start REM, typically one of:

  2. Find this line, which is present in all the files listed above:

    #JVM_ARGS="${JVM_ARGS} -Djava.security.auth.login.config=${REM_HOME}/rem.jaas"

    and uncomment it by removing the # at the start of the line so that it becomes:

    JVM_ARGS="${JVM_ARGS} -Djava.security.auth.login.config=${REM_HOME}/rem.jaas"

  3. Save the file, overwriting the original copy.

Enable JAAS in Tomcat-based REM

These instructions assume you have created a bin/setenv.sh script while following the instructions in Setting up Tomcat to run REM.

Note You may need to adapt these instructions if your Tomcat instance requires JAAS for other applications and/or itself.

  1. Edit Tomcat’s bin/setenv.sh script, adding the following line at the end of the file:

    CATALINA_OPTS="$CATALINA_OPTS -Djava.security.auth.login.config=${REM_HOME}/rem.jaas"

  2. Save the file, overwriting the original copy.

4. Use LDAP, and only LDAP, via JAAS policy

JAAS policy controls which authentication and authorization types are used.

  1. Edit or create the file rem.jaas, whose location varies by installation type:

    • For stand-alone REM the rem.jaas will be in the top-level Rhino element manager installation directory.

    • For Tomcat-based REM the rem.jaas will be in the rem_home directory within Tomcat’s top-level installation directory.

  2. Set the content of rem.jaas to:

    rhino-element-manager {
    com.opencloud.rem.server.security.auth.LdapLoginModule REQUIRED
    properties = "${rem.home}/ldapauth.properties";
};

  3. Then save the file, overwriting the original.

5. Define REM’s LDAP querying behaviour

REM needs to know how to reach the LDAP service, and how to use it. This is controlled by the properties in ldapauth.properties.

  1. Edit or create the ldapauth.properties file, whose location varies by installation type:

    • For stand-alone REM the ldapauth.properties will be in the top-level Rhino element manager installation directory.

    • For Tomcat-based REM the ldapauth.properties will be in the rem_home directory within Tomcat’s top-level installation directory.

  2. Set the following properties within the ldapauth.properties file:

    ldap.url

    to the URL for your LDAP service, in the either the form:

    • ldaps://host[:port]/basedn, or

    • ldap://[host[:port]]/basedn if STARTTLS should be used for TLS.

    Here are some examples:

    # Connect to local directory server
ldap.url=ldap:///dc=example,dc=com
    # Connect to remote directory server (ldap.usetls should be set to true)
ldap.url=ldap://remoteserver/dc=example,dc=com
    # Connect to remote directory server using SSL
ldap.url=ldaps://remoteserver/dc=example,dc=com
    ldap.usetls

    to true, unless an ldaps URL was used for ldap.url, in which case this property should be left unset:

    ldap.usetls=true

Decide whether to use Direct mode or Search mode, and continue editing ldapauth.properties as directed by the relevant subsection below. REM cannot use both modes at the same time. If you configure both modes, REM will use direct mode.

Configuring direct mode

  1. In ldapauth.properties set:

    ldap.userdnpattern

    to a DN pattern that can be used to directly login users to LDAP. This pattern is used for creating a DN string where the pattern is relative to the base DN in the ldap.url. The string {0} will be replaced with the user name submitted in the login prompt.

    Here’s an example:

    # This is relative to the ldap.url base DN given
ldap.userdnpattern=uid={0},ou=People

  2. Save ldapauth.properties, overwriting the original, and proceed to step 6. Start REM and provision additional users.

Configuring search mode

  1. In ldapauth.properties set:

    ldap.managerdn

    to the LDAP account DN which should be used to search for the LDAP DN of the user attempting to log in to REM. This may be blank if the LDAP server allows anonymous connections to search adequately.

    ldap.managerpw

    to the password for the ldap.managerdn configured above. This may be blank if the LDAP server allows anonymous connections to search adequately.

    ldap.searchfilter

    to the LDAP filter expression that should be used to locate the DN of the user attempting to log in to REM. The string {0} will be replaced by the submitted username. The scope of this search may be adjusted using ldap.searchbase as documented below.

    Here’s an example:

    ldap.searchfilter=(uid={0})
    ldap.searchbase

    optionally, to the context name to search in, relative to the base DN given in the ldap.url. This property may be omitted if not required.

    Here’s an example:

    ldap.searchbase=ou=People

  2. Save ldapauth.properties, overwriting the original.

  3. Ensure that only the REM (or Tomcat, as appropriate) user can read ldapauth.properties if you set ldap.managerpw, because it now contains a password in clear text that is available to anyone who can read the file.

  4. Proceed to step 6. Start REM and provision additional users.

6. Start REM and provision additional users

Finally:

  1. Start REM.

  2. Log in as the LDAP-authenticated REM administration user you chose in 1. Create an LDAP-backed REM administration account.

  3. Create any additional REM user and/or REM administration accounts that you require using REM’s Users and Roles page. Remember:

    • No LDAP user will have access to REM unless there is a corresponding REM user account defined within REM itself.

    • User permissions in REM are controlled by the REM roles assigned to the REM user via the REM management interface. REM does not use LDAP to determine user roles.

Troubleshooting LDAP authentication problems

You may need to troubleshoot if LDAP authentication isn’t working after following the steps above. Here are the two most useful things to try, in order.

Enable debug logging in REM

To enable debug logging in REM:

  1. Edit log4j2.properties and

    1. Comment out the line:

      logger.rolling.level=INFO

      so that it becomes:

      #logger.rolling.level=INFO

    2. Change the line:

      rootLogger.level=INFO

      to

      rootLogger.level=DEBUG

  2. Save log4j2.properties, overwriting the original.

  3. Restart REM.

Enable JDK TLS debugging

If the REM debug logging, or anything else, indicates a TLS problem, add the second line shown below just below the first line shown below in your REM startup script:

JVM_ARGS="${JVM_ARGS} -Djava.security.auth.login.config=${REM_HOME}/rem.jaas"
JVM_ARGS="${JVM_ARGS} -Djavax.net.debug=all"

(For Tomcat installations, edit setenv.sh and use CATALINA_OPTS instead of JVM_ARGS.)

This enables the JDK’s built in TLS debugging, producing a lot of output that should help you diagnose the cause of the TLS problem.

Previous page