Security domains exchange authentication and authorization using data packages named assertions. The Security Assertion Markup Language (SAML) is an open standard that specifies the format of an assertion. A federated partnership consists of an identity provider (producer of an assertion) and a service provider (consumer of an assertion).
An enterprise can modify the content of an assertion based on the business agreements between the federated partners. For example, one partner can require user-friendly name equivalents for the attributes in the assertion. Or, a partner can opt to include the XML-type designation for each attribute in the assertion.
Federation Manager creates SAML assertions with its implementation of the AssertionGeneratorPlugin.java interface. An Application Developer can enhance the contents of the SAML assertion by overwriting the existing implementation class.
The diagram shown following illustrates the process of creating a custom assertion generator plug-in.
The process of customizing a SAML assertion includes these steps:
You create a custom assertion generator plug-in by implementing the AssertionGeneratorPlugin.java interface. The minimum requirements for the implementation class are listed following.
Follow these steps:
Example
In this example, imagine that the application developer defines handler.updateNameID to create user-friendly name attributes.
/**
* <p>Performs Assertion Generator callout functionality to customize the
* SAML assertion in the <code>AssertionGeneratorPlugin</code> object and
* returns a result.</p>
* @param apiContext A context object that provides methods for sending
* log, trace, and error messages to the Policy Server. Use the APIContext.getAttrMap() method to retrieve attributes posted by the application specified in the Application URL.
* @param userContext A context object that allows a custom object to set
* and retrieve information about a user in a user
* directory. The information includes user
* attributes and directory attributes associated
* with the user.
* @param pluginParam The string for Assertion plug-in parameters.
* @param inputAssertion The current XML token representing the SAML Assertion.
* @param outputAssertion The final XML token representing the SAML Assertion.
* @return 0 if assertion is customized successfully, or -1 if no customization or an error occurred.
* If the method fails, the outputAssertion is ignored.
* @throws java.lang.Exception For cases when the customization terminates unexpectedly.
*
**/
public int customizeAssertion(APIContext apiContext, UserContext userContext,String pluginParam,
String inputAssertion, final StringBuffer outputAssertion) throws Exception {
if (inputAssertion == null || inputAssertion.equals("")) {
// Indicates non-zero for an error.
apiContext.trace(PLUGIN_TAG, "Received null or empty response for customization");
return -1;
}
apiContext.trace(PLUGIN_TAG, "Entering customizeAssertion");
StringBuffer newAssertion = new StringBuffer(inputAssertion);
try
{
Saml1AssertionHandler handler =
initHandler(apiContext, userContext);
handler.updateNameID(newAssertion);
handler.addAttributes(pluginParam, newAssertion);
}
catch(Throwable th)
{
apiContext.error("SAML1AssertionSample: " + th.getMessage());
StringWriter writer = new StringWriter();
th.printStackTrace(new PrintWriter(writer));
writer.flush();
apiContext.trace(PLUGIN_TAG,
"Error customizing Assertion:\n" + writer.toString());
apiContext.trace(PLUGIN_TAG, "Done customizeAssertion");
return -1;
}
outputAssertion.append(newAssertion);
apiContext.trace(PLUGIN_TAG, "Done customizeAssertion");
// return "success"
return 0;
}
Note: The syntax requirements and use of the parameter string that is passed into the customizeAssertion method is the responsibility of the custom object.
After you have coded your implementation class for the AssertionGeneratoPlugin.java interface, compile it and verify that Federation Manager can find your executable file.
Follow these steps:
Windows: build_plugin.bat
UNIX: build_plugin.sh
A compiled sample plug-in, fedpluginsample.jar, is in the directory federation_mgr_sdk_home\jar.
You can place the plug-in jar in any directory and have the JVMOptions.txt file point to it. To use the sample plug-in, modify the classpath to point to fedpluginsample.jar; however, do not modify the classpath for smapi.jar.
Note: To use Apache Xerces or Xalan in your plug-in, use the Xerces or Xalan binary files installed with Federation Manager. The binaries are not installed with the Federation Manager SDK. Using these files is necessary for compatibility reasons.
Restarting the services helps ensure that Federation Manager uses the latest version of the assertion generator plug-in.
To configure the assertion generator plug-in, you provide values for settings in the Federation Manager UI.
Note: Do not configure the plug-in settings until you deploy the plug-in.
Follow these steps:
Specifies the Java class name of the plug-in. Enter a name. This plug-in is invoked at run time.
Example: com.mycompany.assertiongenerator.AssertionSample
The plug-in class can parse and modify the assertion, and then return the result to Federation Manager for final processing. Specify an assertion generator plug-in for each relying party. A compiled sample plug-in is included in the directory federation_mgr_sdk_home/jar.
(Optional). Specifies the string that Federation Manager passes to the plug-in as a parameter at run time. The string can contain any value; there is no specific syntax to follow.
The plug-in interprets the parameters that it receives. For example, the parameter is the name of an attribute, or the string can contain an integer that instructs the plug-in to do something.
The assertion generator plug-in is coded, compiled, and in place. The Federation Manager assertion generator creates enhanced assertions as defined by the federation partners.
|
Copyright © 2012 CA Technologies.
All rights reserved.
|
|