com.netegrity.policyserver.smapi
Interface AssertionGeneratorPlugin

All Superinterfaces:

AssertionGeneratorCacheObject

public interface AssertionGeneratorPlugin
extends AssertionGeneratorCacheObject

The base interface for objects that customize the default SAML assertion or SAML response generated by SiteMinder. For implementations adhering to SAML 1.x, SiteMinder provides a SAML assertion element as the default input. For implementations adhering to SAML 2.0, SiteMinder provides a SAML response element, which contains an assertion element, as the default input.

With this interface you can implement logic that customizes the format and content of the SAML input. The SAML Assertion Generator Framework calls the methods in the custom class.

Configuration of the assertion generator plug-in requires the Java API SiteMinder SDK version of v6.0 SP 2 or later.

Development, Configuration, and Deployment Notes

• The implementation class must provide a public default constructor with no parameters.
• The implementation must be stateless -- that is, the single plug-in instance can be concurrently used for multiple threads.
• Configure your custom implementation class in the Policy Server Affiliate Properties dialog (SAML 1.x), or in the Service Provider properties dialog (SAML 2.0), or through the C or Perl Policy Management API.
• You configure the custom class by specifying the full class name and optionally, any parameters that the class may require.
• To enable SiteMinder to locate your deployed implementation class, specify the deployment location in -Djava.class.path of the configuration file JVMOptions.txt. This file is in the following location of the SiteMinder installed directory structure:

   <install-path>\siteminder\config

For a sample of an assertion plug-in class, see AssertionSample.java in the following location of the SiteMinder installed directory structure:

    sdk\samples\assertiongeneratorplugin

Since:

SDK 6.0 SP1 CR4

Method Summary

int

customizeAssertion(APIContext apiContext, UserContext userContext, java.lang.String pluginParam, java.lang.String input, java.lang.StringBuffer output) Customizes the default SAML assertion (SAML 1.x) or response (SAML 2.0) that SiteMinder passes into this method, and returns an updated version of the input.

Methods inherited from interface com.netegrity.policyserver.smapi.AssertionGeneratorCacheObject

init, release

Method Detail

customizeAssertion

int customizeAssertion(APIContext apiContext,
                       UserContext userContext,
                       java.lang.String pluginParam,
                       java.lang.String input,
                       java.lang.StringBuffer output)
                       throws java.lang.Exception

Customizes the default SAML assertion (SAML 1.x) or response (SAML 2.0) that SiteMinder passes into this method, and returns an updated version of the input.

This method provides the user with the opportunity to validate or alter the input content. If an assertion generator plug-in is defined for an Affiliate (SAML 1.x), or Service Provider (SAML 2.0), the SiteMinder SAML Assertion Generator Framework calls this method after the default input is generated for the affiliate.

The implementor of this plug-in is responsible for understanding how to parse the SAML assertion or response passed in by SiteMinder.

Parameters:

apiContext - An APIContext object that provides methods for sending log, trace, and error messages to the Policy Server.

userContext - A UserContext 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.

pluginParam - Parameters that are passed into the custom object. The syntax and use of these parameters are entirely up to the custom object.

input - The current XML token representing the default SAML assertion (SAML 1.x) or response (SAML 2.0). Parsing this token (for example, with a DOM or SAX parser) is the responsibility of the custom object.

output - The final XML token representing the SAML input as modified by the custom object.

Returns:

0 if the input is customized successfully, or -1 if no customization occurred or if an error occurred. If the method fails, output is ignored, and the original input is used. If the custom object does not change the original input, the object should return -1, not 0.

Throws:

java.lang.Exception - If the custom object is terminated unexpectedly, it throws an exception. SiteMinder catches this exception and fails the request, because no correct assertion or response can be generated.

Note: input and output contain only an XML token. The token does not have <?xml ?> related tags. If your XML parser cannot read the token, add (at your own risk) <?xml version="1.0" encoding="UTF-8" ?> accordingly. Remove it before returning the modified token to SiteMinder.