Implementing a custom AuthenticationToken

 

Overview

This task explains how you might create your own AuthenticationToken implementation, which is set in the login Subject and propagated downstream. This implementation enables you to 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 AuthenticationToken implementations are not used by the security run time in WAS 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 AuthenticationToken.

• Call the getUniqueId() method for uniqueness

• Call the getName() and the getVersion() methods for adding serialized bytes to the TokenHolder that is sent downstream

All of the other uses are custom implementations.

To implement a custom authentication token, complete the following steps:

 

Procedure

1. Write a custom implementation of the AuthenticationToken interface. There are many different methods for implementing the AuthenticationToken interface. However, make sure that the methods required by the AuthenticationToken interface and the token interface are fully implemented. After you implement this interface, one can place it in the install_dir/classes directory. Alternatively, one can place the class in any private directory. However, make sure that the WAS class loader can locate the class and that it is granted the appropriate permissions. We can add the JAR file or directory that contains this class into the server.policy file so that it has the necessary permissions that are needed by the server code.

   Tip: All of the token types defined by the propagation framework have similar interfaces. Basically, 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 AuthenticationToken, might extend the abstract class and then most of the work is completed.

   To see an implementation of AuthenticationToken, see Example: com.ibm.wsspi.security.token.AuthenticationToken implementation

2. Add and receive the custom AuthenticationToken during WAS logins This task is typically accomplished by adding a custom login module to the various application and system login configurations. However, in order to deserialize the information, plug in a custom login module. After the object is instantiated in the login module, one 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, if you want to do your own custom serialization, or if you want to specify the uniqueness for Subject caching purposes, then consider writing your own AuthenticationToken implementation.

   The code sample in Example: custom AuthenticationToken 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 contains propagation data. If the callback does not contain propagation data, initialize a new custom AuthenticationToken implementation and set it into the Subject. If the callback contains propagation data, look for your specific custom AuthenticationToken TokenHolder instance, convert the byte[] back into your custom AuthenticationToken object, and set it back into the Subject. The code sample shows both instances.

   You can make your AuthenticationToken read-only in the commit phase of the login module. If you do not make the token read-only, then attributes can be added within your applications.

3. Add your custom login module to WebSphere Application Server system login configurations that already contain the com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule for receiving serialized versions of your custom authorization token

   Because this login module relies on information in the sharedState added by the com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule, add this login module after com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule. 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

 

Result

After completing these steps, you have implemented a custom AuthenticationToken.

 

See also

Example: com.ibm.wsspi.security.token.AuthenticationToken implementation
Example: custom AuthenticationToken login module

 

Related Tasks

Propagating a custom Java serializable object

 

See Also

Custom login module development for a system login configuration

 

---