com.sun.enterprise.security.auth.realm.file

Class FileRealm

java.lang.Object

com.sun.enterprise.security.auth.realm.AbstractRealm

com.sun.enterprise.security.auth.realm.AbstractStatefulRealm

com.sun.enterprise.security.auth.realm.Realm

com.sun.enterprise.security.BaseRealm

com.sun.enterprise.security.auth.realm.file.FileRealm

All Implemented Interfaces:

Comparable<Realm>

@Service
public final class FileRealm
extends BaseRealm

Realm wrapper for supporting file password authentication.

In addition to the basic realm functionality, this class provides administration methods for the file realm.

Format of the keyfile used by this class is one line per user containing username;password;groups where:

• username - Name string.
• password - A salted SHA hash (SSHA) of the user password.
• groups - A comma separated list of group memberships.

The file realm needs the following properties in its configuration:

• file - Full path to the keyfile to load
• jaas-ctx - JAAS context name used to access LoginModule for authentication.

Author:

Harry Singh, Jyri Virkki, Shing Wai Chan

Field Summary

Fields

Modifier and Type	Field and Description
static String	AUTH_TYPE Descriptive string of the authentication type of this realm.
static String	PARAM_KEYFILE These are property names which should be in auth-realm in server.xml

Fields inherited from class com.sun.enterprise.security.BaseRealm

sm

Fields inherited from class com.sun.enterprise.security.auth.realm.Realm

_logger, JAAS_CONTEXT_PARAM, RI_DEFAULT

Fields inherited from class com.sun.enterprise.security.auth.realm.AbstractStatefulRealm

groupMapper, GROUPS_SEP, PARAM_DEFAULT_DIGEST_ALGORITHM, PARAM_GROUP_MAPPING, PARAM_GROUPS

Constructor Summary

Constructors

Constructor and Description
FileRealm() No arg constructor used by the Realm class when creating realms.
FileRealm(String keyfile) Constructor.

Method Summary

Modifier and Type	Method and Description
void	addUser(String name, char[] password, String[] groupList) Adds new user to file realm.
String[]	authenticate(String user, char[] password) Authenticates a user.
String	getAuthType() Returns a short (preferably less than fifteen characters) description of the kind of authentication which is supported by this realm.
Enumeration<String>	getGroupNames() Returns names of all the groups in this particular realm.
Enumeration<String>	getGroupNames(String username) Returns the name of all the groups that this user belongs to.
static List<String>	getRealmFileNames(Config config) Return a list of the file names used by all file realms defined for the specified config.
User	getUser(String name) Returns the information recorded about a particular named user.
Enumeration<String>	getUserNames() Returns names of all the users in this particular realm.
boolean	hasAuthenticatableUser() Test whether their is a user in the FileRealm that has a password that has been set, i.e., something other than the resetKey.
protected void	init(Properties props) Initialize a realm with some properties.
void	persist() Persist the realm data to permanent storage
void	refresh() Refreshes the realm data so that new users/groups are visible.
void	refresh(String configName) Refreshes the realm data so that new users/groups are visible.
void	removeUser(String name) Remove user from file realm.
boolean	supportsUserManagement()
void	updateUser(String name, String newName, char[] password, String[] groups) Update data for an existing user.

Methods inherited from class com.sun.enterprise.security.BaseRealm

addUser, updateUser

Methods inherited from class com.sun.enterprise.security.auth.realm.Realm

getDefaultInstance, getDefaultRealm, getInstance, getInstance, getRealmNames, getRealmStatsProvier, instantiate, instantiate, isValidRealm, isValidRealm, setDefaultRealm, unloadInstance, unloadInstance, updateInstance, updateInstance

Methods inherited from class com.sun.enterprise.security.auth.realm.AbstractStatefulRealm

addAssignGroups, compareTo, getDefaultDigestAlgorithm, getJAASContext, getMappedGroupNames, getName, getProperties, getProperty, setName, setProperty, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Comparable

compareTo

Field Detail

AUTH_TYPE

public static final String AUTH_TYPE

Descriptive string of the authentication type of this realm.

See Also:

Constant Field Values

PARAM_KEYFILE

public static final String PARAM_KEYFILE

These are property names which should be in auth-realm in server.xml

See Also:

Constant Field Values

Constructor Detail

FileRealm

public FileRealm(String keyfile)
          throws BadRealmException,
                 NoSuchRealmException

Constructor.

The created FileRealm instance is not registered in the Realm registry. This constructor can be used by admin tools to create a FileRealm instance which can be edited by adding or removing users and then saved to disk, without affecting the installed realm instance.

The file provided should always exist. A default (empty) keyfile is installed with the server so this should always be the case unless the user has manually deleted this file. If this file path provided does not point to an existing file this constructor will first attempt to create it. If this succeeds the constructor returns normally and an empty keyfile will have been created; otherwise an exception is thrown.

Parameters:

keyfile - Full path to the keyfile to read for user data.

Throws:

BadRealmException - If the configuration parameters identify a corrupt realm.

NoSuchRealmException - If the configuration parameters specify a realm which doesn't exist.

FileRealm

public FileRealm()

No arg constructor used by the Realm class when creating realms. This is followed by a call to the init() method.

Method Detail

getAuthType

public String getAuthType()

Returns a short (preferably less than fifteen characters) description of the kind of authentication which is supported by this realm.

Specified by:

getAuthType in class AbstractRealm

Returns:

Description of the kind of authentication that is directly supported by this realm.

init

protected void init(Properties props)
             throws BadRealmException,
                    NoSuchRealmException

Initialize a realm with some properties. This can be used when instantiating realms from their descriptions. This method is invoked from Realm during initialization.

Overrides:

init in class AbstractStatefulRealm

Parameters:

props - Initialization parameters used by this realm.

Throws:

BadRealmException - If the configuration parameters identify a corrupt realm.

NoSuchRealmException - If the configuration parameters specify a realm which doesn't exist.

authenticate

public String[] authenticate(String user,
                             char[] password)

Authenticates a user.

This method is invoked by the FileLoginModule in order to authenticate a user in the file realm. The authentication decision is kept within the realm class implementation in order to keep the password cache in a single location with no public accessors, to simplify future improvements.

Parameters:

user - Name of user to authenticate.

password - Password provided by client.

Returns:

Array of group names the user belongs to, or null if authentication fails.

getRealmFileNames

public static List<String> getRealmFileNames(Config config)

Return a list of the file names used by all file realms defined for the specified config.

Parameters:

config - the config object

Returns:

a list of the file names for all files realms in the config

getUserNames

public Enumeration<String> getUserNames()
                                 throws BadRealmException

Returns names of all the users in this particular realm.

Overrides:

getUserNames in class BaseRealm

Returns:

enumeration of user names (strings)

Throws:

BadRealmException - if realm data structures are bad

getUser

public User getUser(String name)
             throws NoSuchUserException

Returns the information recorded about a particular named user.

Overrides:

getUser in class BaseRealm

Parameters:

name - Name of the user whose information is desired.

Returns:

The user object.

Throws:

NoSuchUserException - if the user doesn't exist.

getGroupNames

public Enumeration<String> getGroupNames()
                                  throws BadRealmException

Returns names of all the groups in this particular realm. Note that this will not return assign-groups.

Overrides:

getGroupNames in class BaseRealm

Returns:

enumeration of group names (strings)

Throws:

BadRealmException - if realm data structures are bad

getGroupNames

public Enumeration<String> getGroupNames(String username)
                                  throws NoSuchUserException

Returns the name of all the groups that this user belongs to.

Specified by:

getGroupNames in class AbstractRealm

Parameters:

username - Name of the user in this realm whose group listing is needed.

Returns:

Enumeration of group names (strings).

Throws:

NoSuchUserException - thrown if the realm does not support this operation - e.g. Certificate realm does not support this operation.

refresh

public void refresh()
             throws BadRealmException

Refreshes the realm data so that new users/groups are visible.

A new FileRealm instance is created and initialized from the keyfile on disk. The new instance is installed in the Realm registry so future Realm.getInstance() calls will obtain the new data. Any existing references to this instance (e.g. in active LoginModule sessions) are unaffected.

Overrides:

refresh in class BaseRealm

Throws:

BadRealmException - if realm data structures are bad

refresh

public void refresh(String configName)
             throws BadRealmException

Refreshes the realm data so that new users/groups are visible.

A new FileRealm instance is created and initialized from the keyfile on disk. The new instance is installed in the Realm registry so future Realm.getInstance() calls will obtain the new data. Any existing references to this instance (e.g. in active LoginModule sessions) are unaffected.

Overrides:

refresh in class AbstractStatefulRealm

Parameters:

config -

Throws:

BadRealmException - if realm data structures are bad

addUser

public void addUser(String name,
                    char[] password,
                    String[] groupList)

Adds new user to file realm. User cannot exist already.

Overrides:

addUser in class BaseRealm

Parameters:

name - User name.

password - Cleartext password for the user.

groupList - List of groups to which user belongs.

removeUser

public void removeUser(String name)

Remove user from file realm. User must exist.

Overrides:

removeUser in class BaseRealm

Parameters:

name - User name.

updateUser

public void updateUser(String name,
                       String newName,
                       char[] password,
                       String[] groups)

Update data for an existing user. User must exist.

Overrides:

updateUser in class BaseRealm

Parameters:

name - Current name of the user to update.

newName - New name to give this user. It can be the same as the original name. Otherwise it must be a new user name which does not already exist as a user.

password - Cleartext password for the user. If non-null the user password is changed to this value. If null, the original password is retained.

groups - List of groups to which user belongs.

persist

public void persist()
             throws BadRealmException

Persist the realm data to permanent storage

Overrides:

persist in class BaseRealm

Throws:

BadRealmException

hasAuthenticatableUser

public boolean hasAuthenticatableUser()

Test whether their is a user in the FileRealm that has a password that has been set, i.e., something other than the resetKey.

supportsUserManagement

public boolean supportsUserManagement()

Overrides:

supportsUserManagement in class BaseRealm

Returns:

true if the realm implementation support User Management (add,remove,update user)