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.
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.
- To build the WebSphere Application Server Version 6.0.x and
later implementation, 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:
app_server_root/java/bin/javac -classpath
app_server_root/plugins/com.ibm.ws.runtime.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 com.ibm.ws.runtime.jar file is required.
- Copy the implementation classes to the product class
path.
The %install_root%/lib/ext directory
is the preferred location.
- 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 Platform, Enterprise Edition (Java EE)
resources to verify that the custom registry migration is successful.