Previous Topic: Authentication and Authorization APIsNext Topic: Delegated Management Services API


Customizing a SAML Assertion

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.

CA SiteMinder® Federation 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.

Diagram showing the process of customizing a SAML assertion

The process of customizing a SAML assertion includes these steps:

  1. Implement the Java assertion generator plug-in interface.
  2. Deploy the new assertion generator plug-in .
  3. Configure the assertion generator plug-in in the CA SiteMinder® Federation UI.

Implement the Java Assertion Generator Plug-in Interface

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:

  1. Provide a public default constructor method that contains no parameters.
  2. Provide code that helps ensure that the implementation is stateless, so that many threads can use a single plug-in class.
  3. Include a call to the customizeAssertion method.

    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.

Deploy the Assertion Generator Plug-in

After you have coded your implementation class for the AssertionGeneratoPlugin.java interface, compile it and verify that CA SiteMinder® Federation can find your executable file.

Follow these steps:

  1. Compile the assertion generator plug-in code in one of the following ways:
  2. In the JVMOptions.txt file, modify the -Djava.class.path value so it includes the classpath for the plug-in. Locate the JVMOptions.txt file in the directory federation_mgr_home\siteminder\config.

    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 CA SiteMinder® Federation. The binaries are not installed with the CA SiteMinder® Federation SDK. Using these files is necessary for compatibility reasons.

  3. Restart the CA SiteMinder® Federation services.

    Restarting the services helps ensure that CA SiteMinder® Federation uses the latest version of the assertion generator plug-in.

Configure the Assertion Generator Plug-in in the UI

To configure the assertion generator plug-in, you provide values for settings in the CA SiteMinder® Federation UI.

Note: Do not configure the plug-in settings until you deploy the plug-in.

Follow these steps:

  1. Log on to the CA SiteMinder® Federation UI.
  2. Navigate to the Assertion Configuration step of the Partnership wizard for the partnership you want to modify.
  3. Enter values for the following fields:
    Plug-in Class

    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 CA SiteMinder® Federation 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.

    Plug-in Parameter

    (Optional). Specifies the string that CA SiteMinder® Federation 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 CA SiteMinder® Federation assertion generator creates enhanced assertions as defined by the federation partners.