Federation Guides › Legacy Federation Guide › Configure a WS-Federation Account Partner › Customize a SAML Assertion Response (optional)

Customize a SAML Assertion Response (optional)

You can modify the assertion content using an assertion generator plug-in. The plug-in enables you to customize the content of an assertion using the business agreements between you and your partners and vendors. One plug-in is allowed for each partner.

The steps to configure an assertion generator plug-in are:

1. Install the CA SiteMinder® SDK, if you have not done so already.
2. Implement the AssertionGeneratorPlugin.java interface, which is part of the SDK.
3. Deploy your assertion generator plug-in implementation class.
4. Enable the assertion generator plug-in parameters in the Administrative UI.

Additional information about the Assertion Generator plug-in can be found as follows:

• Reference information (method signatures, parameters, return values, data types), and also the new constructor for UserContext class, are in the Javadoc Reference. Refer to the AssertionGeneratorPlugin interface in the Javadoc.
• Overview and conceptual information for authentication and authorization APIs is in the CA SiteMinder® Programming Guide for Java.

Implement the AssertionGeneratorPlugin Interface

The first step in creating a custom assertion generator plug-in is to implement the AssertionGeneratorPlugin interface.

Follow these steps:

1. Provide a public default constructor method that contains no parameters.
2. Provide code so that the implementation is stateless. Many threads must be able to use a single plug-in class.
3. Implement methods in the interface to satisfy your requirements.

   The implementation must include a call to the customizeAssertion methods. You can overwrite the existing implementations. See the following sample classes for examples:

   SAML 1.x/WS-Federation

   AssertionSample.java

   SAML 2.0

   SAML2AssertionSample.java

   The sample classes are located in the directory /sdk/samples/assertiongeneratorplugin.

   The contents of the parameter string that your implementation passes 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 AssertionGeneratorPlugin interface, compile it and verify that CA SiteMinder® can find your executable file.

To deploy the assertion generator plug-in

1. Compile the assertion plug-in Java file.

   Compilation requires the following .jar files, which are installed with the Policy Server:

   • policy_server_home/bin/jars/SmJavaApi.jar
   • policy_server_home/bin/thirdparty/xercesImpl.jar
   • policy_server_home/bin/endorsed/xalan.jar
2. In the JVMOptions.txt file, modify the -Djava.class.path value so it includes the classpath for the plug-in. This modification enables the plug-in to be loaded with the modified classpath. Locate the JVMOptions.txt file in the directory installation_home\siteminder\config.

   Note: Do not modify the classpath for xercesImpl.jar, xalan.jar, or SMJavaApi.jar.

3. Enable the plug-in.

Enable the Assertion Generator Plug-in

After writing an assertion generator plug-in and compiling it, enable the plug-in by configuring settings in the Administrative UI. The UI parameters let CA SiteMinder® know where to find the plug-in.

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

Follow these steps:

1. Log on to the Administrative UI.
2. Click Federation, Legacy Federation, Resource Partners.
3. Select an existing Resource Partner entry or create one.
4. Navigate to the General settings.
5. In the Advanced section, complete the following fields:

   Java Class Name

   Specify a Java class name for an existing plug-in

   The plug-in class can parse and modify the assertion, and then return the result to the Assertion Generator for final processing.

   Only one plug-in is allowed for each partner. For example, com.mycompany.assertiongenerator.AssertionSample

   Parameter

   (Optional) Specify a string of parameters that is passed to the plug-in specified in the Java Class Name field.

   Note: Instead of enabling the assertion plug-in through the Administrative UI, you can use the Policy Management API (C or Perl) to integrate the plug-in. For more information, see the CA SiteMinder® Programming Guide for C or the CA SiteMinder® Programming Guide for Java.

6. Restart the Policy Server.

   Restarting the Policy Server ensures that the latest version of the assertion plug-in is picked up after being recompiled.

Customize the Assertion with Attributes from a Web Application

You can use an assertion generator plug-in to add web application attributes tp an assertion. This is another way to customize the assertion.

To include web application attributes in an assertion

1. Compile the assertion plug-in Java file.

   Compilation requires the following .jar files, which are installed with the Policy Server:

   • policy_server_home/bin/jars/SmJavaApi.jar
   • policy_server_home/bin/thirdparty/xercesImpl.jar
   • policy_server_home/bin/endorsed/xalan.jar
2. In the JVMOptions.txt file, modify the -Djava.class.path value so it includes the classpath for the plug-in. This modification enables the plug-in to be loaded with the modified classpath. Locate the JVMOptions.txt file in the directory installation_home\siteminder\config.

   Note: Do not modify the classpath for xercesImpl.jar, xalan.jar, or SMJavaApi.jar.

3. Configure a sample plug-in.

   An APIContext class in the SMJavaAPI has a new method, getAttrMap(), which returns a map object containing the attributes from the web application included in the assertion. In the SiteMinder SDK, there are two sample Assertion Generator plug-ins that show how to use this map object:

   • SAML2AppAttrPlugin.java (SAML 2.0)
   • WSFedAppAttrPlugin.java (WS-Federation)

   These samples are located in the directory sdk/samples/assertiongeneratorplugin. They enable the Assertion Generator to add attributes from a web application to an assertion.

4. Log in to the Administrative UI.
5. Select Federation, Legacy Federation, SAML Service Providers or Resource Partners.
6. Select an exiting entry or create one.
7. Navigate to the General settings.
8. In the Assertion Generator Plug-in section, complete the following fields:

   Java Class Name

   Names the Java class for the plug-in. For example, the sample classes included with the CA SiteMinder® SDK are:

   • com.ca.assertiongenerator.SAML2AppAttrPlugin

     (SAML 2.0)

   • com.ca.assertiongenerator.WSFedAppAttrPlugin

     (WS-Federation)

   Parameter

   Specify a string of parameters that is passed to the plug-in specified in the Java Class Name field. These parameters would be the attributes that you want to include in the assertion.

   Note: Instead of configuring the settings through the Administrative UI, you can use the Policy Management API (C or Perl) to integrate the plug-in. For instructions, see the CA SiteMinder® Programming Guide for C or the CA SiteMinder® Programming Guide for Java.

9. Restart the Policy Server.

   Restarting the Policy Server verifies that the latest version of the assertion plug-in is picked up after being recompiled.