This topic explains how you might create your own propagation
token implementation, which is set on the running thread and propagated
downstream.
About this task
The default propagation token usually is sufficient for propagating
attributes that are not user-specific. 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 by plugging in a custom login module into the inbound
system login configurations. This task also might include encryption
and decryption.
To implement a custom propagation token, you must complete
the following steps:
- Write a custom implementation of the PropagationToken interface. Many different methods are available for implementing the PropagationToken
interface. However, make sure that the methods that are required by
the PropagationToken interface and the token interface are fully implemented.
![[AIX Solaris HP-UX Linux Windows]](../images/dist.gif)
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 that it has the required permissions for the server code.
After you implement this interface, you can place
it in the profile_root/classes directory. For more information on classes, see Creating a classes subdirectory in your profile for custom classes.
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 propagation
token, might extend the abstract class and then most of the work is
complete.
To see an implementation of the propagation token,
see Example: com.ibm.wsspi.security.token.PropagationToken implementation.
- Add and receive the custom propagation 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.
You also can add the implementation from an application. However,
to deserialize the information, you must plug in a custom login module,
which is discussed in Propagating a custom Java serializable object for security attribute propagation.
The WSSecurityPropagationHelper class has APIs that are used to set
a propagation token on the thread and to retrieve the token from the
thread to make updates.
The code sample in Example: Custom propagation 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 propagation token implementation
and set it on the thread. If the callback contains propagation data,
look for your specific custom propagation token TokenHolder instance,
convert the byte array back into your custom PropagationToken object,
and set it back on the thread. The code sample shows both instances.
You
can add attributes any time your custom propagation token is added
to the thread. If you add attributes between requests and the getUniqueId
method changes, the Common Secure Interoperability Version 2 (CSIv2)
client session is invalidated so that it can send the new information downstream.
Adding attributes between requests can affect performance. In many
cases, you want the downstream requests to receive the new propagation
token information.
To add the custom propagation token to the
thread, call the WSSecurityPropagationHelper.addPropagationToken method.
This call requires the WebSphereRuntimePerMission "setPropagationToken" Java 2 Security permission.
- 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 propagation
token You can also add this login module to any of the
application logins where you might want to generate your custom propagation
token on the thread during the login. Alternatively, you can generate
the custom PropagationToken implementation from within your application.
However, to deserialize it, you must add the implementation to the
system login modules.
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.