This document describes how to add an object into the Subject
from a login module and describes other infrastructure considerations
to make sure that the Java object
gets propagated.
Before you begin
Prior to completing this task, verify that security propagation
is enabled in the administrative console.
About this task
With security attribute propagation enabled, you can propagate
data either horizontally with single sign-on (SSO) enabled or downstream
using Common Secure Interoperability Version 2 (CSIv2). When a login
occurs, either through an application login configuration or a system
login configuration, a custom login module can be plugged in to add Java serialized objects into the Subject during
login. This document describes how to add an object into the Subject
from a login module and describes other infrastructure considerations
to make sure that the Java object
gets propagated.
Procedure
- Add your custom Java object
into the Subject from a custom login module. A two-phase
process exists for each Java Authentication
and Authorization Service (JAAS) login module. WebSphere® Application
Server completes the following processes for each login module present
in the configuration:
- login method
- In this step, the login configuration callbacks are analyzed,
if necessary, and the new objects or credentials are created.
- commit method
- In this step, the objects or credentials that are created during
login are added into the Subject.
After a custom Java object
is added into the Subject, WebSphere Application Server
serializes the object on the sending server, deserializes the object
on the receiving server, and adds the object back into the Subject
downstream. However, some requirements exist for this process to occur
successfully. For more information on the JAAS programming model,
see the JAAS information provided in the Security: Resources for learning
article.
Important: Whenever you plug a custom login
module into the login infrastructure of WebSphere Application
Server, make sure that the code is trusted. When you add the login
module into the
profile_root/classes directory,
the login module has Java 2
Security AllPermissions permissions. For more information, see
Creating a classes subdirectory in your profile for custom classes. However, because the
login module might be run after the application code on the call stack,
you might add doPrivileged code so that you do not need to add additional
properties to your applications.
The following code sample
shows how to add doPrivileged code. For information on what to do
during initialization, login and commit, see
Developing custom login modules for a system login configuration for JAAS.
public customLoginModule()
{
public void initialize(Subject subject, CallbackHandler callbackHandler,
Map sharedState, Map options)
{
}
public boolean login() throws LoginException
{
// Construct callback for the WSTokenHolderCallback so that you
// can determine if
// your custom object has propagated
Callback callbacks[] = new Callback[1];
callbacks[0] = new WSTokenHolderCallback("Authz Token List: ");
try
{
_callbackHandler.handle(callbacks);
}
catch (Exception e)
{
throw new LoginException (e.getLocalizedMessage());
}
// Checks to see if any information is propagated into this login
List authzTokenList = ((WSTokenHolderCallback) callbacks[1]).
getTokenHolderList();
if (authzTokenList != null)
{
for (int i = 0; i< authzTokenList.size(); i++)
{
TokenHolder tokenHolder = (TokenHolder)authzTokenList.get(i);
// Look for your custom object. Make sure you use
// "startsWith"because there is some data appended
// to the end of the name indicating in which Subject
// Set it belongs. Example from getName():
// "com.acme.CustomObject (1)". The class name is
// generated at the sending side by calling the
// object.getClass().getName() method. If this object
// is deserialized by WebSphere Application Server,
// then return it and you do not need to add it here.
// Otherwise, you can add it below.
// Note: If your class appears in this list and does
// not use custom serialization (for example, an
// implementation of the Token interface described in
// the Propagation Token Framework), then WebSphere
// Application Server automatically deserializes the
// Java object for you. You might just return here if
// it is found in the list.
if (tokenHolder.getName().startsWith("com.acme.CustomObject"))
return true;
}
}
// If you get to this point, then your custom object has not propagated
myCustomObject = new com.acme.CustomObject();
myCustomObject.put("mykey", "mydata");
}
public boolean commit() throws LoginException
{
try
{
// Assigns a reference to a final variable so it can be used in
// the doPrivileged block
final com.acme.CustomObject myCustomObjectFinal = myCustomObject;
// Prevents your applications from needing a JAAS getPrivateCredential
// permission.
java.security.AccessController.doPrivileged(new java.security.
PrivilegedExceptionAction()
{
public Object run() throws java.lang.Exception
{
// Try not to add a null object to the Subject or an object
// that already exists.
if (myCustomObjectFinal != null && !subject.getPrivateCredentials().
contains(myCustomObjectFinal))
{
// This call requires a special Java 2 Security permission,
// see the JAAS application programming interface (API)
// documentation.
subject.getPrivateCredentials().add(myCustomObjectFinal);
}
return null;
}
});
}
catch (java.security.PrivilegedActionException e)
{
// Wraps the exception in a WSLoginFailedException
java.lang.Throwable myException = e.getException();
throw new WSLoginFailedException (myException.getMessage(), myException);
}
}
// Defines your login module variables
com.acme.CustomObject myCustomObject = null;
}
- Verify that your custom Java class
implements the java.io.Serializable interface. An object
that is added to the Subject must be serialized if you want the object
to propagate. For example, the object must implement the java.io.Serializable
interface. If the object is not serialized, the request does not fail,
but the object does not propagate. To make sure an object that is
added to the Subject is propagated, implement one of the token interfaces
that is defined in Security attribute propagation or
add attributes to one of the following existing default token implementations:
- AuthorizationToken
- Add attributes if they are user-specific. For
more information, see Using the default authorization token to propagate security attributes.
- PropagationToken
- Add attributes that are specific to an invocation. For more information, see Using the default propagation token to propagate security attributes.
If you are careful adding custom objects and follow
all the steps to make sure that WebSphere Application
Server can serialize and deserialize the object at each hop, then
it is sufficient to use custom Java objects
only.
- Verify that your custom Java class
exists on all of the systems that might receive the request.
When you add a custom
object into the Subject and expect WebSphere Application
Server to propagate the object, make sure that the class definition
for that custom object exists in the profile_root/classes directory
on all of the nodes where serialization or deserialization might occur.
Also, verify that the Java class
versions are the same.
- Verify that your custom login module is configured in all
of the login configurations used in your environment where you need
to add your custom object during a login. Any login configuration
that interacts with WebSphere Application Server
generates a Subject that might be propagated outbound for an Enterprise JavaBeans (EJB) request. If you want WebSphere Application Server to propagate
a custom object in all cases, make sure that the custom login module
is added to every login configuration that is used in your environment.
For more information, see Developing custom login modules for a system login configuration for JAAS.
- Verify that security attribute propagation is enabled on
all of the downstream servers that receive the propagated information. When an EJB request is sent to a downstream server and security
attribute propagation is disabled on that server, only the authentication
token is sent for backwards compatibility. Therefore, you must review
the configuration to verify that propagation is enabled in all of
the cells that might receive requests. You must check several places
in the administrative console to make sure propagation is fully enabled. For more information, see Propagating security attributes among application servers.
- Add any custom objects to the propagation exclude list
that you do not want to propagate. You can configure a
property to exclude the propagation of objects that match specific
class names, package names, or both. For example, you can have a custom
object that is related to a specific process. If the object is propagated,
it does not contain valid information. You must tell WebSphere Application
Server not to propagate this object. Complete the following steps
to specify the object in the propagation exclude list, using the administrative
console:
- Click Security > Global security > Custom properties >
New.
- Add com.ibm.ws.security.propagationExcludeList in
the Name field.
- Add the name of the custom object in the Value field. You can add a list of custom objects to the propagation exclude
list, separated by a colon (:). For example, you might enter com.acme.CustomLocalObject:com.acme.private.*.
You can enter a class name such as com.acme.CustomLocalObject or
a package name such as com.acme.private.*. In this example, WebSphere Application Server does not propagate
any class that equals com.acme.CustomLocalObject or begins
with com.acme.private.
Although you can add custom objects
to the propagation exclude list, you must be aware of a side effect. WebSphere Application Server stores the
opaque token, or the serialized Subject contents, in a local cache
for the life of the single sign-on (SSO) token. The life of the SSO
token, which has a default of two hours, is configured in the SSO
properties on the administrative console. The information that is
added to the opaque token includes only the objects not in the exclude
list.
Ensure that your SSO token timeout
value is greater that the authentication cache timeout value. To modify
the authentication cache, see the documentation about the authentication
cache settings.
Results
As a result of this task, custom Java serializable
objects are propagated horizontally or downstream. For more information
on the differences between horizontal and downstream propagation,
see
Security attribute propagation or add attributes to one of the following
existing default token implementations:.