A default PropagationToken is located on the thread of execution for applications and the security infrastructure to use. WebSphere Application Server propagates this default PropagationToken downstream and the token stays on the thread where the invocation lands at each hop. The data should be available from within the container of any resource where the PropagationToken lands. Remember that you must enable the propagation feature at each server where a request is sent in order for propagation to work. Make sure that you have enabled security attribute propagation for all of the cells in your environment where you want propagation
There is a WSSecurityHelper class that has application programming interfaces (APIs) for accessing the PropagationToken attributes. This article documents the usage scenarios and includes examples. A close relationship exists between PropagationToken and the WorkArea feature. The main difference between these features is that after you add attributes to the PropagationToken, you cannot change the attributes. You cannot change these attributes so that the security run time can add auditable information and have that information remain there for the life of the invocation. Any time that you add an attribute to a specific key, an ArrayList is stored to hold that attribute. Any new attribute added with the same key is added to the ArrayList. When you call getAttributes, the ArrayList is converted to a String[] and the order is preserved. The first element in the String[] is the first attribute added for that specific key.
In the default PropagationToken, a change flag is kept that logs any data changes to the token. These changes are tracked to enable WebSphere Application Server to know when to re-send the authentication information downstream so that the downstream server has those changes. Normally, Common Secure Interoperability Version 2 (CSIv2) maintains a session between servers for an authenticated client. If the PropagationToken changes, a new session is generated and subsequently a new authentication occurs. Frequent changes to the PropagationToken during a method cause frequent downstream calls. If you change the token prior to making many downstream calls or you change the token between each downstream call, you might impact security performance.
Getting the server list from the default PropagationToken
String[] server_list = null;
// If security is disabled on this application server, do not bother checking
if (com.ibm.websphere.security.WSSecurityHelper.isServerSecurityEnabled())
{
try
{
// Gets the server_list string array
server_list = com.ibm.websphere.security.WSSecurityHelper.getServerList();
}
catch (Exception e)
{
// Performs normal exception handling for your application
}
if (server_list != null)
{
// print out each server in the list, server_list[0] is the first server
for (int i=0; i<server_list.length; i++)
{
System.out.println("Server[" + i + "] = " + server_list[i]);
}
}
}
Getting the caller list from the default PropagationToken
The following code sample shows how to use the getCallerList() API:
String[] caller_list = null;
// If security is disabled on this application server, do not check the caller list
if (com.ibm.websphere.security.WSSecurityHelper.isServerSecurityEnabled())
{
try
{
// Gets the caller_list string array
caller_list = com.ibm.websphere.security.WSSecurityHelper.getCallerList();
}
catch (Exception e)
{
// Performs normal exception handling for your application
}
if (caller_list != null)
{
// Prints out each caller in the list, caller_list[0] is the first caller
for (int i=0; i<caller_list.length;i++)
{
System.out.println("Caller[" + i + "] = " + caller_list[i]);
}
}
}
The format of each caller in the list is: cell:node:server:realm:port_number/securityName. The output, for example, is: myManager:node1:server1:ldap.austin.ibm.com:389/jsmith.
Getting the first caller from the default PropagationToken
String first_caller = null;
// If security is disabled on this application server, do not bother checking
if (com.ibm.websphere.security.WSSecurityHelper.isServerSecurityEnabled())
{
try
{
// Gets the first caller
first_caller = com.ibm.websphere.security.WSSecurityHelper.getFirstCaller();
// Prints out the caller name
System.out.println("First caller: " + first_caller);
}
catch (Exception e)
{
// Performs normal exception handling for your application
}
}
The output, for example, is: jsmith.
Getting the first application server name from the default PropagationToken
Whenever you want to know what the first application server is for this request, you can call the getFirstServer() method directly. The following code sample retrieves the name of the first application server using the getFirstServer() API:
String first_server = null;
// If security is disabled on this application server, do not bother checking
if (com.ibm.websphere.security.WSSecurityHelper.isServerSecurityEnabled())
{
try
{
// Gets the first server
first_server = com.ibm.websphere.security.WSSecurityHelper.getFirstServer();
// Prints out the server name
System.out.println("First server: " + first_server);
}
catch (Exception e)
{
// Performs normal exception handling for your application
}
}
The output, for example, is: myManager:node1:server1.
Adding custom attributes to the default PropagationToken
// If security is disabled on this application server,
// do not check the status of server security
if (com.ibm.websphere.security.WSSecurityHelper.isServerSecurityEnabled())
{
try
{
// Specifies the key and values
String key = "mykey";
String value1 = "value1";
String value2 = "value2";
// Sets key, value1
com.ibm.websphere.security.WSSecurityHelper.
addPropagationAttribute (key, value1);
// Sets key, value2
String[] previous_values = com.ibm.websphere.security.WSSecurityHelper.
addPropagationAttribute (key, value2);
// Note: previous_values should contain value1
}
catch (Exception e)
{
// Performs normal exception handling for your application
}
}
Getting custom attributes from the default PropagationToken
The following code sample shows how to use the getPropagationAttributes API:
// If security is disabled on this application server, do not bother checking
if (com.ibm.websphere.security.WSSecurityHelper.isServerSecurityEnabled())
{
try
{
String key = "mykey";
String[] values = null;
// Sets key, value1
values = com.ibm.websphere.security.WSSecurityHelper.
getPropagationAttributes (key);
// Prints the values
for (int i=0; i<values.length; i++)
{
System.out.println("Value[" + i + "] = " + values[i]);
}
}
catch (Exception e)
{
// Performs normal exception handling for your application
}
}
Value[0] = value1
Value[1] = value2
See Adding custom attributes to the default PropagationToken to add attributes using the addPropagationAttributes API.
Changing the TokenFactory associated with the default PropagationToken