Propagate a custom Java serializable object for security attribute propagation

Propagate a custom Java serializable object for security attribute propagation

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.

Prior to completing this task, verify that security propagation is enabled in the administrative console.

With security attribute propagation enabled, we can propagate data either horizontally with single sign-on (SSO) enabled or downstream using 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.

Tasks
Add our 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 created during login are added into the Subject.

After a custom Java object is added into the Subject, WAS 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 we put the classes together in a JAR file and add the file to the app_server_root/lib/ext/ directory, the login module has Java 2 Security AllPermissions permissions . IBM recommends that we add your login module and other infrastructure classes into any private directory. However, we must modify the profile_root/properties/server.policy file to make sure that your private directory, Java archive (JAR) file, or both have the permissions required to run the application programming interfaces (API) that are called from the login module. Because the login module might be run after the application code on the call stack, we might add doPrivileged code so that we do not need to add additional properties to the applications.
(iSeries) Important: Whenever you plug a custom login module into the login infrastructure of WebSphere Application Server, make sure that the code is trusted. When we add the login module into the profile_root/classes directory, the login module has Java 2 Security AllPermissions permissions. See Create 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, we might add doPrivileged code so that we do not need to add additional properties to the 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
     // our 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 our custom object. Make sure we 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 WAS, 
                  //  then return it and we do not need to add it here.
                  //  Otherwise, we can add it in the following code.
                  //  Note: If our 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. We might just return here if 
                  //  it is found in the list.

				        if (tokenHolder.getName().startsWith("com.acme.CustomObject"))
					     return true;
			    }
		  }
       //  If we get to this point, then our 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 the 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 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 our custom Java class implements the java.io.Serializable interface. An object that is added to the Subject must be serialized if we 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 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 Use the default authorization token to propagate security attributes.

PropagationToken

Add attributes specific to an invocation. See Use the default propagation token to propagate security attributes.

If we 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 our custom Java class exists on all of the systems that might receive the request.
When we add a custom object into the Subject and expect WAS to propagate the object, put the class definitions together in a JAR file and add the file to the app_server_root/lib/ext/ directory on all of the nodes where serialization or deserialization might occur. Verify that the Java class versions are the same.

(iSeries) When we 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. Verify that the Java class versions are the same.

Verify that our custom login module is configured in all of the login configurations used in the environment where we need to add our custom object during a login. Any login configuration that interacts with WAS generates a Subject that might be propagated outbound for an EJB request. If we want WAS to propagate a custom object in all cases, make sure that the custom login module is added to every login configuration used in the environment. 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, we must review the configuration to verify that propagation is enabled in all of the cells that might receive requests. We must check several places in the administrative console to make sure propagation is fully enabled. See Propagating security attributes among application servers.
Add any custom objects to the propagation exclude list that we do not want to propagate. We can configure a property to exclude the propagation of objects that match specific class names, package names, or both. For example, we can have a custom object that is related to a specific process. If the object is propagated, it does not contain valid information. We 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. We can add a list of custom objects to the propagation exclude list, separated by a colon (:). For example, we might enter com.acme.CustomLocalObject:com.acme.private.*. We can enter a class name such as com.acme.CustomLocalObject or a package name such as com.acme.private.*. In this example, WAS does not propagate any class that equals com.acme.CustomLocalObject or begins with com.acme.private.
Although we can add custom objects to the propagation exclude list, we must be aware of a side effect. WAS 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 the 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.
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:.

Related:

Security attribute propagation
Implement tokens for security attribute propagation
Developing custom login modules for a system login configuration for JAAS
Use the default authorization token to propagate security attributes
Use the default propagation token to propagate security attributes
Propagating security attributes among application servers
Security: Resources for learning
Authentication cache settings