Implementing this interface enables WebSphere Application Server security to use custom registries. This capability should extend the java.rmi file. With a remote registry, you can complete this process remotely.
public void initialize(java.util.Properties props)
throws CustomRegistryException,
RemoteException;
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 bring up to initialize the registry. This method is also called when validation is performed by the administrative console, when security is on. This method remains the same as in version 4.x.
public String checkPassword(String userSecurityName, String password)
throws PasswordCheckFailedException,
CustomRegistryException,
RemoteException;
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 checks the name and password combination in the registry and (if they match) returns the user 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. This method is the same as in version 4.x.
public String mapCertificate(X509Certificate[] cert)
throws CertificateMapNotSupportedException,
CertificateMapFailedException,
CustomRegistryException,
RemoteException;
This method is called when certificates are provided for authentication. For Web applications, when the authentication constraints are set to CLIENT-CERT in the web.xml file of the application, this method is called to map a certificate to a valid user in the registry. For Java clients, this method is called to map the client certificates in the transport layer, when using the transport layer authentication. 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.
In WebSphere Application Server Version 4.x, the input parameter was the X509Certificate. In WebSphere Application Server Version 5.x and later, this parameter changes to accept an array of X509Certificate certificates (such as a certificate chain). In version 4.x, this parameter was called only for Web applications, but in version 5.x and later you can call this method for both Web and Java clients.
public String getRealm()
throws CustomRegistryException,
RemoteException;
For the sample, the getRealm method returns the string, customRealm. One of the calls to this method is when the registry information is validated. This method is the same as in version 4.x.
public Result getUsers(String pattern, int limit)
throws CustomRegistryException,
RemoteException;
The custom registry implementations are expected to support at least the wildcard search (*). For example, a pattern of (*) returns all the users and a pattern of (b*) returns the users starting 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 users returned and the Boolean flag indicates if 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 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 wildcard characters such as the asterisk (*) and question mark (?).
This method is called by the 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.
In WebSphere Application Server Version 4.x, this method specifies to take only the pattern parameter. The return is a list. In WebSphere Application Server Version 5.x or later, this method is changed to take one additional parameter, the limit. Ideally, your implementation should change to take the limit value and limit the users returned. The return is changed to return a result object, which consists of the list (as in version 4) and a flag indicating if more entries exist. So, when the list returns, 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() method. The default for the Boolean attribute in the result object is false.
public String getUserDisplayName(String userSecurityName)
throws EntryNotFoundException,
CustomRegistryException,
RemoteException;
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 using the command line using the wsadmin tool. Use this method only for displaying. This method is the same as in Version 4.0.
public String getUniqueUserId(String userSecurityName)
throws EntryNotFoundException,
CustomRegistryException,
RemoteException;
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 is called to make sure a valid user exists for a given uniqueUserId. This method is called to get the security name of the user when the uniqueUserId is obtained from a token.
public boolean isValidUser(String userSecurityName)
throws CustomRegistryException,
RemoteException;
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 prevents 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 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 groups returned and the Boolean flag indicates 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.
In WebSphere Application Server Version 4, this method is used to take the pattern parameter only and returns a list. In WebSphere Application Server Version 5.x or later, this method is changed to take one additional parameter, the limit. Change to take the limit value and limit the users returned. The return is changed to return a result object, which consists of the list (as in version 4) and a flag indicating whether more entries exist. 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;
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;
In the sample, this method returns the unique ID 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;
In the sample, this method returns the unique ID 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 in which the user belongs 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;
In the sample, this method returns the security name of the group whose unique ID matches the supplied ID. This method verifies that a valid group exists for a given uniqueGroupId.
public boolean isValidGroup(String groupSecurityName)
throws CustomRegistryException,
RemoteException;
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 might prevent problems later.
public List getGroupsForUser(String userSecurityName)
throws EntryNotFoundException,
CustomRegistryException,
RemoteException;
In the sample, this method returns all the group security names that contain the userSecurityName.
This method is called by the administrative console or the scripting tool to verify that the users entered for the RunAs roles are already part of that role in the users and groups to role mapping. This check is required to ensure that a user cannot be added to a RunAs role unless that user is assigned to the role in the users and groups to role mapping either directly or indirectly (through a group that contains this user). Since a group in which the user belongs can be part of the role in the users and groups to role mapping, this method is called to check if any of the groups that this user belongs to mapped to that role.
public Result getUsersForGroup(String groupSecurityName, int limit)
throws NotImplementedException,
EntryNotFoundException,
CustomRegistryException,
RemoteException;
The return parameter is an object of type com.ibm.websphere.security.Result. This object contains two attributes, java.util.List and java.lang.boolean. The list contains the users returned and the Boolean flag, which indicates whether there are more users available in the registry for the search pattern. This Boolean flag indicates to the client whether users are available in the registry.
In the example, this method gets one user more than the requested number of users for a group if the limit parameter is not set to 0. If it succeeds in getting one more user, it sets the Boolean flag to true.
In WebSphere Application Server Version 4, this getUsers method was mandatory for the product. For WebSphere Application Server Version 5.x or later, this method can throw the exception NotImplementedException exception in situations where it is not practical to get the requested set of users. However, this exception should be thrown in rare situations, as other components can be affected. In version 4, this method accepted only the pattern parameter and the returned a list. In version 5, this method accepts one additional parameter, the limit. Change your implementation to take the limit value and limit the users returned. The return changes to return a result object, which consists of the list (as in version 4) and a flag indicating whether more entries exist. When the list is returned, use the Result.setList(List) method 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;
Related tasks
Developing custom user registries
Migrating custom user registries
Related reference
Configuring custom user registries
FileRegistrySample.java file