Migrating custom user registries

If you built your own custom user registry, consider the migration items listed below. If you have a custom user registry that was provided by a Security Solution Provider, contact that provider to ensure that you have the correct version of their custom user registry to support WebSphere Application Server.

In WebSphere Application Server, 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.

You cannot use other WebSphere Application Server components, for example, data sources, to initialize the custom registry because other components, like the containers, are initialized after security and are not available during the registry initialization. A custom registry implementation is a pure custom implementation, independent of other WebSphere Application Server components.

The getCallerPrincipal enterprise bean method and the getUserPrincipal and getRemoteUser servlet methods return the security name instead of the display name. For more information, see UserRegistry interface methods or the API documentation.

If the migration tool is used to migrate the WebSphere Application Server Version 5 configuration to WebSphere Application Server Version 6.0.x and later, this migration does not change your existing code. Because the WebSphere Application Server Version 5 custom registry works in WebSphere Application Server Version 6.0.x and later without any changes to the implementation, except when using data sources, you can use the Version 5-based custom registry after the migration without modifying the code.

Copy the files to the cell and to each of the node class paths.

In WebSphere Application Server Version 6.0.x and later, a case-insensitive authorization can occur when using an enabled custom user registry.

Setting this flag does not have any effect on the user names or passwords. Only the unique IDs that are 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 runtime.

Before proceeding, look at the UserRegistry interface. See Developing custom user registries for a description of each of these methods in detail.

About this task

The following steps go through all the changes that are required to move your WebSphere Application Server Version 4.x custom user registry that implemented the old com.ibm.websphere.security.CustomRegistry interface to the com.ibm.websphere.security.UserRegistry interface.

Note: The sample implementation file is used as an example when describing the following steps.

Procedure

Change your implementation to UserRegistry instead of CustomRegistry. Change:

public class FileRegistrySample implements CustomRegistry

to:

public class FileRegistrySample implements UserRegistry

Create the java.rmi.RemoteException exception 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 interested only in the first certificate, take the first certificate in the chain before processing. In WebSphere Application Server Version 6.0.x and later, 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.
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 that is obtained from the user 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 exception. Change the following code:
```
public List getUsersForGroup(String groupName)
          throws CustomRegistryException,
                 EntryNotFoundException {
```
to:
```
public Result getUsersForGroup(String groupSecurityName, int limit)
          throws NotImplementedException,
                 EntryNotFoundException,
                 CustomRegistryException {
```
In WebSphere Application Server Version 6.0.x and later, this method is not called directly by the WebSphere Application Server security component. However, other components of WebSphere Application Server, like the WebSphere Business Integration Server Foundation process choreographer, use this method when staff assignments are modeled using groups. Because this implementation is supported in WebSphere Application Server Version 6.0.x and later, it is recommended 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 the following code:
```
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 that is obtained from the user registry whose number is limited to the value of the limit parameter. 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;
   }

The first and second lines of the previous code example are split onto two lines for illustrative purposes only.

To build the WebSphere Application Server Version 6.0.x and later implementation, make sure you have the sas.jar and the wssec.jar files in your class path.
To set the files in your class path, use the following code as a sample and substitute your environment values for the variables that are used in the example:
```
%install_root%/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 WebSphere Application Server Version 5 custom registry (CustomRegistry) in WebSphere Application Server Version 6.0.x and later, only the sas.jar file is required.
Copy the implementation classes to the product class path.
The %install_root%/lib/ext directory is the preferred location.
Make sure that you copy these classes to the cell and all the nodes. Without the classes in each of the node class paths, the nodes and the application servers in those nodes cannot start when security is on.
Use the administrative console to set up the custom registry.
Follow the instructions in Configuring custom user registries to set up the custom registry, including the Ignore case for authorization option. Make sure that you add the WAS_UseDisplayName properties if required.

Results

WebSphere Application Server Version 4.x based custom user registry that implemented the old com.ibm.websphere.security.CustomRegistry interface is migrated to the com.ibm.websphere.security.UserRegistry interface.

What to do next

If you are enabling security, see Enabling security for all application servers to complete the remaining steps. When completed, save the configuration and restart all the servers. Try accessing some Java 2 Platform, Enterprise Edition (J2EE) resources to verify that the custom registry migration is successful.