JBoss.orgCommunity Documentation

Chapter 13. TorqueBox Authentication

13.1. Security Domains
13.2. Configuration
13.3. Ruby API

TorqueBox provides a simple Ruby interface to the underlying JAAS security framework built into the JBoss Application Server. JAAS (Java Authentication and Authorization Service) is a pluggable security framework which intends to shield application developers from the underlying security implementation. We kept with this approach for TorqueBox and have hidden most all of the implementation details so you can focus on writing your applications.

TorqueBox applications can authenticate against any security realm that you have specified in your JBoss configuration file (typically standalone.xml or standalone-ha.xml). configuration. To learn more about how JBoss security works and is configured, refer to the JBoss documentation. The TorqueBox integration, however, makes authenticating against a corporate JAAS data store trivial.

The JBoss Application Server allows application developers to authenticate against any of the JAAS security policies configured in the AS. In addition, TorqueBox adds TorqueBox-specific security policies to the AS when your application is deployed. We refer to these JAAS policy names as "domains". TorqueBox ships with a simple authentication domain, named torquebox. The torquebox domain uses a SimpleServerLoginModule for authentication.

The SimpleServerLoginModule login algorithm is: if password is null, authenticate the user and assign an identity of "guest" and a role of "guest". else if password is equal to the user name, assign an identity equal to the username and both "user" and "guest" roles else authentication fails.

To use the torquebox domain, specify this in your deployment descriptor:

The torquebox domain is deployed on demand only if your application specifies it in the configuration file. However, note that JAAS security domains are available to all applications deployed within the AS.

In addition to the torquebox security domain, an application specific domain - torquebox-appname is initialized when your application is deployed. The name of the application is determined from the name of your external descriptor (your *-knob.yml file) - the -knob.yml is dropped, leaving the application name.

This domain allows you to specify username/password pairs inside your deployment descriptor. Users are authenticated against whatever usernames and passwords you have configured.

TorqueBox authentication is configured in the torquebox.yml file or in a separate auth.yml by adding an auth section. Within this, you may add one or more named authentication handles. For example, let's say your application is a dashboard which allows users to access JMX and HornetQ data. Most of the time, you're going to be using the hornetq domain, but on occasion, you'll want to authenticate against the JMX domain. You can do this within Ruby code by configuring your auth section.

When using the DSL in torquebox.rb, each authentication entry is specified using the authentication directive.

A handle to the HornetQ authentication domain is now available to you with:

authenticator = TorqueBox::Authentication.default

and the JMX authentication domain can be obtained with:

authenticator = TorqueBox::Authentication['jmx']

The Ruby API has 3 methods:

The first two methods, default and [] are used to get the default authentication domain or to look up an authenticator by name. The last is to actually authenticate a user. To use the Ruby API, require torquebox and torquebox-authentication as shown below. This code shows a simple Ruby authentication module that authenticates agains the JAAS security configuration.

require 'torquebox'
require 'torquebox-security'

module MyApp
  module Authentication
    def login_path

    def authenticated?
    def authenticate(username, password)
      return false if username.blank? || password.blank?
      authenticator = TorqueBox::Authentication.default
      authenticator.authenticate(username, password) do
        session[:user] = username

    def require_authentication
      return if authenticated?
      redirect login_path 

    def logout
      session[:user] = nil
      redirect login_path

The authenticate method accepts a block, allowing you to execute code within an authenticated context.