Developing the UserRegistry interface for using custom registries

Implementing this interface enables WebSphere® Application Server security to use custom registries. This capability extends the java.rmi file. With a remote registry, you can complete this process remotely.

About this task

Provide implementations of the following methods.

Procedure

Initialize the UserRegistry method, with initialize(java.util.Properties).
```
public void initialize(java.util.Properties props)
       throws CustomRegistryException, 
              RemoteException;
```
This method is called to initialize the UserRegistry method. All the properties that are defined in the Custom User Registry panel propagate to this method.
For the FileRegistrySample.java sample file, the initialize method retrieves the names of the registry files that contain 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. This method remains the same as in Version 4.x.
Authenticate users with checkPassword(String,String).
```
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 user ID and a password. This method returns a string which, in most cases, is the user security name. A credential is created for the user for authorization purposes. This user name is also returned for the getCallerPrincipal enterprise bean call and the servlet calls the getUserPrincipal and getRemoteUser methods. See 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 is logged in, you must verify that the user is valid in the registry.
For the FileRegistrySample.java sample file, 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 user registry and, if they match, the method returns the user being authenticated.

This method is called for various scenarios, for example, by the administrative console to validate the user information after the user registry is initialized. This method 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.
Obtain user names from X.509 certificates with mapCertificate(X509Certificate[]).
```
public String mapCertificate(X509Certificate[] cert)
          throws CertificateMapNotSupportedException,              
                 CertificateMapFailedException,              
                 CustomRegistryException,
                 RemoteException;
```
The mapCertificate method is called to obtain a user name from an X.509 certificate chain that is 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 create the CertificateMapNotSupportedException exception. The consequence of not supporting certificates is authentication failure if the challenge type is certificates, even if valid certificates are in the browser.
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 transport layer authentication. When the identity assertion token, 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 is the X509Certificate certificate. 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 is called for web applications only, but in version 5.x and later, you can call this method for both web and Java clients.
Obtain the security realm name with getRealm.
```
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 customRealm default name is used.
For the FileRegistrySample.java sample file, the getRealm method returns the customRealm string. One of the calls to this method occurs when the user registry information is validated. This method is the same method as in Version 4.x.
Obtain the list of users from the registry with getUsers(String,int).
```
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.
The custom registry implementations are expected to support at least the wildcard search (*). For example, a pattern of asterisk (*) returns all the users and a pattern of (b*) returns the users starting with b.

The return parameter is an object with a com.ibm.websphere.security.Result type. This object contains two attributes, a java.util.List and a java.lang.boolean attribute. The list contains the users that are returned and the Boolean flag indicates if more users are available in the user 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 FileRegistrySample.java sample file, the getUsers method retrieves the required number of users from the user registry and sets them as a list in the Result object. To find out if more users are presented 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 the 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 user 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 changes to take the limit value and limits the users that are returned. The return is changed to return a Result object, which consists of the list and a flag that indicates if more entries exist. When the list returns, use the Result.setList(List) method to set the list in the Result object. If more entries exist than requested in the limit parameter, set the Boolean attribute to true in the result object, using the Result.setHasMore method. The default for the Boolean attribute in the result object is false.
Obtain the display name of a user with getUserDisplayName(String).
```
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 descriptive name is for the user and does not have to be unique in the registry.
For example, in IBM® i systems, you can display the text description for the user profile.

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.

If display names existed for any user in WebSphere Application Server Version 4.x, these names were useful for the Enterprise JavaBeans (EJB) method call getCallerPrincipal and the servlet calls getUserPrincipal and getRemoteUser. If the display names are not the same as the security name for any user, the display names are returned for the previously mentioned enterprise beans and servlet methods. Returning display names for these methods might become problematic in some situations because the display names might not be unique in the user registry. Avoid this problem by changing the default behavior to return the user security name instead of the user display name in this version of the product. For more information on how to set properties for the custom registry, see the section on Setting Properties for Custom Registries.

In the FileRegistrySample.java sample file, this method returns the display name of the user whose name matches the user name that is provided. If the display name does not exist, this method returns an empty string.

This method can be called by the product to present the display names in the administrative console, or by using the command line and the wsadmin tool. Use this method for display purposes only. This method is the same as in Version 4.x.
Obtain the unique ID of a user with getUniqueUserId(String).
```
public String getUniqueUserId(String userSecurityName)       
        throws EntryNotFoundException,
               CustomRegistryException,
               RemoteException;
```
This method returns the unique ID of the user, given the security name.
In the FileRegistrySample.java sample file, this method returns the uniqueUserId value 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.
Obtain the security name of a user with getUserSecurityName(String).
```
public String getUserSecurityName(String uniqueUserId)       
       throws EntryNotFoundException,
              CustomRegistryException,
              RemoteException;
```
This method returns the security name of a user given the unique ID. In the FileRegistrySample.java sample file, this method returns the security name of the user whose unique ID matches the supplied ID.
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.
Check whether a given user is a valid user in the registry with isValidUser(String).
```
public boolean isValidUser(String userSecurityName)       
        throws CustomRegistryException,
               RemoteException;
```
This method indicates whether the given user is a valid user in the registry.
In the FileRegistrySample.java sample file, 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, when the name is obtained from the certificate if the user is not found as a valid user in the user registry, you can avoid trying to create the credential for the user.
Return the list of groups from the user registry with getGroups(String,int).
```
public Result getGroups(String pattern, int limit)       
      throws CustomRegistryException,
             RemoteException;
```
The getGroups method returns the list of groups from the user 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 user registry. The custom registry implementations are expected to support at least the wildcard search (*). For example, a pattern of asterisk (*) returns all the users and a pattern of (b*) returns the users starting with b.
The return parameter is an object of the com.ibm.websphere.security.Result type. This object contains the java.util.List and java.lang.boolean attributes. The list contains the groups that are returned and the Boolean flag indicates whether more groups are available in the user 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 FileRegistrySample.java sample file, the getUsers method retrieves the required number of groups from the user registry and sets them as a list in the Result object. To find out if more groups are presented 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 the asterisk (*) and question mark (?) characters.

This method is called by the administrative console to add groups to roles in the various map-groups-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 user 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 the limit parameter. Change to take the limit value and limit the users that are returned. The return is changed to return a Result object, which consists of the list and a flag that indicates whether more entries exist. Use the Result.setList(List) method to set the list in the Result object. If more entries exist than requested in the limit parameter, set the Boolean attribute to true in the Result object using the Result.setHasMore method. The default for the Boolean attribute in the Result object is false.
Obtain the display name of a group with getGroupDisplayName(String).
```
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 that describes the group that you can set in some user registries. This name is a descriptive name for the group and does not have to 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 FileRegistrySample.java sample file, this method returns the display name of the group whose name matches the group name that is 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 the command line using the wsadmin tool. This method is used for display purposes only.
Obtain the unique ID of a group with getUniqueGroupId(String).
```
public String getUniqueGroupId(String groupSecurityName)
         throws EntryNotFoundException,
                CustomRegistryException,
                RemoteException;
```
This method returns the unique ID of the group that is given the security name.
In the FileRegistrySample.java sample file, 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 ID.
Obtain the unique IDs of all groups to which a user belongs with getUniqueGroupIds(String).
```
public List getUniqueGroupIds(String uniqueUserId)
      throws EntryNotFoundException,
             CustomRegistryException,
             RemoteException;
```
This method returns the unique IDs of all the groups to which a user belongs.
In the FileRegistrySample.java sample file, this method returns the unique ID of all the groups that contain this uniqueUserID ID. This method is called when creating the credential for the user. As part of creating the credential, all the groupUniqueIds IDs in which the user belongs are collected and put in the credential for authorization purposes when groups are given access to a resource.
Obtain the security name of a group with getGroupSecurityName(String).
```
public String getGroupSecurityName(String uniqueGroupId)
				 throws EntryNotFoundException,
           CustomRegistryException,
           RemoteException;
```
This method returns the security name of a group given its unique ID.
In the FileRegistrySample.java sample file, 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 ID.
Determine whether a group is a valid group in the registry with isValidGroup(String).
```
public boolean isValidGroup(String groupSecurityName)       
       throws CustomRegistryException,
              RemoteException;
```
This method indicates if the given group is a valid group in the registry.
In the FileRegistrySample.java sample file, 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.
Obtain all groups to which a user belongs with getGroupsForUser(String).
```
public List getGroupsForUser(String userSecurityName)       
     throws EntryNotFoundException,
            CustomRegistryException,
            RemoteException;
```
This method returns all the groups to which a user belongs whose name matches the supplied name. This method is similar to the getUniqueGroupIds method with the exception that the security names are used instead of the unique IDs.
In the FileRegistrySample.java sample file, this method returns all the group security names that contain the userSecurityName name.

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. Because 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.
Retrieve users from a specified group with getUsersForGroup(String,int).
```
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. This method is not directly called by the WebSphere Application Server security component. However, this method can be called by other components. In rare situations, if you are working with a user registry where getting all the users from any of your groups is not practical, you can create the NotImplementedException exception for the particular groups. In this case, verify that if the process choreographer is installed the staff assignments are not modeled using these particular groups. If no concern exists about returning the users from groups in the user registry, it is recommended that you do not create the NotImplemented exception when implementing this method.
The return parameter is an object with a com.ibm.websphere.security.Result type. This object contains the java.util.List and java.lang.boolean attributes. The list contains the users that are returned and the Boolean flag, which indicates whether more users are available in the user registry for the search pattern. This Boolean flag indicates to the client whether users are available in the user registry.

In the example, this method gets one user more than the requested number of users for a group. If the method succeeds in getting one more user, the Boolean flag is set to true.

In WebSphere Application Server Version 4, this getUsers method is mandatory for the product. For WebSphere Application Server Version 5.x or later, this method can create the NotImplementedException exception in situations where it is not practical to get the requested set of users. However, create this exception in rare situations when as other components can be affected. In Version 4, this method accepts only the pattern parameter and returns a list. In Version 5, this method accepts the limit parameter. Change your implementation to take the limit value and limit the users that are returned. The return changes to return a Result object, which consists of the list and a flag that indicates whether more entries exist. When the list is returned, use the Result.setList(List) method to set the list in the Result object. If more entries than requested are 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.
Implement the createCredential(String) method.
Attention: The first two lines of the following code sample are split for illustrative purposes only.
```
public com.ibm.websphere.security.cred.WSCredential createCredential(String userSecurityName)
 throws NotImplementedException,
            EntryNotFoundException,
            CustomRegistryException,
            RemoteException;
```
In this release the WebSphere Application Server, the createCredential method is not called. You can return null. In the example, a null value is returned.

Developing the UserRegistry interface for using custom registries

About this task

Procedure

What to do next