Implement a custom single sign-on token for security attribute propagation

We can create our own single sign-on token implementation. The single sign-on token implementation 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 (API) and the SingleSignonToken.getVersion API. There is no delimiter. When we add a single sign-on token to the Subject, it also gets propagated horizontally and downstream in case the Subject is used for other web requests. We must deserialize your custom single sign-on token when you receive it from a propagation login. Consider writing our own implementation to accomplish one of the following tasks:

• Isolate the attributes within our own implementation.

• Serialize the information by using custom serialization. Encrypt the information because it is out to the HTTP response and is available on the Internet. We 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 single sign-on token...

1. Write a custom implementation of the SingleSignonToken interface.

   Many different methods are available for implementing the SingleSignonToken interface. However, make sure the methods required by the SingleSignonToken interface and the token interface are fully implemented.

   (dist)(zos) After you implement this interface, we can place it in the app_server_root/classes directory. Alternatively, we can place the class in any private directory. However, verify the WAS class loader can locate the class and that it is granted the appropriate permissions. We can add the JAR file or directory containing this class into the server.policy file so that it has the required permissions for the server code.

   (iseries) After you implement this interface, we can place it in the profile_root/classes directory. For more information on classes, see Create a classes subdirectory in the profile for custom classes.

   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 we 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 the token implementations, including the single sign-on token, might extend the abstract class and then most of the work is complete.

   To see an implementation of the single sign-on token, see Example: A com.ibm.wsspi.security.token.SingleSignonToken implementation

2. Add and receive the custom single sign-on 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, plug in a custom login module, which is discussed in a subsequent step. After the object is instantiated in the login module, we can add it to the Subject during the commit method.

   The code sample in Example: A custom single sign-on token login module, shows how to determine if the login is an initial login or a propagation login. The difference is whether the WSTokenHolderCallback callback contains propagation data. If the callback does not contain propagation data, initialize a new custom single sign-on token 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 the custom single sign-on token both from a horizontal propagation login and from the HTTP request. However, IBM recommends that we make the token available in both places because then the information arrives at any front-end application server, even if that server does not support propagation.

   We can make the single sign-on token read-only in the commit phase of the login module. If we make the token read-only, additional attributes cannot be added within the applications.

   Restriction:

   • HTTP cookies have a size limitation. Size restrictions should be included in the documentation for the specific browser.

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

   • 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: An HTTP cookie retrieval shows how we can retrieve the HTTP cookie from the HTTP request, decode the cookie so that it is back to your original bytes, and create the custom SingleSignonToken object from the bytes.

4. Add the 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 the custom propagation token. Because this login module relies on information in the sharedState state 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 adding the custom login module into the existing login configurations, see Develop custom login modules for a system login configuration for JAAS.

Results

After completing these steps, we have implemented a custom single sign-on token.

Subtopics

• Example: A com.ibm.wsspi.security.token.SingleSignonToken implementation
  Use this file to see an example of a single sign-on implementation. The following sample code does not extend an abstract class, but implements the com.ibm.wsspi.security.token.SingleSignonToken interface directly. We can implement the interface directly, but it might cause you to write duplicate code. However, you might choose to implement the interface directly if considerable differences exist between how you handle the various token implementations.

• Example: A custom single sign-on token login module
  This file shows how to determine if the login is an initial login or a propagation login.

• Example: An HTTP cookie retrieval
  The following example shows you how to retrieve a cookie from an HTTP request, decode the cookie so that it is back to your original bytes, and create the custom SingleSignonToken object from the bytes. This example shows how to complete these steps from a login module. However, we also can complete these steps using a servlet.

Related concepts

Security attribute propagation

Related tasks

Propagating security attributes among application servers

Develop custom login modules for a system login configuration for JAAS