<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="authentication">
  <title>TorqueBox Authentication</title>

  <para>
    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.
  </para>
  <para>
    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 <ulink
    url="https://docs.jboss.org/author/display/AS7/Admin+Guide#AdminGuide-SecurityRealms">the
    JBoss documentation</ulink>. The TorqueBox integration, however,
    makes authenticating against a corporate JAAS data store trivial.
  </para>

  <section id="security-domains">
    <title>Security Domains</title>
    <para>
      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
      <code>torquebox</code>.  The <code>torquebox</code> domain uses a
      <code>SimpleServerLoginModule</code> for authentication.
    </para>
    <para>
      The <code>SimpleServerLoginModule</code> 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.
    </para>
    <para>
      To use the <code>torquebox</code> domain, specify this in your deployment descriptor:
    </para>
    
    <para><example>
      <title>Using the <code>torquebox</code> domain</title>
      <para>Using the YAML syntax:<programlisting>auth:
  default:
    domain: torquebox</programlisting></para>

      <para>And via the DSL:<programlisting>TorqueBox.configure do
  ...
  authentication :default, :domain => 'torquebox'
end</programlisting></para>
     </example></para>

    <para>
      The <code>torquebox</code> 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.  
    </para>
    <para>
      In addition to the <code>torquebox</code> security domain, an application specific
      domain - <code>torquebox-<replaceable>appname</replaceable></code> is initialized 
      when your application is deployed. The name of the application is determined from 
      the name of your external descriptor (your <filename><replaceable>*</replaceable>-knob.yml</filename>
      file) - the <filename>-knob.yml</filename> is dropped, leaving the application name.
    </para>
      
    <para>
      This domain allows you to specify username/password pairs inside your deployment descriptor.
      Users are authenticated against whatever usernames and passwords you have configured.
    </para>

      <para><example>
        <title>Using the <code>torquebox</code> domain</title>
        <para>Using the YAML syntax:<programlisting>auth:
  default:
    domain: torquebox-myapp
    credentials:
      john: johnspassword
      alice: alicespassword</programlisting></para>

      <para>And via the DSL:<programlisting>TorqueBox.configure do
  ...
  authentication :default do 
    domain 'torquebox'
    credential 'john', 'johnspassword'
    credential 'alice', 'alicespassword'
  end
end</programlisting></para>
     </example></para>
    

  </section>

  <section id="authentication-configuration">
    <title>Configuration</title>
    <para>
      TorqueBox authentication is configured in the <code>torquebox.yml</code> file or in a
      separate <code>auth.yml</code> by adding an <code>auth</code> 
      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 <code>auth</code> section.
    </para>

    <para>When using the DSL in <filename>torquebox.rb</filename>, each authentication entry
    is specified using the <methodname>authentication</methodname> directive.</para>
    
    <para><example>
      <title>Using the <code>torquebox</code> domain</title>
      <para>Using the YAML syntax:<programlisting>auth:
  default:
    domain: hornetq
  jmx:
    domain: jmx-console</programlisting></para>

      <para>And via the DSL:<programlisting>TorqueBox.configure do
  ...
  authentication :default, :domain => 'hornetq'
  authentication :jmx, :domain => 'jmx-console'
end</programlisting></para>
     </example></para>

    <para>
      A handle to the HornetQ authentication domain is now available to you with:
      <screen>authenticator = TorqueBox::Authentication.default</screen> and the JMX authentication
      domain can be obtained with: <screen>authenticator = TorqueBox::Authentication['jmx']</screen>
    </para>
  </section>

  <section id="authentication-ruby-api">
    <title>Ruby API</title>
    <para>
      The Ruby API has 3 methods:
    <itemizedlist spacing="compact">
      <listitem>
        <para><code>default</code></para>
      </listitem>
      <listitem>
        <para><code>[]( name )</code></para>
      </listitem>
      <listitem>
        <para><code>authenticate( username, password )</code></para>
      </listitem>
    </itemizedlist>
    </para>
    <para>
      The first two methods, <code>default</code> and <code>[]</code> 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 <code>torquebox</code> and <code>torquebox-authentication</code>
      as shown below. This code shows a simple Ruby authentication module that
      authenticates agains the JAAS security configuration.
    </para>
    
    <para>
      <screen>
require 'torquebox'
require 'torquebox-security'

module MyApp
  module Authentication
 
    def login_path
      "/login"
    end

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

    def require_authentication
      return if authenticated?
      redirect login_path 
    end

    def logout
      session[:user] = nil
      redirect login_path
    end
   
  end
end</screen>
      The <code>authenticate</code> method accepts a block, 
      allowing you to execute code within an authenticated context.
    </para>

  </section>

</chapter>
