This topic explains how you might create your own authentication
token implementation, which is set in the login Subject and propagated
downstream.
About this task
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 by 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 by using the getUniqueID
application programming interface (API).
Important: Custom authentication token implementations
are not used by the security runtime in WebSphere® Application
Server to enforce authentication. WebSphere Application
Security runtime 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:
Procedure
- 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
app_server_root/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 that are 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 for security attribute propagation. 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 Developing custom login
modules for a system login configuration for JAAS.
Results
After completing these steps, you have implemented a custom
authentication token.