Migrating custom user registries:

s!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4//EN"> Migrating custom user registries:

Migrating custom user registries

Before you perform this task, it is assumed that you already have a custom user registry implemented and working in WebSphere Application Server Version 4. The custom registry in WebSphere Application Server Version 4 is based on the CustomRegistry interface. For WAS V5, the interface is called the UserRegistry interface. The WebSphere Application Server Version 4-based custom registry works without any changes to the implementation in WAS V5 except when the implementation is using data sources to connect to a database during initialization. If the previous implementation is using a data source to access a database, change the implementation to use JDBC connections to connect to the database. The WebSphere Application Server Version 4 version of the CustomRegistry interface is deprecated in WebSphere Application Server Version 5. So, moving your implementation to the WAS V5-based interface is expected.
In WAS V5, in addition to the UserRegistry interface, the custom user registry requires the Result object to handle user and group 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 WebSphere Application Server Version 4, it might have been possible to use other WebSphere Application Server components (for example, datasources) to initialize the custom registry. This is no longer possible in WAS V5, since other components like the containers are initialized after security and are not available during the registry initialization. In WebSphere Application Server Version 5, a custom registry implementation is a pure custom implementation, independent of other WebSphere Application Server components.
In WebSphere Application Server Version 4, if you had display names for users the EJB method getCallerPrincipal( ) and the servlet methods getUserPrincipal( ) and getRemoteUser( ) returned the display names. This behavior has changed in WAS V5. By default, these methods now return the security name instead of the display name. However, if you need the display names to return, set the WAS_UseDisplayName property to true. See the getUserDisplayName method description or the Javadoc, for more information.
If the migration tool was used to migrate the WebSphere Application Server Version 4 configuration to WAS V5, be aware that this migration does not involve any changes to your existing code. Since the WebSphere Application Server Version 4 custom registry works in WAS V5 without any changes to the implementation (except when using data sources) you can use the Version 4-based custom registry after the migration without modifying the code. Consider that the migration tool might not copy your implementation files from Version 4 to Version 5. You might have to copy them to the class path in the Version 5 setup (preferably to the classes subdirectoy, just like in Version 4). If you are using the Network Deployment version, copy the files to the cell and to each of the nodes class paths.
In Version 5, a case insensitive authorization can occur when using the custom registry. This authorization is new in Version 5 and in effect only on the authorization check. This function is useful in cases where your custom registry returns inconsistent (in terms of case) results for user and group unique IDs.
Note: Setting this flag does not have any effect on the user names or passwords. Only the unique IDs returned from the registry are changed to lower-case before comparing them with the information in the authorization table, which is also converted to lowercase during run time.
Before proceeding, look at the new UserRegistry interface. The section titled "Developing custom user registries" under Developing secured applications describes each of these methods in detail and also indicates the changes from Version 4. The following steps go through in detail all the changes required to move your WebSphere Application Server Version 4 custom user registry to the Version 5 custom user registry. The steps are very simple and involve minimal code changes. The sample implementation file is used as an example when describing some of the steps.
Change your implementation to UserRegistry instead of CustomRegistry . Change:
 public class FileRegistrySample implements CustomRegistry  
to 
 public class FileRegistrySample implements UserRegistry 
Throw the java.rmi.RemoteException in the constructors public FileRegistrySample() throws java.rmi.RemoteException
Change the mapCertificate method to take a certificate chain instead of a single certificate. Change
 public String mapCertificate(X509Certificate cert) 
to 
 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. 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 or the Java clients transport(layer certificates, Identity Assertion certificates). In Version 4, this was only called by Web clients since the CSIv2 protocol was not supported.
Remove the getUsers() method.
Change the signature of the getUsers(String) method to return a Result object and accept an additional parameter (int). Change:
 public List getUsers(String pattern)  
to 
 public Result getUsers(String pattern, int limit) 
In your implementation, construct the Result object from the list of the users obtained from the registry (whose number is 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 exceeds the limit value.
Change the signature of the getUsersForGroup(String) method to return a Result object and accept an additional parameter (int) and throw a new exception called NotImplementedException. Change
 public List getUsersForGroup(String groupName)
          throws CustomRegistryException,
                 EntryNotFoundException { 
to
public Result getUsersForGroup(String groupSecurityName, int limit)
          throws NotImplementedException,
                 EntryNotFoundException,
                 CustomRegistryException {
In Version 5, this method is not called directly by the WebSphere Application Server Security component. However, other components of the WebSphere Application Server like the WebSphere Application Server Enterprise Process Choreographer (Enterprise Edition) use this method when staff assignments are modeled using groups. Since this already is implemented in WebSphere Application Server Version 4, it is recommened that you change the implementation similar to the getUsers method as explained in step 5.
Remove the getUniqueUserIds(String) method.
Remove the getGroups() method.
Change the signature of the getGroups(String) method to return a Result object and accept an additional parameter (int). change
 public List getGroups(String pattern) 
to
 public Result getGroups(String pattern, int limit) 
In your implementation, construct the Result object from the list of the groups obtained from the registry (whose number is 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 exceeds the limit value.
Add the createCredential method. This method is not called at this time, so return as null .
 public com.ibm.websphere.security.cred.WSCredential createCredential(String userSecurityName)
         throws CustomRegistryException,
                NotImplementedException,
                EntryNotFoundException {
         return null;
   }
 
To build the Version 5 implementation make sure you have the sas.jar and wssec.jar in your class path.
 $WAS_HOME\java\bin\javac -classpath %WAS_HOME%\lib\wssec.jar;
%WAS_HOME%\lib\sas.jar FileRegistrySample.java
 
Type the previous lines as one continuous line.
To build the Version 4 custom registry in Version 5 and Version 5.0.1, only the wssec.jar file is required.
To build the Version 4 custom registry in Version 5.0.2, only the sas.jar file is required.
Copy the implementation classes to the product class path. The $WAS_HOME/lib/ext directory is the preferred location. If you are using the Network Deployment product, make sure that you copy these files to the cell and all the nodes. Without the files in each of the node class paths the nodes and the appservers in those nodes cannot start when security is on.
Use the administrative console GUI to set up the custom registry. Follow the instructions in the Configure custom user registries article to set up the custom registry including the IgnoreCase flag. Make sure you add the WAS_UseDisplayName properties, if required.
Results
Migrates a Version 4 custom registry to the Version 5 custom registry.

Usage scenario
This step is required to migrate a custom registry from WebSphere Application Server Version 4 to WAS V5.

What to do next
If you are enabling security, make sure you complete the remaining steps. Once completed, save the configuration and restart all the servers. Try accessing some J2EE resources to verify that the custom registry migration was successful.
Custom user registries
Developing custom user registries
UserRegistry.java files
FileRegistrySample.java file for WAS V5.0.2

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.