The Java Authentication and Authorization Service (JAAS) allows integration with enterprise systems, identity servers, databases, and password files.

JAAS configuration

The file rhino.jaas defines the JAAS modules Rhino uses for authentication:

/** Login Configuration for OpenCloud Rhino **/

jmxr-adaptor {
    com.opencloud.rhino.security.auth.FileLoginModule REQUIRED
    file="$${rhino.dir.base}/rhino.passwd"
    hash="SHA3-512";
};
Note See the Javadoc for the JAAS Configuration class for details about flags such as REQUIRED.

The system property java.security.auth.login.config defines the location of rhino.jaas (in read-config-variables for a production Rhino instance and jvm_args for the Rhino SDK.)

Rhino contains JAAS login modules based on files, LDAP, and JAIN SLEE profiles.

File login module

The FileLoginModule reads login credentials and roles from a file. It is the default login module for a new Rhino installation.

The parameters to the FileLoginModule are:

  • file - specifies location of password file.

  • hash - password hashing algorithm. Use none for clear text passwords, or a valid java.security.MessageDigest secure hash algorithm name (e.g. SHA-1 or SHA3-512). If not specified, a default secure hash algorithm is used.

Password File Format

<username>:<password>:<role,role...>

  • username - user’s name

  • password - user’s password (or hashed password). May be prefixed by the hash method in {}.

  • roles - comma-separated list of role names that the user belongs to, eg. rhino,view.

Tip
Using flags and hashed passwords

By default, Rhino stores passwords in cleartext, in the password file. For increased security, store a secure one-way hash of the password instead:

  1. Configure the file login module, changing the hash="none" option to a secure hash algorithm such as hash="SHA3-512".

  2. Use the client/bin/rhino-passwd utility to generate hashed passwords.

  3. Copy those hashed passwords into the password file.

LDAP login module

The LdapLoginModule reads login credentials and roles from an LDAP directory server.

To use this module, edit the JAAS configuration file ${RHINO_HOME}/config/rhino.jaas, and add an entry to the jmxr-adaptor declaration:

jmxr-adaptor {
    com.opencloud.rhino.security.auth.LdapLoginModule SUFFICIENT
        properties="config/ldapauth.properties";

    /* a "backup" login module would typically go here */
};

Configuration Properties

The properties file contains LDAP connection parameters. The properties that this module uses are documented in the example ldapauth.properties file, along with default values and examples

The file config/ldapauth.properties defines the LDAP-connection configuration:

### Properties for JAAS LDAP login module (LdapLoginModule)
#
# The commented values are the default values that will be used if the given property is not specified.
# The ldap.url property has no default and must be specified.
#
# This properties file should be supplied to the LdapLoginModule using the "properties" property, e.g.
#
# jmxr-adaptor {
#     com.opencloud.rhino.security.auth.LdapLoginModule SUFFICIENT
#     properties="config/ldapauth.properties";
#  };
#

### Connection properties

# An LDAP URL of the form ldap://[host[:port]]/basedn or ldaps://host[:port]/basedn
# Some examples:
# Connect to local directory server
#ldap.url=ldap:///dc=example,dc=com
# Connect to remote directory server
#ldap.url=ldap://remoteserver/dc=example,dc=com
# Connect to remote directory server using SSL
#ldap.url=ldaps://remoteserver/dc=example,dc=com
ldap.url=

# Use TLS.  When set to true, the LdapLoginModule attempts a "Start TLS" request when it connects to the
# directory server.  This should NOT be set to true when using an ldaps:// (SSL) URL.
#ldap.usetls=true

# To use TLS or SSL, you must have your directory server's X509 certificate installed in Rhino's trust
# store, located at $RHINO_BASE/rhino-server.keystore.

### Authentication properties

## Direct mode
# In "direct mode", the login module attempts to bind using a DN calculated from the pattern property.
# Direct mode is used if the ldap.userdnpattern property is specified.

# A DN pattern that can be used to directly login users to LDAP.  This pattern is used for creating a DN string for
# 'direct' user authentication, where the pattern is relative to the base DN in the LDAP URL.
# {0} will be replaced with the submitted username.
# A typical value for this property might be "uid={0},ou=People"

#ldap.userdnpattern=

## Search mode
# In "search mode", the login module binds using the given manager credentials and searches for the user.
# Authentication to LDAP will be done from the DN found if successful.
# Search mode is used if the ldap.userdnpattern property is not specified.

# Bind credentials to search for the user.  May be blank if the directory server allows anonymous connections, or if
# using direct mode.
#ldap.managerdn=
#ldap.managerpw=

# A filter expression used to search for the user DN that will be used in LDAP authentication.
# {0} will be replaced by the submitted username.
#ldap.searchfilter=(uid={0})

# Context name to search in, relative to the base DN in the LDAP URL.
#ldap.searchbase=

### Role resolution properties

# A search is performed using the search base (ldap.role.searchbase), and filter (ldap.role.filter).  The results of
# the search define the Rhino roles.  The role name is in the specified attribute (ldap.roles.nameattr) and must match
# role definitions in Rhino configuration.  The members of each role are determined by examining the values of the
# member attribute (ldap.role.memberattr) and must contain the DN of the authenticated user.

# Attribute on the group entry which denotes the group name.
#ldap.rolenameattr=cn

# A multi-value attribute on the group entry which contains user DNs or ids of the group members (e.g. uniqueMember,member)
#ldap.rolememberattr=uniqueMember

# The LDAP filter used to search for group entries.
#ldap.rolefilter=(objectclass=groupOfUniqueNames)

# A search base for group entry DNs, relative to the DN that already exists on the LDAP server's URL.
#ldap.rolesearchbase=ou=Groups

# Do case-sensitive search by default. Allowed values are true and false.
#ldap.casesensitive=true

TLS setup for ldaps:// or starttls

For security reasons, always use TLS for LDAP authentication, either via an ldaps:// URL or via ldap.usetls=true. Rhino does not use the JDK’s default CA certificates list, so you must add a TLS certificate that Rhino should trust to Rhino’s rhino-server.keystore. This must be done whether you are using a TLS certificate from a public or private CA, or a self-signed certificate, for your LDAP server, otherwise Rhino will refuse to trust the LDAP server. You may use any of:

  • The CA’s root certificate, which will be the most durable choice as it should continue to work across LDAP server certificate rotations for a number of years.

  • One of the CA’s intermediate certificates, which will be less durable than using the root CA certificate.

  • The LDAP server’s certificate, which is the least durable choice because you will need to replace it in each Rhino keystore file whenever the LDAP server gets a new certificate.

To add an LDAP TLS certificate to rhino-server.keystore, run the following, with $PATH_TO_YOUR_CA_CERT replaced with the correct path to your certificate:

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

SLEE profile login module

The ProfileLoginModule reads login credentials and roles from a SLEE profile table.

To use this module, edit the JAAS configuration file ${RHINO_HOME}/config/rhino.jaas, and add an entry to the jmxr-adaptor declaration:

jmxr-adaptor {
    com.opencloud.rhino.security.auth.ProfileLoginModule SUFFICIENT
        profiletable="UserLoginProfileTable"
        passwordattribute="HashedPassword"
        rolesattribute="Roles"
        hash="SHA3-512";

    /* a "backup" login module would typically go here */
};

ProfileLoginModule supports the following options:

Option Description Default 
 profiletable

name of the profile table to use

 
 UserLoginProfileTable
 
 passwordattribute

profile attribute to compare the password against
profile attribute type must be java.lang.String

 
 HashedPassword
 
 rolesattribute

profile attribute to load the roles from
profile attribute type must be array of java.lang.String

 
 Roles
 
 hash

hashing algorithm to use for the password
use none for clear text passwords, or a valid java.security.MessageDigest secure hash algorithm name (e.g. SHA-1 or 'SHA3-512').

Note If anything other than SHA3-512 is specified, then the environment variable on the UserLoginProfile profile spec must be set to match the algorithm used. 
 SHA3-512

The profile login module:

  • finds the profile in a specified table with a name matching the supplied username

  • compares the supplied password with the password stored in the profile; if authentication succeeds, retrieves the roles for that user from the profile.

Rhino comes with a profile specification that you can use to create a profile table for the profile login module (in $RHINO_HOME/lib/user-login-profile-du.jar). It contains a profile specification called UserLoginProfileSpec. You can install it using the rhino-console:

[Rhino@localhost (#3)] installlocaldu ../../lib/user-login-profile-du.jar
installed: DeployableUnitID[url=file:/tmp/rhino/lib/user-login-profile-du.jar]
[Rhino@localhost (#4)] listprofilespecs
ProfileSpecificationIDname=AddressProfileSpec,vendor=javax.slee,version=1.0
ProfileSpecificationIDname=AddressProfileSpec,vendor=javax.slee,version=1.1
ProfileSpecificationIDname=ResourceInfoProfileSpec,vendor=javax.slee,version=1.0
ProfileSpecificationID[name=UserLoginProfileSpec,vendor=Open Cloud,version=1.0]
Tip A profile table named UserLoginProfileTable created using this specification will work with the default configuration values listed above.

Creating a profile table fallback

OpenCloud recommends configuring a file login module as a fallback mechanism, in case the profile table is accidentally deleted or renamed, or the admin user profile is deleted or changed.

Warning Without a fallback you would not be able to fix the profile table problem, since no user would be able to login using a management client!

To create a profile table fallback, give ProfileLoginModule a SUFFICIENT flag and the FileLoginModule a REQUIRED flag:

jmxr-adaptor {
    com.opencloud.rhino.security.auth.ProfileLoginModule SUFFICIENT
        profiletable="UserLoginProfileTable"
        passwordattribute="HashedPassword"
        rolesattribute="Roles"
        hash="SHA3-512";

    com.opencloud.rhino.security.auth.FileLoginModule REQUIRED
        file="$${rhino.dir.base}/rhino.passwd"
        hash="SHA3-512";
};
Previous page Next page
Rhino Version 3.2