Before you begin
If you have built your own custom user registry, you will need to consider the migration items listed below. If you have a custom user registry that was provided by a Security Solution Provider, you will need to contract that provider to ensure you have the correct version of their custom user registry to support WebSphere Application Server Version 6.0.x and later
Before you perform this task, it is assumed that you have a custom user registry implemented and working with WebSphere Application Server Version 6.0.x and later. The custom registry interface is the UserRegistry interface.
In WebSphere Application Server Version 4, the custom user registry allows the use of data sources to connect to a database during initialization. However, you must change the implementation of WebSphere Application Server Version 6.0.x and later to use JDBC connections using native DatabaseDriver to connect to a database and NOT use data sources.
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. However, if you need the display names to return, set the WAS_UseDisplayName property to true. 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.
If the migration tool is used to migrate the WebSphere Application Server Version 4 configuration to WebSphere Application Server Version 6.0.x and later, the migration tool might not copy your implementation files from Version 4 to Version 6.0.x and later. You might have to copy them to the class path in the Version 6.0.x and later setup, preferably to the classes subdirectory.
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 run time.
Before proceeding, look at the UserRegistry interface. See Developing custom user registries for a description of each of these methods in detail.
Why and when to perform this task
The following steps go through all the changes that are required to move your WebSphere Application Server Version 5 custom user registry to the WebSphere Application Server Version 6.0.x and later custom user registry.Steps for this task
public class FileRegistrySample implements CustomRegistryto:
public class FileRegistrySample implements UserRegistry
public FileRegistrySample() throws java.rmi.RemoteException
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, 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.
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.
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 the 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.
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.
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.
%install_root%/java/bin/javac -classpath %WAS_HOME%/lib/wssec.jar; %WAS_HOME%/lib/sas.jar FileRegistrySample.javaType 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.
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.
Result
WebSphere Application Server Version 5 custom user registry is migrated to the WebSphere Application Server Version 6.0.x custom user registry.What to do next
If you are enabling security, make sure you 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.Related concepts
Custom user registries
Related tasks
Developing custom user registries
Related reference
UserRegistry.java files
FileRegistrySample.java file