You can create your 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.
About this task
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 single sign-on token 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 single sign-on token when you receive it from a propagation
login. 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. 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 by using the getUniqueID
API.
To implement a custom single sign-on token, complete the following
steps:
Procedure
- Write a custom implementation of the SingleSignonToken
interface.
Many different methods are available for
implementing the SingleSignonToken interface. However, make sure the
methods that are required by the SingleSignonToken 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 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. 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 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
- 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, you must plug in a custom
login module, which is discussed in a subsequent step. After the object
is instantiated in the login module, you 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.
You can get your custom single sign-on token 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 does not support propagation.
You can make your single
sign-on token 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. Size restrictions should
be included in the documentation for your specific browser.
- The WebSphere Application Server 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.
- Get the HTTP cookie from the HTTP request
object during login or from an application.
The sample
code that is found in
Example: An HTTP cookie retrieval shows how you 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.
- 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 propagation token.
Because this login module relies on information in the sharedState
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 adding your custom login module
into 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
single sign-on token.