Package org.glassfish.security.common

Class FileRealmStorageManager

java.lang.Object

org.glassfish.security.common.FileRealmStorageManager

public final class FileRealmStorageManager
extends Object

A class for performing CRUD operations on a file storage for storing users, passwords and groups.

This class provides administration methods for the file realm. It is used by the FileRealm class to provide the FileRealm functionality. But some administration classes that need direct access to the File without using the security module use this class directly.

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 or "RESET"
• groups - A comma separated list of group memberships.

If the password is "RESET", then the password must be reset before that user can authenticate.

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:

Tom Mueller

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	FileRealmStorageManager.User	Represents a FileRealm user.

Field Summary

Fields

Modifier and Type	Field	Description
static String	MISC_VALID_CHARS
static String	PARAM_KEYFILE

Constructor Summary

Constructors

Constructor	Description
FileRealmStorageManager(String keyfileName)	Constructor.

Method Summary

Modifier and Type	Method	Description
void	addUser(String username, char[] password, String[] groupList)	Adds new user to file realm.
String[]	authenticate(String username, char[] password)	Authenticates a user.
Set<String>	getGroupNames()	Returns names of all the groups in this particular realm.
String[]	getGroupNames(String username)	Returns the name of all the groups that this user belongs to.
FileRealmStorageManager.User	getUser(String name)	Returns the information recorded about a particular named user.
Set<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.
void	persist()	Write keyfile data out to disk.
void	removeUser(String username)	Remove user from file realm.
void	updateUser(String username, String newUsername, char[] password, String[] groups)	Update data for an existing user.
static void	validateGroupList(String[] groupNames)	Validates syntax of a list of group names.
static void	validateGroupName(String group)	Validates syntax of a group name.
static void	validatePassword(char[] password)	Validates syntax of a password.
static void	validateUserName(String name)	Validates syntax of a user name.

Methods inherited from class java.lang.Object

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

Field Detail

PARAM_KEYFILE

public static final String PARAM_KEYFILE

See Also:

Constant Field Values

MISC_VALID_CHARS

public static final String MISC_VALID_CHARS

See Also:

Constant Field Values

Constructor Detail

FileRealmStorageManager

public FileRealmStorageManager(String keyfileName)
                        throws IOException

Constructor.

The created FileRealmStorageManager instance is not registered in the Realm registry. This constructor can be used by admin tools to create a FileRealmStorageManager 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:

IOException - If the configuration parameters identify a corrupt keyfile

Method Detail

getUser

public FileRealmStorageManager.User getUser(String name)

Returns the information recorded about a particular named user.

Parameters:

name - Name of the user whose information is desired.

Returns:

The user object, or null if the user doesn't exist.

getUserNames

public Set<String> getUserNames()

Returns names of all the users in this particular realm.

Returns:

enumeration of user names (strings)

getGroupNames

public Set<String> getGroupNames()

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

Returns:

enumeration of group names (strings)

getGroupNames

public String[] getGroupNames(String username)

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

Parameters:

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

Returns:

Array of group names (strings) or null if the user does not exist.

authenticate

public String[] authenticate(String username,
                             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:

username - Name of user to authenticate.

password - Password provided by client.

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.

addUser

public void addUser(String username,
                    char[] password,
                    String[] groupList)
             throws IllegalArgumentException

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

Parameters:

username - User name.

password - Cleartext password for the user.

groupList - List of groups to which user belongs.

Throws:

IllegalArgumentException - If there are problems adding user.

removeUser

public void removeUser(String username)
                throws IllegalArgumentException

Remove user from file realm. User must exist.

Parameters:

username - User name.

Throws:

IllegalArgumentException - If user does not exist.

updateUser

public void updateUser(String username,
                       String newUsername,
                       char[] password,
                       String[] groups)
                throws IllegalArgumentException

Update data for an existing user. User must exist.

Parameters:

username - Current name of the user to update.

newUsername - 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.

groupList - List of groups to which user belongs.

Throws:

IllegalArgumentException - If there are problems adding user.

persist

public void persist()
             throws IOException

Write keyfile data out to disk. The file generation is synchronized within this class only, caller is responsible for any other file locking or revision management as deemed necessary.

Throws:

IOException - if there is a failure

validateUserName

public static void validateUserName(String name)
                             throws IllegalArgumentException

Validates syntax of a user name.

This method throws an exception if the provided value is not valid. The message of the exception provides a reason why it is not valid. This is used internally by add/modify User to validate the client-provided values. It is not necessary for the client to call these methods first. However, these are provided as public methods for convenience in case some client (e.g. GUI client) wants to provide independent field validation prior to calling add/modify user.

Parameters:

name - User name to validate.

Throws:

IllegalArgumentException - Thrown if the value is not valid.

validatePassword

public static void validatePassword(char[] password)
                             throws IllegalArgumentException

Validates syntax of a password.

This method throws an exception if the provided value is not valid. The message of the exception provides a reason why it is not valid. This is used internally by add/modify User to validate the client-provided values. It is not necessary for the client to call these methods first. However, these are provided as public methods for convenience in case some client (e.g. GUI client) wants to provide independent field validation prior to calling add/modify user.

Parameters:

password - Password to validate.

Throws:

IllegalArgumentException - Thrown if the value is not valid.

validateGroupName

public static void validateGroupName(String group)
                              throws IllegalArgumentException

Validates syntax of a group name.

This method throws an exception if the provided value is not valid. The message of the exception provides a reason why it is not valid. This is used internally by add/modify User to validate the client-provided values. It is not necessary for the client to call these methods first. However, these are provided as public methods for convenience in case some client (e.g. GUI client) wants to provide independent field validation prior to calling add/modify user.

Parameters:

group - Group name to validate.

Throws:

IllegalArgumentException - Thrown if the value is not valid.

validateGroupList

public static void validateGroupList(String[] groupNames)
                              throws IllegalArgumentException

Validates syntax of a list of group names.

This is equivalent to calling validateGroupName on every element of the groupList.

Parameters:

groupNames - Array of group names to validate.

Throws:

IASSecurityException - Thrown if the value is not valid.

IllegalArgumentException