Federation Guides › Legacy Federation Guide › Configure CA SiteMinder® as a WS-Federation Resource Partner › 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 WS-Federation

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 WS-Federation scheme. In the General settings, go to the Advanced section and 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.

Redirect Users After Failed WS-Federation Authentication Attempts

For single sign-on processing, you can configure several optional redirect URLs if a user cannot be authenticated at the Resource Partner. The redirect URLs allow finer control over where a user is redirected. For example, when a user cannot be located in a user store, the Redirect URL for the User Not Found specification can redirect the user to the appropriate location.

Note: These URLs are not required.

If you do not configure redirect URLs, standard SiteMinder processing takes place. How SiteMinder handles a failed authentication depends on the configuration.

If a Resource Partner cannot authenticate a user during a single sign-on transaction, the Resource Partner can redirect that user to a customized URL for further processing.

You can configure several optional redirect URLs for failed authentication. If the assertion is not valid, the redirect URLs allow finer control over where a user is redirected. For example, if a user cannot be located in a user store, you can fill in a User Not Found redirect URL.

The Status Redirect URLs and Modes are in the Additional Configuration section of the authentication dialog. The redirect URLs are for specific status conditions:

• User is not found
• Single sign-on message is invalid
• User credentials are not accepted

If any of the conditions occur, redirect URLs can send the user to an application or a customized error page for further action.

Note: Configuring redirect URLs is not required.

To configure optional Redirect URLs

1. Navigate to the WS Federation authentication scheme you want to modify.
2. Select WS-Federation Configuration.
3. In the Advanced section, fill in a URL for one or more of the following fields:
   • Redirect URL for the User Not Found status
   • Redirect URL for the invalid SSO Message status
   • Redirect URL for the Unaccepted User Credential (SSO Message) status

   If enter a value for the Redirect URL for the Invalid SSO Message status, select a mode.

   Note: Click Help for descriptions of settings and controls, including their respective requirements and limits.

   Federation Web Services handles the errors by mapping the authentication reason into one of the configured redirect URLs. The user can be redirected to that URL to report the error.

Note: These redirect URLs can be used with the CA SiteMinder® message consumer plug-in for further assertion processing. If authentication fails, the plug-in can send the user to one of the redirect URLs you specify.