The UserRegistry interface

Custom User Registry

WebSphere can be configured to use a type of user registry other than Local OS or LDAP. This registry is referred to as a Custom Registry. The custom registry feature supports any user registry that is not implemented by WebSphere Application Server. We can use any user registry by implementing the UserRegistry interface.
2.4.1 The UserRegistry interface

The UserRegistry interface is very helpful in situations, for example, where the current user and group information exists in some other format (for example, a database) and cannot be moved to Local OS or LDAP. In such a case, implement the UserRegistry interface so that WebSphere Application Server can use the existing registry for all of the security-related operations. Using a custom registry is a software implementation effort; it is expected that the implementation does not depend on other WebSphere Application Server resources, for example, data sources, for its operation.
To implement the UserRegistry interface it will be necessary to provide a Java class that provides WebSphere with a standard interface in order for WebSphere to communicate with the registry in an appropriate fashion. The provision of this interface ensures that a variety of user registries may be used, such as relational databases, files stored on directly on the file system. A combination of multiple registries may be used, such as LDAP and RACF.
The UserRegistry interface defines a general set of methods to allow the application server to obtain user and group information from the registry, the interface is also implemented by the two other available user registries in WebSphere Application Server V6, LDAP and Local OS. The registry can operate as a process running remotely to the application server and thus it is necessary for each registry to implement the java.rmi.Remote interface.
There is one point worth noting in regard to the initialization of a WebSphere Application Server V6 custom registry. With V4, it was possible to use other WebSphere Application Server components to initialize the custom registry. For example, a data source might have been used to connect to a database-based custom registry or one may have made use of a deployed EJB. However, since V5, neither of these examples is possible because, unlike in V4, the security mechanism is initialized before other components such as containers, and therefore, these facilities are not available when the security component is started. Therefore any implementation of the custom registry should not depend on any WebSphere Application Server component such as data sources, enterprise beans, and so on.
The methods in the UserRegistry interface operate on the following information for users:

userSecurityName User name used to log on when prompted by an application.
uniqueUserId Unique identifier for the user; it is equivalent to the uid in UNIX or the dn in LDAP.
userDisplayName Optional string that describes a user.
groupSecurityName Security group.
groupUniqueId Unique identifier for the group.
groupDisplayName Optional string that describes a group.

The list below includes all the methods defined in the UserRegistry interface. Each method must be implemented by the custom registry.

Method signature Use
void initialize(java.util.Properties props) throws CustomRegistryException, RemoteException Initializes the registry. This method is called when creating the registry.
String checkPassword(String userSecurityName, String password) throws PasswordCheckFailedException, CustomRegistryException, RemoteException Checks the password of the user. This method is called to authenticate a user when the user's name and password are given.
String mapCertificate(X509Certificate[] cert) throws CertificateMapNotSupportedException, CertificateMapFailedException, CustomRegistryException, RemoteException Maps a Certificate (of X509 format) to a valid user in the Registry. This is used to map the name in the certificate supplied by a browser to a valid userSecurityName in the registry.
String getRealm() throws CustomRegistryException, RemoteException The realm is a registry-specific string indicating the realm or domain for which this registry applies. For example, for OS400 or AIX this would be the host name of the system whose user registry this object represents. If null is returned by this method realm defaults to the value of "customRealm".
Result getUsers(String pattern, int limit) throws CustomRegistryException, RemoteException Gets a list of users that match a pattern in the registry. The maximum number of users returned is defined by the limit argument.
String getUserDisplayName(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException Returns the display name for the user specified by userSecurityName.
String getUniqueUserId(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException Returns the UniqueId for a userSecurityName. This method is called when creating a credential for a user.
String getUserSecurityName(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException Returns the name for a user given its uniqueId.
boolean isValidUser(String userSecurityName) throws CustomRegistryException, RemoteException Determines if the userSecurityName exists in the registry.
Result getGroups(String pattern, int limit) throws CustomRegistryException, RemoteException Gets a list of groups that match a pattern in the registry. The maximum number of groups returned is defined by the limit argument.
String getGroupDisplayName(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException Returns the display name for the group specified by groupSecurityName.
String getUniqueGroupId(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException Returns the Unique id for a group.
List getUniqueGroupIds(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException Returns the UniqueIds for all the groups that contain the UniqueId of a user. Called during creation of a user's credential.
String getGroupSecurityName(String uniqueGroupId) throws EntryNotFoundException, CustomRegistryException, RemoteException Returns the name for a group given its uniqueId.
boolean isValidGroup(String groupSecurityName) throws CustomRegistryException, RemoteException Determines if the groupSecurityName exists in the registry.
Result getUsersForGroup(String groupSecurityName, int limit) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException Gets a list of users in a group. The maximum number of users returned is defined by the limit argument.
public List getGroupsForUser(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException Gets all the groups the given user is a member of.
Credential createCredential(String userSecurityName) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException Throws the NotImplementedException for this method.

userSecurityName	User name used to log on when prompted by an application.
uniqueUserId	Unique identifier for the user; it is equivalent to the uid in UNIX or the dn in LDAP.
userDisplayName	Optional string that describes a user.
groupSecurityName	Security group.
groupUniqueId	Unique identifier for the group.
groupDisplayName	Optional string that describes a group.

Method signature	Use
void initialize(java.util.Properties props) throws CustomRegistryException, RemoteException	Initializes the registry. This method is called when creating the registry.
String checkPassword(String userSecurityName, String password) throws PasswordCheckFailedException, CustomRegistryException, RemoteException	Checks the password of the user. This method is called to authenticate a user when the user's name and password are given.
String mapCertificate(X509Certificate[] cert) throws CertificateMapNotSupportedException, CertificateMapFailedException, CustomRegistryException, RemoteException	Maps a Certificate (of X509 format) to a valid user in the Registry. This is used to map the name in the certificate supplied by a browser to a valid userSecurityName in the registry.
String getRealm() throws CustomRegistryException, RemoteException	The realm is a registry-specific string indicating the realm or domain for which this registry applies. For example, for OS400 or AIX this would be the host name of the system whose user registry this object represents. If null is returned by this method realm defaults to the value of "customRealm".
Result getUsers(String pattern, int limit) throws CustomRegistryException, RemoteException	Gets a list of users that match a pattern in the registry. The maximum number of users returned is defined by the limit argument.
String getUserDisplayName(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException	Returns the display name for the user specified by userSecurityName.
String getUniqueUserId(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException	Returns the UniqueId for a userSecurityName. This method is called when creating a credential for a user.
String getUserSecurityName(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException	Returns the name for a user given its uniqueId.
boolean isValidUser(String userSecurityName) throws CustomRegistryException, RemoteException	Determines if the userSecurityName exists in the registry.
Result getGroups(String pattern, int limit) throws CustomRegistryException, RemoteException	Gets a list of groups that match a pattern in the registry. The maximum number of groups returned is defined by the limit argument.
String getGroupDisplayName(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException	Returns the display name for the group specified by groupSecurityName.
String getUniqueGroupId(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException	Returns the Unique id for a group.
List getUniqueGroupIds(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException	Returns the UniqueIds for all the groups that contain the UniqueId of a user. Called during creation of a user's credential.
String getGroupSecurityName(String uniqueGroupId) throws EntryNotFoundException, CustomRegistryException, RemoteException	Returns the name for a group given its uniqueId.
boolean isValidGroup(String groupSecurityName) throws CustomRegistryException, RemoteException	Determines if the groupSecurityName exists in the registry.
Result getUsersForGroup(String groupSecurityName, int limit) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException	Gets a list of users in a group. The maximum number of users returned is defined by the limit argument.
public List getGroupsForUser(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException	Gets all the groups the given user is a member of.
Credential createCredential(String userSecurityName) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException	Throws the NotImplementedException for this method.