Migrate custom user registries

The custom registry in WebSphere Application Server Version 4 is based on the CustomRegistry interface. For WebSphere Application Server Version 5, the interface is called the UserRegistry interface. Note that the Version 4 based custom registry works without any changes to the implementation in Version 5 except when the implementation uses data sources to connect to a database during initialization. However, the Version 4 CustomRegistry is deprecated in Version 5 and may be removed in the next release. Hence, it is recommended that you migrate your implementation to the Version 5 based interface.

In Version 5, in addition to the UserRegistry interface, the custom user registry requires the Result object to handle users and groups information. This file is already provided in the package and you are expected to use it for the getUsers(), getGroups(), and the getUsersForGroup() methods.

In Version 4, it was possible to use other WebSphere Application Server components to initialize the custom registry. For example, a data source could be used to connect to a database-based user registry during the initialization of the custom registry. Deployed enterprise beans could also be used during initialization. This is no longer possible in Version 5 because other components (such as the containers) are not initialized until after security is initialized, and hence are not available during the registry initialization. In Version 5, a custom registry implementation is expected to be a pure custom implementation and should not depend on other WebSphere Application Server components.

In Version 4, if you implemented display names for users, the display names were returned by the enterprise bean method getCallerPrincipal() and the servlet methods getUserPrincipal() and getRemoteUser(). This behavior has changed in Version 5. By default, these methods now return the security name instead of the display name. However, if you want the display names to be returned, set the WAS_UseDisplayName property to true. See the getUserDisplayName() method description in the Interface CustomRegistry API documentation for more information.

If the migration tool was used to migrate the Version 4.0 configuration to Version 5, be aware that this migration does not involve any changes to your existing code. Use the Version 4.0 custom registry without changes to the code in Version 5 (except when data sources are used). If you want to continue using your Version 4 custom user registry with Version 5.0, follow the steps provided in Enable your Version 4 custom user registry to run with Version 5.

In Version 5, a case-insensitive authorization can be performed when the custom registry is used. This feature is new in Version 5 and effects only the authorization check. The case-insensitive authorization check is useful in cases where your custom registry returns case-inconsistent results for unique IDs of users and groups.

Note: Setting this flag does not effect user names or passwords. Only UniqueIDs that are returned from the registry are converted to lower case before they are compared with the information in the authorization table (which is also converted to lower case during run time).

Before you proceed with the migration, see Develop custom user registries for information about methods for the new UserRegistry interface.

Perform these steps to migration your Version 4 custom user registry to Version 5:

1. Change your code to implement UserRegistry instead of CustomRegistry. Change this code:

     public class FileRegistrySample implements CustomRegistry

   to this:

     public class FileRegistrySample implements UserRegistry

2. Throw the java.rmi.RemoteException in the constructors, for example:

     public FileRegistrySample() throws java.rmi.RemoteException

3. Change the mapCertificate() method to take a certificate chain instead of a single certificate. Change this code:

     public String mapCertificate(X509Certificate cert)

   to this:

     public String mapCertificate(X509Certificate[] cert)

   Having a certificate chain gives you the flexibility to act on the chain instead of one certificate. If you are only interested in the first certificate, just take the first certificate in the chain before processing it. Note that in Version 5, the mapCertificate() method is called to map the user in a certificate to a valid user in the registry, when certificates are used for authentication by the Web and or the Java clients (transport layer certificates, Identity Assertion certificates). In Version 4, this method was only called by Web clients because the Common Secure Interoperability, Version 2 (CSIv2) protocol was not supported.

4. Remove the getUsers() method.

5. Change the signature of the getUsers(String) method to return a Result object and accept an additional int parameter. Change this code:

     public List getUsers(String pattern)

   to this:

     public Result getUsers(String pattern, int limit)

   In your implementation, construct the Result object from the List of the users that is obtained from the registry (whose number should be limited to the value of the limit parameter), and call the setHasMore() method on the Result object if the total number of users in the registry exceed the limit value.

6. Change the signature of the getUsersForGroup(String) method to return a Result object, to accept an additional int parameter, and to throw a new exception called NotImplementedException. For example, change this code:

     public List getUsersForGroup(String groupName)
     throws CustomRegistryException,
            EntryNotFoundException {

   to this:

     public Result getUsersForGroup(String groupSecurityName, int limit)
     throws NotImplementedException,
            CustomRegistryException,
            EntryNotFoundException {

   Note: In Version 5, this method is not called directly by the WebSphere Application Server Security component. However, other components of WebSphere Application Server clients (such as the WebSphere Application Server Enterprise Process Choreographer (Enterprise Edition)) call this method when staff assignments are modeled using groups. Because this behavior was implemented in Version 4, it is recommended that you change the implementation in the method explained in step 5 (for the getUsers() method).

7. Remove the getUniqueUserIds(String) method.

8. Remove the getGroups() method.

9. Change the signature of the getGroups(String) method to return a Result object and accept an additional int parameter. Change this code:

     public List getGroups(String pattern)

   to this:

     public Result getGroups(String pattern, int limit)

   In your implementation, construct the Result object from the List of the groups that is obtained from the registry (whose number should be limited to the value of the limit parameter) and call the setHasMore() method on the Result object if the total number of groups in the registry exceed the limit value.

10. Add the createCredential() method. This method is not called at this time, so return as null. Here is an example:

      import com.ibm.websphere.security.cred.WSCredential;
    
      public WSCredential createCredential(String userSecurityName)
      throws CustomRegistryException,
             NotImplementedException,
             EntryNotFoundException {
    
        NotImplementedException ex = 
           new NotImplementedException("createCredential not implemented");
        throw ex;
      }

11. Compile your custom user registry:

    • For Versions 5.0 and 5.0.1
      Make sure /QIBM/ProdData/WebAS5/Base/lib/wssec.jar is in the compiler class path.

    • For Version 5.0.2 and later
      Make sure /QIBM/ProdData/WebAS5/Base/lib/sas.jar is in the compiler class path.

12. Assemble, deploy, and configure your custom user registry. For more information, see Configure the custom user registry.