Implementing a custom SingleSignonToken

 

Overview

This task explains how to create your own SingleSignonToken implementation, which is set in the login Subject and added to the HTTP response as an HTTP cookie. The cookie name is the concatenation of the SingleSignonToken.getName() application programming interface (API) and the SingleSignonToken.getVersion() API. There is no delimiter. When you add a SingleSignonToken to the Subject, it also gets propagated horizontally and downstream in case the Subject is used for other Web requests. You must deserialize your custom SingleSignonToken when you receive it from a propagation login. Consider writing your own implementation if you want to accomplish one of the following:

• Isolate your attributes within your own implementation.

• Serialize the information using custom serialization. It is recommended that you encrypt the information because it is out to the HTTP response and is available on the Internet. You must deserialize or decrypt the bytes at the target and add that information back into the Subject.

• Affect the overall uniqueness of the Subject using the getUniqueID() API

To implement a custom SingleSignonToken, complete the following steps:

 

Procedure

1. Write a custom implementation of the SingleSignonToken interface.

   There are many different methods for implementing the SingleSignonToken interface. However, make sure that the methods required by the SingleSignonToken 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 SingleSignonToken, might extend the abstract class and then most of the work is completed.

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

2. Add and receive the custom SingleSignonToken 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, in order to deserialize the information, you will need to plug in a custom login module, which is discussed in a subsequent step. After the object is instantiated in the login module, one can add it to the Subject during the commit() method.

   The code sample in Example: custom SingleSignonToken login module shows how to determine if the login is an initial login or a propagation login. The difference is whether the WSTokenHolderCallback contains propagation data. If the callback does not contain propagation data, initialize a new custom SingleSignonToken implementation and set it into the Subject. Also, look for the HTTP cookie from the HTTP request if the HTTP request object is available in the callback. We can get your custom SingleSignonToken both from a horizontal propagation login and from the HTTP request. However, it is recommended that you make the token available in both places because then the information arrives at any front-end application server even if that server that does not support propagation.

   We can make your SingleSignonToken read-only in the commit phase of the login module. If you make the token read-only, additional attributes cannot be added within your applications.

    

   Restriction

   • HTTP cookies have a size limitation so do not add too much data to this token.

   • The WAS run time does not handle cookies that it does not generate, so this cookie is not used by the run time.

   • The SingleSignonToken object, when in the Subject, does affect the cache lookup of the Subject if you return something in the getUniqueID() method.

3. Get the HTTP cookie from the HTTP request object during login or from an application. The sample code, found in Example: HTTP cookie retrieval shows how one can retrieve the HTTP cookie from the HTTP request, decode the cookie so that it is back to your original bytes, and create your custom SingleSignonToken object from the bytes.

4. Add your custom login module to WAS system login configurations that already contain the com.ibm.ws.security.server.lm.wsMapDefaultInboundLoginModule for receiving serialized versions of your custom propagation 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 adding your custom login module into the existing login configurations, see Custom login module development for a system login configuration

 

Result

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

 

See also

Example: com.ibm.wsspi.security.token.SingleSignonToken implementation
Example: custom SingleSignonToken login module
Example: HTTP cookie retrieval

 

See Also

Custom login module development for a system login configuration

 

---