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, you must contact that provider to ensure that
you have the correct version of their custom user registry to support WebSphere
Application Server.
Before you begin
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 Developing the UserRegistry interface for using custom registries 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 nodes class paths and profile_root/classes directories.
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 standalone custom 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.
- 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.
- Make sure you have the com.ibm.ws.runtime.jar file
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:
javac -J-Djava.version=1.5 -classpath
profile_root/plugins/com.ibm.ws.runtime.jar FileRegistrySample.java
Type
the previous lines as one continuous line.
- Copy the implementation classes to the product class path.
It is recommended that
you copy these implementation classes to the profile_root/classes directory.
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 standalone custom 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.
What to do next
If you are enabling security, see Enabling security 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.