Previous Topic: Custom Authentication Scheme Creation Uisng JavaNext Topic: Use the Authorization API

Programming Guides › Programming Guide for Java › Java Authentication and Authorization Guidance › Custom Authentication Scheme Creation Uisng Java › Extend the SAML and WS-Federation Authentication Schemes

Extend the SAML and WS-Federation Authentication Schemes

The SiteMinder SAML (1.x and 2.0) and WS-Federation authentication schemes process response messages. For business reasons, for example, you might want to add additional steps to further process a response. The Message Consumer Extension API defines an interface that enables you to elaborate on the SAML or WS-Federation response in two ways during the authentication process:

The SiteMinder Java MessageConsumerPlugin API implements the Message Consumer Extension (MCE) interface. You can code to your own requirements and then integrate the custom plug-in into SiteMinder.

The MessageConsumerPlugin includes the following four methods:

Method

Description

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, or to add data for new federation users to a user store. Note that this method receives the decrypted assertion. The decrypted assertion is added to the properties map passed to MCP under the key “_DecryptedAssertion”.

postAuthenticateUser()

Provides any additional code to determine the final outcome of assertion processing, regardless of whether the policy server processing results in success or failure.

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

The Role of the MessageConsumerPlugin

The following list describes the MessageConsumerPlugin in an elaborated process of user authentication:

  1. The Federation Web Services (FWS) application forwards a request for user authentication to the Policy Server.
  2. The Policy Server invokes the authentication scheme to disambiguate the user.
  3. The authentication scheme disambiguates the user as follows:
    1. The authentication scheme metadata is obtained from the Policy store.
    2. The authentication scheme attempts to obtain the LoginID. If LoginID is not found, the authentication scheme invokes the MessageConsumerPlugin as described in Step 4.
    3. If the LoginID is obtained successfully, the authentication scheme searches the current user directory with a predefined SearchSpec. If the user is not found, the postDisambiguate() method is called as described in Step 4. If the user is found, the Policy Server proceeds with credential validation, as described in Step 6 and following.
    4. When the authentication scheme does not provide the user store SearchSpec, the Policy Server core searches for the user with the search string defined with the User Directory object. The MessageConsumerPlugin is not called.
  4. The postDisambiguateUser() method searches a user directory to determine whether a particular LoginID exists. The result is returned to the authentication scheme. The method might be called several times if more than one user directory is configured. This method can also be used to add data for new federation users from the assertion to a user store.
  5. When the user has been successfully disambiguated by the Policy Server, the authentication scheme, or the plug-in, the Policy Server returns the user DN to the Policy Server and proceeds to credential validation (Step 8 and following).
  6. If the user has not been successfuly disambiguated for this user directory by either the Policy Server, the authentication scheme, or MessageConsumerPlugin, the FWS application checks the next user directory and repeats Steps 2 - 6 before proceeding with credential validation.
  7. When a user has been disambiguated, the Policy Server again calls the authentication scheme to determine whether the user has the proper credentials for the authentication request. The authentication scheme determines whether the response message is acceptable.
  8. After the the authentication scheme has attempted to authenticate the disambiguated user with the response message, the Policy Server calls the postAuthenticateUser() method from the MessageConsumerPlugin. The Policy Server always calls this method when a user is disambiguated, even when the Policy Server core performs the user disambiguation.
  9. You can use postAuthenticateUser() to add any other procedures for federation credential validation required by your implementation.
  10. The final result is passed back to the Policy Server by the authenticaiton scheme.
  11. If necessary, the FWS application can process any failure and redirect the user to an appropriate URL.