Previous Topic: Configure Social Sign-onNext Topic: Delegated Authentication

Federation Guides › Partnership Federation Guide › Assertion Processing Customization (Relying Party)

Assertion Processing Customization (Relying Party)

The message consumer plug-in is a Java program that implements the Message Consumer Extension API. 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.

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

If the plug-in successfully finds the user, the process continues 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, the system calls the postAuthenticateUser method of the message consumer plug-in, if the plug-in is configured. If the method succeeds, CA SiteMinder® Federation 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.

Reference information (method signatures, parameters, return values, data types), and the constructor for UserContext class, are in the Java SDK Programming Reference. Refer to the MessageConsumerPlugin interface.

To configure the plugin:

  1. Install the CA SiteMinder® Federation SDK.
  2. Implement the MessageconsumerPlugin.java interface, which is part of the 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 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 outcome of assertion processing, regardless of whether the Policy Server processing is a success or failure.

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

The default location for the samples is:

Windows

C:\Program Files\FederationManager\sdk\java\sample

The package name is com\ca\federation\sdk\plugin\sample.

UNIX

/FederationManager/sdk/java/sample

The package name is com/ca/federation/sdk/plugin/sample.

Deploy a Message Consumer Plug-in

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

Follow these steps:

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

    federation_install_dir\siteminder\bin\jars\SmJavaApi.jar

    federation_install_dir is the directory where you installed CA SiteMinder® Federation

  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 federation_mgr_installation_home\siteminder\config.

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

  3. Restart the system 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 in the UI

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® Federation 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.

    Select the Consumer-to-Producer or SP-to-IdP partnership that you want to modify.

  2. Navigate to the User Identification step in the partnership wizard.
  3. In the Message Consumer Plug-in section, complete the following fields:
    Plug-in Class

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

    com.ca.messageconsumerplugin.MessageConsumerPluginSample

    Plug-in Parameters

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

  4. Restart the federation services according to your operating environment.