Federation Security Services Guide › Configure SiteMinder as a SAML 1.x Consumer › Customize Assertion Processing with the Message Consumer Plug-in

Customize Assertion Processing with the Message Consumer Plug-in

The message consumer plug-in is a Java program that implements the Message Consumer Plug–in. The plug-in lets you implement your own business logic for processing assertions, such as rejecting an assertion and returning a status code. This additional processing works together with the standard processing of an assertion.

Note: For more information about status codes for authentication and disambiguation, see the SiteMinder Programming Guide for Java.

During authentication, SiteMinder first tries to process the assertion by mapping a user to its local user store. If SiteMinder cannot find the user, it calls the postDisambiguateUser method of the message consumer plug-in.

If the plug-in successfully finds the user, SiteMinder proceeds to the second phase of authentication. If the plug-in cannot map the user to a local user store, the plug-in returns a UserNotFound error. The plug-in can optionally use the redirect URL feature. Without the consumer plug-in, the redirect URLs are based on the error that the SAML authentication scheme generates.

During the second phase of authentication, SiteMinder calls the postAuthenticateUser method of the message consumer plug-in, if the plug-in is configured. If the method succeeds, SiteMinder redirects the user to the requested resource. If the method fails, you can configure the plug-in to send the user to a failure page. The failure page can be one of the redirect URLs that you can specify with the authentication scheme configuration.

Additional information about the message consumer plug-in can be found as follows:

• Reference information (method signatures, parameters, return values, data types), and the constructor for UserContext class, are in the Java Developer Reference. Refer to the MessageConsumerPlugin interface.
• Overview and conceptual information about authentication and authorization APIs, see the SiteMinder Programming Guide for Java.

To configure the plugin

1. Install the SiteMinder SDK, if you have not done so already.
2. Implement the MessageconsumerPlugin.java interface, which is part of the SiteMinder SDK.
3. Deploy your message consumer plug-in implementation class.
4. Enable the message consumer plug-in in the Administrative UI.

Implement the MessageConsumerPlugin Interface

Create a custom message consumer plug-in by implementing the MessageConsumerPlugin.java interface. The minimum requirements for the implementation class are listed in the following procedure.

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 as your requirements demand.

   The MessageConsumerPlugin includes the following four methods:

   init()

   Performs any initialization procedures that the plug-in requires. SiteMinder calls this method once for each plug-in instance, when the plug-in is loaded.

   release()

   Performs any rundown procedures that the plug-in requires. SiteMinder calls this method once for each plug-in instance, when SiteMinder is shutting down.

   postDisambiguateUser()

   Provides processing to disambiguate a user when the authentication scheme is unable to do so. Alternatively, this method can add data for new federation users to a user store. This method receives the decrypted assertion. The decrypted assertion is added to the properties map passed to plug-in under the key "_DecryptedAssertion".

   postAuthenticateUser()

   Provides additional code to determine the final outcome of assertion processing, regardless of whether the Policy Server processing is a success or failure.

SiteMinder provides the following samples of the Message Consumer plug-in class:

MessageConsumerPluginSample.java in installation_home\sdk\samples\messageconsumerplugin

MessageConsumerSAML20.java in installation_home\sdk\samples\authextensionsaml20

Deploy a Message Consumer Plug-in

After you have coded your implementation class for the MessageConsumerPlugin interface, compile it and verify that SiteMinder can find your executable file.

To deploy the Message Consumer Plugin:

1. Compile the MessageConsumerPlugin Java file. The file requires the following dependent libraries, which are installed with the Policy Server:

   installation_home\siteminder\bin\jars\SmJavaApi.jar

   An identical copy of SmJavaApi.jar is installed with SiteMinder SDK. The file is in the directory installation_home\sdk\java\SmJavaApi.jar.

   You can use either of them at development time.

2. When a plug-in class is available, in a folder or a jar file, modify the -Djava.class.path value in the JVMOptions.txt file. This step enables the plug-in class to load with the modified classpath. Locate the JVMOptions.txt file in the directory installation_home\siteminder\config.

   Note: Do not modify the classpath for the existing xerces.jar, xalan.jar, or SmJavaApi.jar.

3. Restart the Policy Server to pick up the latest version of MessageConsumerPlugin. This step is necessary each time the plug-in Java file is recompiled.
4. Enable the plug-in.