Implementing this interface enables WebSphere Application Server - Express security to use custom registries. This capability should extend the java.rmi file. With a remote registry, you can complete this process remotely.
To implement this interface, you must provide these methods:
public void initialize(java.util.Properties props) throws CustomRegistryException, RemoteException;
This method is called to initialize the UserRegistry. All the properties defined in the custom user registry panel propagate to this method.
For the sample, the initialize() method retrieves the names of the registry files containing the user and group information.
This method is called during server bringup to initialize the registry. This method is also called when validation is performed by the administrative console when security is on.
public String checkPassword(String userSecurityName, String password) throws PasswordCheckFailedException, CustomRegistryException, RemoteException;
The checkPassword method is called to authenticate users when they log in using a name (or ID) and a password. This method returns a string which, in most cases is the user being authenticated. A credential is then created for the user for authorization purposes. This user name is also returned for the servlet calls getUserPrincipal() and getRemoteUser(). See also the getUserDisplayName method for more information if you have display names in your registry. In some situations if you return a user other than the one who has logged in, ensure that the user is valid in the registry.
For the sample, the mapCertificate method gets the distinguished name (DN) from the certificate chain and makes sure it is a valid user in the registry before returning the user. For the sample, the checkPassword method simply checks the name and password combination in the registry, and if they match, returns the user who is being authenticated.
This method is called for various scenarios. It is called by the administrative console to validate the user information once the registry is initialized. It is also called when you access protected resources in the product for authenticating the user and before proceeding with the authorization.
public String mapCertificate(X509Certificate[] cert) throws CertificateMapNotSupportedException, CertificateMapFailedException, CustomRegistryException, RemoteException;
The mapCertificate method is called to obtain a user name from a X509 certificate chain supplied by the browser. The complete certificate chain is passed to this method and the implementation can validate the chain if needed and get the user information. A credential is created for this user for authorization purposes. If browser certificates are not supported in your configuration you can throw the exception, CertificateMapNotSupportedException. The consequence of not supporting certificates is that the authentication will fail if the challenge type is certificates, even if they have valid certificates in the browser.
This method is called when certificates are provided for authentication. For Web applications, when the auth-constraints are set to CLIENT-CERT in the web.xml of the application, this method is called to map a certificate to a valid user in the registry. Also, when the Identity Assertion Token (when using the CSIv2 authentication protocol) is set to contain certificates, this method is called to map the certificates to a valid user.
The parameter accepts an array of X509Certificate certificates (for example, certificate chain).
public String getRealm() throws CustomRegistryException, RemoteException;
The getRealm method is called to get the name of the security realm. The name of the realm identifies the security domain for which the registry authenticates users. If this method returns a null value, a default name of customRealm is used.
For the sample, the getRealm method returns the string customRealm. One of the calls to this method is when the registry information is validated.
public Result getUsers(String pattern, int limit) throws CustomRegistryException, RemoteException;
The getUsers method returns the list of users from the registry. The names of users depend on the pattern parameter. The number of users are limited by the limit parameter. In a registry that has many users, getting all the users is not practical. So the limit parameter is introduced to limit the number of users retrieved from the registry. A limit of zero (0) indicates to return all the users that match the pattern and can cause problems for large registries. Use this limit with care. The custom registry implementations are expected to support at least the asterisk (*) wildcard search character. For example, a pattern of (*) returns all the users and a pattern of (b*) returns the user names that start with "b."
The return parameter is an object of type com.ibm.websphere.security.Result. 
This object contains two attributes, a java.util.List and a java.lang.boolean. The list should contain the list of users returned and the boolean flag indicates if there are more users available in the registry for the searche pattern. This boolean flag is used to indicate to the client whether more users are available in the registry.
In the sample, the getUsers retrieves the required number of users from the registry and sets them as a list in the Result object. To find out if there are more users than requested the sample gets one more user than requested and if it finds the additional user it sets the boolean flag to true. For pattern matching the match method in the RegExpSample class is used, which supports wildcards characters such as asterisk (*) and question mark (?).
This method is called by administrative console to add users to roles in the various map users to roles panels. The administrative console uses the boolean set in the Result object to indicate that more entries matching the pattern are available in the registry.
This method accepts as parameters the pattern and the limit. A Result object, which consists of the list and a flag indicating if more entries exist, is returned. When the list is returned, use the Result.setList(List) to set the List in the Result object. If there are more entries than requested in the Limit parameter, set the boolean attribute to true in the Result object using Result.setHasMore(). The default for the boolean attribute in the Result object is false.
public String getUserDisplayName(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException;
The getUserDisplayName method returns a display name for a user, if one exists. The display name is an optional string that describes the user that you can set in some registries. This is a descriptive name for the user and need not be unique in the registry. For example in Windows systems, you can display the full name of the user. If you do not need display names in your registry, return null or an empty string for this method.
In the sample, this method returns the display name of the user whose name matches the user name provided. If the display name does not exist this returns an empty string.
This method can be called by the product to present the display names in the administrative console or through the command line using the wsadmin tool. Use this method only for displaying.
public String getUniqueUserId(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException;
This method returns the uniqueId of the user given the security name.
In the sample, this method returns the uniqueId of the user whose name matches the supplied name. This method is called when forming a credential for a user and also when creating the authorization table for the application.
public String getUserSecurityName(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException;
This method returns the security name of a user given the uniqueId. In the sample, this method returns the security name of the user whose uniqueId matches the supplied ID.
This method is called to make sure a valid user exists for a given uniqueUserId. One of the situations this method is called is to get the security name of the user is when the uniqueUserId is obtained from a token.
public boolean isValidUser(String userSecurityName) throws CustomRegistryException, RemoteException;
This method indicates whether the given user is a valid user in the registry.
In the sample, this method returns true if the user is found in the registry, otherwise this method returns false. This method is primarily called in situations where knowing if the user exists in the directory or not would prevent problems later. For example, in the mapCertificate call, once the name is obtained from the certificate if the user is found to be an invalid user in the registry, you can avoid trying to create the credential for the user.
public Result getGroups(String pattern, int limit) throws CustomRegistryException, RemoteException;
The getGroups method returns the list of groups from the registry. The names of groups depend on the pattern parameter. The number of groups is limited by the limit parameter. In a registry that has many groups, getting all the groups is not practical. So the limit parameter is introduced to limit the number of groups retrieved from the registry. A limit of zero (0) indicates to return all the users that match the pattern and can cause problems for large registries. Use this limit with care. The custom registry implementations are expected to support at least the asterisk (*) wildcard search character. For example, a pattern of (*) returns all the users and a pattern of (b*) returns the user names that start with "b."
The return parameter is an object of type com.ibm.websphere.security.Result. This object contains two attributes, a java.util.List and a java.lang.boolean. The list contains the list of groups returned and the boolean flag indicating whether there are more groups available in the registry for the pattern searched. This boolean flag is used to indicate to the client if more groups are available in the registry.
In the sample, the getUsers retrieves the required number of groups from the registry and sets them as a list in the Result object. To find out if there are more groups than requested, the sample gets one more user than requested and if it finds the additional user, it sets the boolean flag to true. For pattern matching, the match method in the RegExpSample class is used. It supports wildcards like *, ?.
This method is called by the administrative console to add groups to roles in the various map groups to roles panels. The administrative console will use the boolean set in the Result object to indicate that more entries matching the pattern are available in the registry.
This method accepts as parameters the pattern and the limit. A Result object, which consists of the list and a flag indicating if more entries exist, is returned. When the list is returned, use the Result.setList(List) to set the List in the Result object. If there are more entries than requested in the Limit parameter, set the boolean attribute to true in the Result object using Result.setHasMore(). The default for the boolean attribute in the Result object is false.
public String getGroupDisplayName(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException;
The getGroupDisplayName method returns a display name for a group if one exists. The display name is an optional string describing the group that you can set in some registries. This name is a descriptive name for the group and need not be unique in the registry. If you do not need to have display names for groups in your registry return null or an empty string for this method.
In the sample, this method returns the display name of the group whose name matches the group name provided. If the display name does not exist this method returns an empty string.
The product can call this method to present the display names in the administrative console or through command line using the wsadmin tool. This method is only used for displaying.
public String getUniqueGroupId(String groupSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException;
This method returns the uniqueId of the group given the security name.
In the sample, this method returns the uniqueId of the group whose name matches the supplied name. This method is called when creating the authorization table for the application.
public List getUniqueGroupIds(String uniqueUserId) throws EntryNotFoundException, CustomRegistryException, RemoteException;
This method returns the uniqueIds of all the groups to which a user whose uniqueId matches the supplied Id belongs.
In the sample, this method returns the uniqueId of all the groups that contain this uniqueUserId. This method is called when creating the credential for the user. As part of creating the credential, all the groupUniqueIds that this user is apart of are collected and put in the credential for authorization purposes when groups are given access to a resource.
public String getGroupSecurityName(String uniqueGroupId) throws EntryNotFoundException, CustomRegistryException, RemoteException;
This method returns the security name of a group given its uniqueId.
In the sample, this method returns the security name of the group whose uniqueId matches the supplied Id. This method is called to make sure a valid group exists for a given uniqueGroupId.
public boolean isValidGroup(String groupSecurityName) throws CustomRegistryException, RemoteException;
This method indicates if the given group is a valid group in the registry.
In the sample, this method returns true if the group is found in the registry, otherwise the method returns false. This method can be used in situations where knowing whether the group exists in the directory would help prevent problems later.
public List getGroupsForUser(String userSecurityName) throws EntryNotFoundException, CustomRegistryException, RemoteException;
This method returns all the groups to which a user whose name matches the supplied name belongs. This method is similar to the getUniqueGroupIds method with the except that the securityNames are used, instead of the uniqueIds.
In the sample, this method returns all the group securityNames that contain the userSecurityName.
public Result getUsersForGroup(String groupSecurityName, int limit) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException;
This method retrieves users from the specified group. The number of users returned is limited by the limit parameter. A limit of 0 indicates to return all the users in that group. This method is not directly called by the WebSphere Security component. However, this can be called by other components, such as some product clients like Workflow. In rare situations, if you are working with a registry where getting all the users from any of your groups is not practical (for example if there are a large number of users), you can throw the NotImplementedException for the particular group or groups. If there is no concern about returning the users from groups in the registry, it is recommended that you do not throw the NotImplemented exception when implementing this method.
The return parameter is an object of type com.ibm.websphere.security.Result. This object contains two attributes, a java.util.List and a java.lang.boolean. The list contains the list of users returned and the boolean flag indicates whether there are more users available in the registry for the search pattern. This boolean flag is used to indicate to the client whether more users are available in the registry.
In the example, this method gets one more user than requested if the limit parameter is not set to 0. If it succeeds in getting one more user it sets the boolean flag to true.
This method is optional and can throw the NotImplementedException if you choose not to implement it. This method accepts two parameters, the pattern and the limit. A Result object, which consists of the list and a flag indicating whether more entries exist, is returned. When the list is returned use the Result.setList(List) to set the list in the Result object. If there are more entries than requested in the limit parameter, set the boolean attribute to true in the Result object using Result.setHasMore(). The default for the boolean attribute in the Result object is false.
public com.ibm.websphere.security.cred.WSCredential createCredential(String userSecurityName) throws NotImplementedException, EntryNotFoundException, CustomRegistryException, RemoteException;
In this release of the WebSphere Application Server - Express, this method is not called. You should, instead, return null. In the example, a null is returned. This method did not exist in Version 4.0.