com.netegrity.policyserver.smapi
Interface MessageConsumerPlugin

public interface MessageConsumerPlugin

The base interface for providing Message Consumer Extension functionality. This plug-in extends the SiteMinder SAML 1.x, SAML 2.0 and the WS-Federation authentication schemes.

This section includes details about developing and integrating the plug-in. See Extend the SAML and WS-Federation Authentication Schemes for background information.

To develop the plug-in implementation:

• The implementation class must provide a public default constructor, which has no parameters.
• The implementation must be stateless -- that is, the single plug-in instance can be concurrently used for many threads.

To integrate the MessageConsumerPlugin with the SiteMinder SAML or WS-Federation authentication scheme:

• Compile the MessageConsumerPlugin Java file. It requires the following dependent libraries installed with SiteMinder Policy Server:
  • <InstallationRoot>\siteminder\bin\jars\SmJavaApi.jar There is an identical copy of SmJavaApi.jar installed with SiteMinder SDK, <InstallationRoot>\sdk\java\SmJavaApi.jar. You can use either of them at the development time.
• When a plug-in class is available, either in a folder or a jar file, modify the <InstallationRoot>\siteminder\config\JVMOptions.txt for the "-Djava.class.path" setting so that the plug-in class can be loaded with the modified classpath. Do not modify the ClassPath for the existing xerces.jar, xalan.jar, or SmJavaApi.jar.
• Restart the Policy Server.The Policy Server must be restarted to pick up the latest version of MessageConsumerPlugin each time the plug-in Java file is recompiled.
• Specify the full class name of the compiled plug-in in the "Advanced" tab of the SAML or WS-Federation Auth Scheme Properties dialog in the Admin GUI. Alternatively, you can use the Policy Management API (C or Perl) to set the IdpPluginClass and IdpPluginParameters.

Since:

SDK 6.0 SP3

Field Summary

static int	AUTH_REASON_FEDERATION_USER_NOT_IN_DIR Constant to indicate the configuration does not provide correct or sufficient information.
static int	AUTH_REASON_INVALID_MESSAGE Constant to indicate the response message is not formed correctly.
static int	AUTH_REASON_NO_LOGIN_ID Constant to indicate the configuration does not provide correct or sufficient information.
static int	AUTH_REASON_UNACCEPTED_MESSAGE Constant to indicate the response message is not accepted as a user credential.
static int	FAILURE Constant to indicate the processing of the response message has failed.
static int	SUCCESS Constant to indicate successful processing of the response message.

Method Summary

boolean	init(APIContext context) Performs any initialization procedures that MessageConsumerPlugin requires.
int	postAuthenticateUser(APIContext apiContext, java.lang.String parameters, java.lang.String message, java.util.Map props, int statusCode) Performs customization of federation credential validation.
int	postDisambiguateUser(APIContext apiContext, UserContext userContext, java.lang.String parameters, java.lang.String message, java.util.Map props, java.lang.String loginID, java.lang.StringBuffer output) Performs additional user disambiguation.
boolean	release(APIContext context) Performs any close-down procedures that the MessageConsumerPlugin requires.

Field Detail

AUTH_REASON_NO_LOGIN_ID

static final int AUTH_REASON_NO_LOGIN_ID

Constant to indicate the configuration does not provide correct or sufficient information. The LoginID is unattainable from the federation message.

See Also:

Constant Field Values

AUTH_REASON_FEDERATION_USER_NOT_IN_DIR

static final int AUTH_REASON_FEDERATION_USER_NOT_IN_DIR

Constant to indicate the configuration does not provide correct or sufficient information. The user was not found in the specified user store.

See Also:

Constant Field Values

AUTH_REASON_INVALID_MESSAGE

static final int AUTH_REASON_INVALID_MESSAGE

Constant to indicate the response message is not formed correctly. All the required elements might not be present.

See Also:

Constant Field Values

AUTH_REASON_UNACCEPTED_MESSAGE

static final int AUTH_REASON_UNACCEPTED_MESSAGE

Constant to indicate the response message is not accepted as a user credential.

See Also:

Constant Field Values

SUCCESS

static final int SUCCESS

Constant to indicate successful processing of the response message.

See Also:

Constant Field Values

FAILURE

static final int FAILURE

Constant to indicate the processing of the response message has failed. It has the value of UnknownUser authentication reason.

See Also:

Constant Field Values

Method Detail

init

boolean init(APIContext context)
             throws java.lang.Exception

Performs any initialization procedures that MessageConsumerPlugin requires.

SiteMinder calls this method when this MessageConsumerPlugin object is loaded. SiteMinder maintains a cache for all the instances, one instance per Policy Server. Each MessageConsumerPlugin is initialized only once.

Parameters:

context - A context object that provides methods for sending log, trace and error messages to the Policy Server.

Returns:

true if the initialization succeeds.

Throws:

java.lang.Exception - Thrown if anything happens unexpectedly; it is treated as an error.

release

boolean release(APIContext context)
                throws java.lang.Exception

Performs any close-down procedures that the MessageConsumerPlugin requires.

SiteMinder calls this method once for each instance of MessageConsumerPlugin class, when this object is unloaded, or SiteMinder is shutting down. SiteMinder maintains a cache for all the instances, one instance per Policy Server. Each MessageConsumerPlugin is released only once.

Parameters:

context - A context object that provides methods for sending log, trace and error messages to the Policy Server.

Returns:

true if the shutdown succeeds.

Throws:

java.lang.Exception - Thrown if anything happens unexpectedly; it is treated as an error.

postDisambiguateUser

int postDisambiguateUser(APIContext apiContext,
                         UserContext userContext,
                         java.lang.String parameters,
                         java.lang.String message,
                         java.util.Map props,
                         java.lang.String loginID,
                         java.lang.StringBuffer output)
                         throws java.lang.Exception

Performs additional user disambiguation. The Policy Server calls this method when the SAML authentication scheme cannot disambiguate the user.

Parameters:

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

userContext - A context object that provides directory information for user disambiguation.

parameters - The parameters string configured with the plug-in.

message - The federation message, which is the SAML Response element.

props - The Map object that contains all the name/value pair settings defined for the authentication scheme.

loginID - The available loginID, which can be used to search the user in the directory

output - The result buffer, which contains the user DN.

Returns:

The processing status, which is either an authentication reason code, or SUCCESS, or FAILURE. This return value is used as the real status for the SAML authentication scheme

Throws:

java.lang.Exception - Thrown when an error has occurred.

postAuthenticateUser

int postAuthenticateUser(APIContext apiContext,
                         java.lang.String parameters,
                         java.lang.String message,
                         java.util.Map props,
                         int statusCode)
                         throws java.lang.Exception

Performs customization of federation credential validation.

Parameters:

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

parameters - The parameters string configured with the plug-in.

message - The federation message, which is the SAML Response element

props - The Map object that contains all the name/value pair settings defined for the authentication scheme

statusCode - The current processing status.

Returns:

The processing status, which is either an authentication reason code, or SUCCESS, or FAILURE. This return value is used as the real status for the SAML authentication scheme.

Throws:

java.lang.Exception - Thrown when an error has occurred.