Federation Guides › Legacy Federation Guide › Configure 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 CA SiteMinder® Programming Guide for Java.

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

If the plug-in successfully finds the user, CA 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, CA SiteMinder® calls the postAuthenticateUser method of the message consumer plug-in, if the plug-in is configured. If the method succeeds, CA 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 CA SiteMinder® Programming Guide for Java.

To configure the plugin

1. Install the CA SiteMinder® SDK, if you have not done so already.
2. Implement the MessageconsumerPlugin.java interface, which is part of the CA 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. CA 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. CA SiteMinder® calls this method once for each plug-in instance, when CA 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.

CA 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 CA 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 CA 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.

Enable the Message Consumer Plug-in for SAML 1.x

After writing a message consumer plug-in and compiling it, enable the plug-in by configuring settings in the Administrative UI. The UI settings tell CA SiteMinder® where to find the plug-in.

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

To enable the message consumer plug-in

1. Log on to the Administrative UI
2. Navigate to the Authentication Scheme dialog for the appropriate SAML 1.x scheme. In the Additional Configuration section, complete the following fields:

   Full Java Class Name

   Specify the Java class name for the plug-in, For example, a sample class included with the CA SiteMinder® SDK is:

   com.ca.messageconsumerplugin.MessageConsumerPluginSample

   Parameter

   Specify a string of parameters that are passed to the plug-in specified in the Full Java Class Name field.

   As an alternative to configuring the plug-in in the Administrative UI, use the Policy Management API (C or Perl) to set the IdpPluginClass and IdpPluginParameters.

3. Restart the Policy Server.