Extending Artemis Security with OAuth2

As documented in ActiveMQ Artemis documentation, there are a number of JAAS Login Modules that come with the product. In addition to these modules, you also have the ability to extend the Security Login Module by implementing your own custom logic.

This article outlines how you can create your own Login Module to provides an example for basic OAuth2 Token Authorization.

Creating an OAuth2 Token

For demonstration purposes, this module will use GitHub as the OAuth2 authority. Github has a fairly detailed process on creating an OAuth2 token, but I will highlight the important steps.

  1. Register a new OAuth application. There are a number of fields to fill in, like Homepage URL and Authorization callback URL, but for our purposes these can be made up values. Here are the values I used: Application name: ArtemisOAuth2Client, Homepage URL: http://apache.activemq.org, Authorization callback URL: https://activemq.apache.org/artemis.
  2. After registering, this creates a Client ID and Client Secret for your application.
  3. Next is creating a personal access token. This involves creating a token description: artemis-privilege-scope, and then assigning scopes to that token. Select any of the scopes, but for this example I selected ‘repo’.
  4. After creation, this results in a token that can be used for authorization. Make sure to copy the token because you will not see it again. (You can regenerate if you lose it).

The result of this process is your own OAuth2 token, which we will now use in the client connection to Artemis, via the OAuth2LoginModule.

Extending the JAAS Login Module

The general process to adding your customized Login Module in Artemis is creating a class that extends javax.security.auth.spi.LoginModule and placing it in a ‘jar’. This ‘jar’ is then placed in the ${ARTEMIS_HOME}/lib directory so that it can be added to the Artemis classpath.

The following is an example from my github account for a simple OAuth2 implementation of a LoginModule. I also recommend viewing the GuestLoginModule from the Artemis baseline, as it provides a fairly straightforward example.

As for the OAuth2 integration, the minimum that you need is the authorization token (passed via the JMSConnectionFactory), the roll to be approved, and the Authorization URL. The roll and authorization URL values are passed in via properties, which are provided in the login.config file in ${BROKER_HOME}/etc. For example:

activemq {   
org.apache.activemq.artemis.plugins.security.jaas.Oauth2LoginModule sufficient
org.apache.activemq.jaas.oauth2.role="admin" org.apache.activemq.jaas.oauth2.oauth2url="api.github.com/user";

As reference, the ‘activemq’ is the identifier of the security domain which is created in the ${BROKER_HOME}/etc/bootstrap.xml

<jaas-security domain="activemq"/>

This configuration instructs the broker to execute the OAuth2LoginModule whenever a client connects. Upon connection, JAAS invokes your implementation of initialize, login, logout, commit, and abort. In this demonstration, ‘initialize()’ handles the values received from login.config.

The ‘login()’ implementation uses the authorization URL that was provided via login.config. If a call to the authorization URL with the OAuth2 token is successful, then the login is considered successful. The RolePrincipal and UserPrincipal are saved so that they can referenced during during ‘commit()’.

In ‘commit()’, if the login was successful the principals are added, which enable Artemis to create the connection. If the login was not successful, then the Artemis client will be unable to make the connection.

Once your implementation of LoginModule is complete, build your jar and add to the ${ARTEMIS_HOME}/lib directory. You then need to update your ${BROKER_HOME}/etc/login.config to invoke this module.

After everything is in place, start the broker and use your favorite Artemis client to connect — making sure to pass the OAuth2 token via the JMSConnectionFactory username.

Special Thanks

The pattern used for this example was built upon the work found on this blog post: https://mariuszprzydatek.com/2014/01/04/token-based-authentication-plugin-for-activemq/. This blog post provided a process to add token-based authentication for ActiveMQ 6.x. The upcoming release of ActiveMQ is Artemis-based, therefore BrokerFilter and BrokerPlugin are no longer available as Artemis leverages JAAS for security plugins. Thank you!

Like what you read? Give Joseph S. Butler a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.