Why and when to perform this task
This topic explains how you might create your own authentication
token implementation, which is set in the login Subject and propagated downstream.
With this implementation you can specify an authentication token that can
be used by a custom login module or application. Consider writing your own
implementation if you want to accomplish one of the following tasks:
- Isolate your attributes within your own implementation.
- Serialize the information using custom serialization. You must deserialize
the bytes at the target and add that information back on the thread. This
task also might include encryption and decryption.
- Affect the overall uniqueness of the Subject using the getUniqueID application
programming interface (API).
Important: Custom authentication token implementations are
not used by the security run time in WebSphere Application Server to enforce
authentication. WebSphere Application Security run time uses this token in
the following situations only:
- Call the getBytes method for serialization
- Call the getForwardable method to determine whether to serialize the authentication
token.
- Call the getUniqueId method for uniqueness
- Call the getName and the getVersion methods for adding serialized bytes
to the token holder that is sent downstream
All of the other uses are custom implementations.
To implement
a custom authentication token, you must complete the following steps:
- Write a custom implementation of the AuthenticationToken interface.
Many different methods are available for implementing the AuthenticationToken
interface. However, make sure the methods that are required by the AuthenticationToken
interface and the token interface are fully implemented. After you implement
this interface, you can place it in the install_dir/classes directory.
Alternatively, you can place the class in any private directory. However,
make sure that the WebSphere Application Server class loader can locate the
class and that it is granted the appropriate permissions. You can add the
Java archive (JAR) file or directory that contains this class into the server.policy file
so the class has the necessary permissions required by the server
code.
Tip: All of the token types that are defined by the propagation
framework have similar interfaces. The token types are marker interfaces that
implement the com.ibm.wsspi.security.token.Token interface. This interface
defines most of the methods. If you plan to implement more than one token
type, consider creating an abstract class that implements the com.ibm.wsspi.security.token.Token
interface. All of your token implementations, including the authentication
token, might extend the abstract class and then most of the work is complete.
To
see an implementation of the AuthenticationToken interface, see Example: A com.ibm.wsspi.security.token.AuthenticationToken implementation.
- Add and receive the custom authentication token during WebSphere
Application Server logins. This task is typically accomplished
by adding a custom login module to the various application and system login
configurations. However, to deserialize the information you must plug in a
custom login module. After the object is instantiated in the login module,
you can add the object to the Subject during the commit method.
If you only
want to add information to the Subject to get propagated, see Propagating a custom Java serializable object. If you want to ensure that
the information is propagated, do your own custom serialization, or specify
the uniqueness for Subject caching purposes, consider writing your own authentication
token implementation.
The code sample in Example: A custom authentication token login module, shows how
to determine if the login is an initial login or a propagation login. The
difference between these login types is whether the WSTokenHolderCallback
callback contains propagation data. If the callback does not contain propagation
data, initialize a new custom authentication token implementation and set
it into the Subject. If the callback contains propagation data, look for your
specific custom authentication token TokenHolder instance, convert the byte
array back into your custom AuthenticationToken object, and set it back into
the Subject. The code sample shows both instances.
You can make your
authentication token read-only in the commit phase of the login module. If
you do not make the token read-only, attributes can be added within your applications.
- Add your custom login module to WebSphere Application
Server system login configurations that already contain the com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule
login module for receiving serialized versions of your custom authorization
token.
Because this login module relies on information in the
shared state that is added by the com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule
login module, add this login module after the com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule
login module. For information on how to add your custom login module to the
existing login configurations, see Custom login module development for a system login configuration.