Lightstreamer JMS Extender - Authentication and Authorization Demo - Java Hook
Java
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Lightstreamer JMS Extender - Authentication and Authorization Demo - Java Hook

The JMS Extender Authentication and Authorization Demo is a simple example illustrating authentication and authorization mechanisms when an external Web/Application Server is involved in the process.

This project includes a simple hook implementation that includes user validation and items authorization logics.

Details

This Authentication and Authorization Demo illustrates the typical best practice used for Lightstreamer JMS Extender Web applications, when a Web/Application server is involved in the process. The actual authentication is usually handled by the legacy Web/Application server, irrespective of JMS Extender. Some sort of token is sent back to the Client through cookies, response payload or any other technique. When the JMS JavaScript Client creates the JMS connection, instead of sending again the full credentials (usually involving a password) to the JMS Extender, it sends just the username and the token. The Hook is passed this information and validates the token against the Web/Application Server that generated it (or a database or whatever back-end system).

Here is an overview of the whole sequence:

sequence diagram

In this demo client the Web/Application server is not actually involved and calls to placeholder methods are performed to validate the tokens.

from src/jmsex_auth_demo/hooks/AuthHook.java:

[...]

AuthorizationResult result= AuthorizationRequest.validateToken(user, password);
if (result != AuthorizationResult.OK)
    throw new HookException("Unauthorized access: token invalid for user '" + user + "'", result.toString());

[...]

This demo also implements Authorization handling of consumer, producer and durable subscription creation requests. Every time a creation request is issued, the hook verifies if the user issuing the request is actually authorized to access the specified destination. Again, a real case might query an external service to verify the user authorizations; this example simply checks on an hard-coded list

from src/jmsex_auth_demo/hooks/AuthHook.java:

[...]

AuthorizationResult result= AuthorizationRequest.authorizeDestination(user, destinationName);
if (result != AuthorizationResult.OK)
    throw new HookException("Unauthorized access: user '" + user + "' can't receive messages from destination '" + destinationName + "'", result.toString());

[...]

Querying an external service at each request is a discouraged approach, though. If the authorizations are actually placed on an external service, it is suggested to use the approach shown in the AuthHookWithAuthCache class where authorizations are queried at connection startup and cached in the adapter.

More details and comments on how the authentication/authorization cycle is accomplished is available in the source code of the application.

The JMS Extender Configuration

The JMS Extender must also be configured appropriately to use the provided hook. Its jms_connectors_conf.xml file should look like:

<?xml version="1.0"?>

<jms_connectors_conf>

    <common>

        <!-- Optional. Fully qualified class name of a hook with purpose
             of authentication and authorization of users. The hook also has
             the purpose of decorating names for client IDs and durable
             subscriptions. Must implement JmsExtenderHook interface.
             See docs for more information.

             The specified class corresponds to the Authentication and
             Authorization Demo Hook.
             -->
        <param name="hook">jmsex_auth_demo.hooks.AuthHook</param>

    </common>

    <!-- Sample JMS connector configured for HornetQ (AKA JBoss Messaging). -->
    <jms_connector name="HornetQ">

        [...]

    </jms_connector>

</jms_connectors_conf>

Install

If you want to install this Demo in your local Lightstreamer JMS Extender, follow these steps.

  • Download and install the Lightstreamer JMS Extender. Please refer to Lightstreamer web site download page to find Lightstreamer JMS Extender download packages.
  • Make sure that the JMS Extender is not running.
  • Get the deploy.zip file, from the releases of this project, unzip it, go to the Deployment_LS folder and copy the JMS_Auth_demo.jar from JMS/lib into jms_connectors/lib folder of your JMS Extender installation.
  • Edit the jms_connectors/jms_connectors_conf.xml file of your JMS Extender installation by adding the appropriate hook class in the <param name="hook"> tag of the <common> section:
    • <param name="hook">jmsex_auth_demo.hooks.AuthHook</param> for the direct version;
    • <param name="hook">jmsex_auth_demo.hooks.AuthHookWithAuthCache</param> for the cached version.
  • Launch Lightstreamer JMS Extender.

Build

To build your own version of JMS_Auth_demo.jar, instead of using the one provided in the deploy.zip file from the Install section above, follow these steps.

  • Download this project.
  • Get the ls-jms-hook-interface.jar file from the latest Lightstreamer JMS Extender distribution, and copy it into the lib directory.
  • Assuming javac and jar are available on the path, from the command line run:
javac -classpath ./lib/ls-jms-hook-interface.jar -d ./classes ./src/jmsex_auth_demo/hooks/*.java
  • Then create the jar:
jar cvf JMS_Auth_demo.jar -C classes ./
  • Copy the just compiled JMS_Auth_demo.jar in the jms_connectors/lib folder of your Lightstreamer JMS Extender installation.

See Also

Clients Using This Adapter

Related Projects

JMS Extender Compatibility Notes

  • Compatible with Lightstreamer JMS Extender SDK for Java Hooks since 1.5 or newer.