Rhino 2.5.0 :: Rhino Administration and Deployment Guide

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

On this page...

JAAS configuration
File login module
LDAP login module
SLEE profile login module

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="md5";
};

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.

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 algorithm name (e.g. md5 or sha-1). If not specified, clear text passwords are 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.

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:

Configure the file login module, changing the hash="none" option to hash="md5".
Use the client/bin/rhino-passwd utility to generate hashed passwords.
Copy those hashed passwords into the password file.

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=false

# 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

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="md5";

    /* 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 algorithm name (e.g. md5 or sha-1).

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

md5

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]

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.

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="md5";

    com.opencloud.rhino.security.auth.FileLoginModule REQUIRED
        file="$${rhino.dir.base}/rhino.passwd"
        hash="md5";
};

Previous page Next page

Authentication

JAAS configuration

File login module

LDAP login module

SLEE profile login module

Creating a profile table fallback