<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="security.config" xml:lang="en"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>Configuring Security</title>
  </info>

  <para>The <emphasis role="bold">security </emphasis>service is used by the
  <emphasis role="bold">ejb</emphasis>,<emphasis role="bold">
  web</emphasis>,<emphasis role="bold"> ws</emphasis> services to provide
  security for <xi:include href="../variables.xml" xpointer="element(j2ee)" />
  components. The <emphasis role="bold">ejb</emphasis> service provides
  security in two forms: declarative security and programmatic security that
  is described in the <link
  xlink:href="ejb2_programmer_guide.html#ejb2.security">EJB Programmer's
  Guide: Security Management</link> .</para>

  <para>The <emphasis role="bold">security </emphasis>service exploits
  security roles and method permissions located in the <xi:include
  href="../variables.xml" xpointer="j2ee" /> deployment descriptors.</para>

  <para>A main concept in security is <emphasis>Authentication </emphasis>
  which is the mechanism telling the container the identity of the user making
  the current request.</para>

  <para>A caller is a client that may be a servlet client or a container
  client. Usually a client proves its identity by a couple user/password or a
  certificate (<emphasis>credential</emphasis>). Once the identification is
  correct <xi:include href="../variables.xml" xpointer="element(appserver)" />
  must build a security context that will be propagated with requests and be
  used by the container to verify that the user exists and has permissions
  sufficient to make the request.</para>

  <para>JAAS is a standard framework for authenticating users. It defines
  configuration files (<filename>jaas.config)</filename> and interfaces like
  the <classname>LoginModule</classname> interface that may be used in
  <xi:include href="../variables.xml" xpointer="element(appserver)" /> to
  perform authentication tasks.</para>

  <para>Lightweight authentication mechanism using JACC may be used to
  authenticate servlet client.</para>

  <para>In the Tomcat documentation we can find this definition: <quote>A
  Realm is a "database" of usernames and passwords that identify valid users
  of a web application (or set of web applications), plus an enum eration of
  the list of roles associated with each valid user.</quote></para>

  <para>In both authentication mechanisms the container use a <emphasis>realm
  </emphasis> to verify validity of users. In JOnAS the
  <emphasis>realm</emphasis> may be a database accessed via JDBC (Database
  realm), a LDAP directory (LDAP realm) or a flat file (Memory realm). The
  type of realm to use is specified in
  <filename>$JONAS_BASE/conf/jonas-realm.xml</filename>.</para>

  <section>
    <info>
      <title>jonas-realm.xml</title>
    </info>

    <para>The file <filename>$JONAS_BASE/conf/jonas-realm.xml</filename> file
    describes:</para>

    <itemizedlist>
      <listitem>
        <para>the content of flat file memory realm</para>
      </listitem>

      <listitem>
        <para>how to access a database realm</para>
      </listitem>

      <listitem>
        <para>how to access a LDAP realm</para>
      </listitem>
    </itemizedlist>

    <section>
      <info>
        <title>Memory realm</title>
      </info>

      <para>The <emphasis>memoryrealm</emphasis> must be named and defines
      users, groups and roles in the section &lt;jonas-memoryrealm&gt;</para>

      <para><screen>&lt;jonas-memoryrealm&gt;
 &lt;memoryrealm name="memrlm_1"&gt; <co xml:id="memoryrealmname" />
   &lt;roles&gt;
     &lt;role name="jonas-admin" description="JonasAdmin role" /&gt; <co
            xml:id="memoryrealmrole" />
     &lt;role name="tomcat" description="Used in examples" /&gt;
   &lt;/roles&gt;
   &lt;groups&gt;
   &lt;group name="jonas" 
      roles="jonas-admin,tomcat,jaas,ws-security" description="All authorization" /&gt; <co
            xml:id="memoryrealmgroup" />
   &lt;/groups&gt;
   &lt;users&gt;
     &lt;user name="tomcat" password="tomcat" roles="tomcat,jonas-admin,manager" /&gt; <co
            xml:id="memoryrealmuser1" />
     &lt;user name="jetty" password="jetty" roles="jetty" /&gt;
     &lt;!-- Example of a crypt password : password for jadmin is : jonas --&gt;
     &lt;user name="jadmin" password="{MD5}nF3dVBB3NPfRgzWlJFwoaw==" roles="jonas-admin" /&gt; <co
            xml:id="memoryrealmuser2" />
     &lt;user name="jps_admin" password="admin" roles="administrator" /&gt;
     &lt;user name="supplier" password="supplier" roles="administrator" /&gt;
     &lt;!-- Another crypt example in another format : password is jonas --&gt;
     &lt;!-- JonasAdmin uses name="jonas" password="jonas" --&gt;
     &lt;user name="jonas" password="SHA:NaLG+uYfgHeqth+qQBlyKr8FCTw=" groups="jonas" /&gt; <co
            xml:id="memoryrealmuser3" />
     &lt;user name="principal1" password="password1" roles="role1" /&gt;
     &lt;user name="principal2" password="password2" roles="role2" /&gt;
    &lt;/users&gt;
 &lt;/memoryrealm&gt;
&lt;/jonas-memoryrealm&gt;</screen><calloutlist>
          <callout arearefs="memoryrealmname">
            <para>memoryrealm must be named. This name will be used in the web
            container configuration file</para>
          </callout>

          <callout arearefs="memoryrealmrole">
            <para>definition of a security role</para>
          </callout>

          <callout arearefs="memoryrealmgroup">
            <para>definition of a group of roles</para>
          </callout>

          <callout arearefs="memoryrealmuser1">
            <para>definition of a user with non encrypted password and a list
            of roles</para>
          </callout>

          <callout arearefs="memoryrealmuser2">
            <para>definition of a user with encrypted password (format
            MD5)</para>
          </callout>

          <callout arearefs="memoryrealmuser3">
            <para>definition of a user with encrypted password (format
            SHA)</para>
          </callout>
        </calloutlist>To get the correct encoded password, the MD5/SHA digest
      must be base64 encoded:</para>

      <screen>$ echo -n jonas | openssl md5 -binary | base64
$ nF3dVBB3NPfRgzWlJFwoaw==</screen>

      <para>This command is available on Linux or Cygwin</para>

      <para>An alternate way to obtain a correct encoded password would be to
      to write a java class that uses sun.misc.BASE64Encoder</para>
    </section>

    <section>
      <info>
        <title>database realm</title>
      </info>

      <para>Users, groups, and roles information are stored in a database; the
      configuration for accessing the corresponding database is described in
      the section &lt;jonas-dsrealm&gt;</para>

      <para>The configuration requires the name of a datasource, the tables
      used, and the names of the columns.</para>

      <para><screen>&lt;jonas-dsrealm&gt;
   &lt;dsrealm name="dsrlm_1" <co xml:id="dsrealmname" />
            dsName="jdbc_1" <co xml:id="dsrealmdsName" />
      userTable="realm_users" userTableUsernameCol="user_name" userTablePasswordCol="user_pass" <co
            xml:id="dsrealmusertable" />
      roleTable="realm_roles" roleTableUsernameCol="user_name" roleTableRolenameCol="role_name"&gt; <co
            xml:id="dsrealmroletable" />
   &lt;/dsrealm&gt;
&lt;/jonas-dsrealm&gt;</screen><calloutlist>
          <callout arearefs="dsrealmname">
            <para>dsrealm must be named</para>
          </callout>

          <callout arearefs="dsrealmdsName">
            <para>JNDI name of the <classname>dataSource</classname> for
            accessing the database via JDBC</para>
          </callout>

          <callout arearefs="dsrealmusertable">
            <para>defines the name of the user table and the name of the
            columns for username/password</para>
          </callout>

          <callout arearefs="dsrealmroletable">
            <para>defines the name of the role table and the name of the
            columns for username/rolename</para>
          </callout>
        </calloutlist></para>

      <para>to use this database a <classname>Datasource</classname>
      configuration with the right JNDI name for the <link
      linkend="services.dbm.config"><emphasis role="bold">dbm</emphasis>
      service</link> must be set in the <filename>jonas.properties</filename>
      file.</para>
    </section>

    <section>
      <info>
        <title>LDAP realm</title>
      </info>

      <para>Users, groups, and roles information are stored in an LDAP
      directory. This is described in the section
      &lt;jonas-ldaprealm&gt;</para>

      <para>There are some optional parameters. If they are not specified,
      some of the parameters are set to a default value. For example if the
      providerUrl element is not set, the default value is
      <uri>ldap://localhost:389</uri>. The <link
      xlink:href="http://jonas.objectweb.org/dtds/jonas-realm_1_0.dtd">jonas-realm_1_0.dtd
      DTD </link>file show the default values.</para>

      <para><itemizedlist>
          <listitem>
            <para>minimal example:</para>

            <para><screen>&lt;jonas-ldaprealm&gt;
&lt;ldaprealm name="ldaprlm_1" <co xml:id="ldaprealmname" />
     baseDN="dc=jonas,dc=ow2,dc=org" /&gt; <co xml:id="ldaprealmbasedn" />
&lt;/jonas-ldaprealm&gt;</screen><calloutlist>
                <callout arearefs="ldaprealmname">
                  <para>ldaprealm must be named</para>
                </callout>

                <callout arearefs="ldaprealmbasedn">
                  <para>to access to LDAP server</para>

                  <para>For this sample, it is assumed that the LDAP server is
                  on the same computer and is on the default port
                  (389).</para>
                </callout>
              </calloutlist></para>
          </listitem>
        </itemizedlist></para>
    </section>
  </section>

  <section>
    <info>
      <title>Servlet Authentication</title>
    </info>

    <para>Depending on the servlet container used, configuration
    differs.</para>

    <section>
      <info>
        <title>Authentication with User/password and Tomcat 6</title>
      </info>

      <itemizedlist>
        <listitem>
          <para>Tomcat configuration:</para>

          <para>Tomcat embedded in the <xi:include href="../variables.xml"
          xpointer="element(appserver)" /> distribution is configured in
          <filename>$JONAS_BASE/conf/tomcat6-server.xml </filename>to use the
          memory realm named <literal>memrlm_1</literal></para>

          <screen>&lt;Server&gt;
[...]
&lt;Realm className="org.ow2.jonas.web.tomcat6.security.Realm" resourceName="memrlm_1" /&gt;
[...]
&lt;/Server&gt;</screen>

          <para>The authentication mechanism implemented by the class
          <classname>org.ow2.jonas.web.tomcat6.security.Realm</classname> is
          able to work with database or LDAP realm configured in
          <filename>jonas-realm.xml. </filename>The value of resourceName
          attribute identifies the <emphasis>realm</emphasis> to be used in
          <filename>jonas-realm.xml.</filename></para>
        </listitem>

        <listitem>
          <para xml:id="config.webapp1">webapp configuration:</para>

          <para>In the <filename>web.xml </filename>of the web application a
          <emphasis>basic authentication</emphasis> or a <emphasis>Form based
          authentication</emphasis> may be used</para>

          <screen>&lt;web-app&gt;
&lt;login-config&gt;
    &lt;auth-method&gt;BASIC&lt;/auth-method&gt;
    &lt;realm-name&gt;Example Basic Authentication Area&lt;/realm-name&gt;
  &lt;/login-config&gt;
&lt;/web-app&gt;</screen>

          <para>or</para>

          <screen>&lt;web-app&gt;
 &lt;login-config&gt;
   &lt;auth-method&gt;FORM&lt;/auth-method&gt;
   &lt;form-login-config&gt;
   &lt;form-login-page&gt;login.jsp&lt;/form-login-page&gt;
   &lt;form-error-page&gt;error.jsp&lt;/form-error-page&gt;
   &lt;/form-login-config&gt;
   &lt;/login-config&gt;
&lt;/web-app&gt;</screen>

          <para>Like basic authentication, form-based authentication is not
          secure, since the content of the user dialog is sent as plain text,
          and the target server is not authenticated.</para>

          <para>To overcome this vulnerability the authentication protocol may
          be run over a SSL session that ensures that all message contents are
          protected for confidentiality.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <info>
        <title>Authentication with certificate and Tomcat 6</title>
      </info>

      <para><itemizedlist>
          <para>In this case, users will not have to enter a login/password.
          They will just present their certificates and authentication is
          performed transparently by the browser (after the user has imported
          his certificate into it). Therefore, the identity presented to the
          server is not a login, but a Distinguished Name(DN).</para>

          <listitem>
            <para xml:id="config.jonas-realm">jonas-realm
            configuration:</para>

            <para>The name identifying the person to whom the certificate
            belongs looks like the following: CN=Someone Unknown,
            OU=ObjectWeb, O=JOnAS, C=ORG with:</para>

            <para>CN : Common Name</para>

            <para>OU : Organizational Unit</para>

            <para>O : Organization</para>

            <para>C : Country Name</para>

            <para>E : Email Address</para>

            <para>L : Locality</para>

            <para>ST :State or Province Name</para>

            <para>The Subject in a certificate contains the main attributes
            and may include additional ones, such as Title, Street Address,
            Postal Code, Phone Number.</para>

            <para>In the jonas-realm.xml a user with password looks
            like:<screen>&lt;user name="jps_admin" password="admin" roles="administrator"/&gt;</screen>A
            certificate-based user must have its DN preceded by the String:
            ##DN## example:<screen>&lt;user name="##DN##CN=whale, OU=ObjectWeb, O=JOnAS, L=JOnAS, ST=JOnAS, C=ORG"
      password="" roles="jadmin" /&gt;</screen></para>
          </listitem>

          <listitem>
            <para>Tomcat Realm configuration:</para>

            <para>The current Realm in $JONAS_BASE/conf/tomcat6-server.xml
            must be replaced by:</para>

            <screen>&lt;Server&gt;
[...]
&lt;Realm className="org.ow2.jonas.web.tomcat6.security.Realm" /&gt;
[...]
&lt;/Server&gt;</screen>

            <para>The class specified uses the JAAS model to authenticate the
            users. Thus, to choose the correct realm to be used for
            authentication, JAAS must be configured see in <xref
            linkend="config.JAAS" />.</para>
          </listitem>

          <listitem>
            <para>Tomcat SSL configuration:</para>

            <para>The following example of &lt;connector&gt; element must be
            uncommented in $JONAS_BASE/conf/tomcat6-server.xml and customized
            (if necessary):</para>

            <screen>&lt;Server&gt;
[...]
&lt;!-- Define a SSL Coyote HTTP/1.1 Connector on port 9043 --&gt;
    &lt;!--
    &lt;Connector port="9043" maxHttpHeaderSize="8192"
               maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
               enableLookups="false" disableUploadTimeout="true"
               acceptCount="100" scheme="https" secure="true"
               clientAuth="false" sslProtocol="TLS" /&gt;
    --&gt;
[...]
&lt;/Server&gt;</screen>

            <para>A complete description of SSL configuration can be found in
            <link
            xlink:href="http://tomcat.apache.org/tomcat-5.5-doc/ssl-howto.html">SSL
            Configuration HOW-TO</link></para>
          </listitem>

          <listitem>
            <para xml:id="config.webapp2">Webapp configuration:</para>

            <para>In the <filename>web.xml</filename>of the web application a
            <emphasis>Client Certificate Authentication Configuration
            </emphasis>must be set, a security-constraint may be used if
            needed; example:</para>

            <screen>&lt;web-app&gt;
   &lt;login-config&gt;
        &lt;auth-method&gt;CLIENT-CERT&lt;/auth-method&gt;
        &lt;realm-name&gt;Example Authentication Area&lt;/realm-name&gt;
   &lt;/login-config&gt;

   &lt;security-constraint&gt;
   ..
     &lt;user-data-constraint&gt;
     &lt;transport-guarantee&gt;CONFIDENTIAL&lt;/transport-guarantee&gt;
     &lt;/user-data-constraint&gt;
   &lt;/security-constraint&gt;
&lt;/web-app&gt;</screen>
          </listitem>
        </itemizedlist></para>
    </section>

    <section>
      <info>
        <title>Servlet Authentication with User/password and Jetty 6.x</title>
      </info>

      <itemizedlist>
        <listitem>
          <para>Jetty configuration</para>

          <para>A web-jetty.xml file must be provided in the <filename
          class="directory">WEB-INF</filename> directory in the <filename
          class="extension">.war</filename> file in which a security
          interceptor
          <classname>org.ow2.jonas.web.jetty6.security.Realm</classname> form
          is specified instead of the default one:</para>

          <screen>&lt;Configure class="org.mortbay.jetty.webapp.WebAppContext"&gt;
  &lt;Call name="setRealmName"&gt;
    &lt;Arg&gt;Example Basic Authentication Area&lt;/Arg&gt;
  &lt;/Call&gt;
  &lt;Call name="setRealm"&gt;
    &lt;Arg&gt;
      &lt;New class="org.ow2.jonas.web.jetty6.security.Realm"&gt;
        &lt;Arg&gt;Example Basic Authentication Area&lt;/Arg&gt;
        &lt;Arg&gt;memrlm_1&lt;/Arg&gt;
      &lt;/New&gt;
    &lt;/Arg&gt;
  &lt;/Call&gt;
&lt;/Configure&gt;</screen>
        </listitem>

        <listitem>
          <para>webapp configuration:</para>

          <para>is similar to the webapp configuration with Tomcat see <xref
          linkend="config.webapp1" />.</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <info>
        <title>Authentication with certificate and Jetty 6.x</title>
      </info>

      <para></para>

      <itemizedlist>
        <listitem>
          <para>Jetty Realm configuration:</para>

          <para>Edit the web-jetty.xml file under WEB-INF directory in the
          .war file to declare a Realm name and a Realm:</para>

          <screen>&lt;Configure class="org.mortbay.jetty.webapp.WebAppContext"&gt;
...
!-- Set the same realm name as the one specified in &lt;realm-name&gt; in &lt;login-config&gt;
    in the web.xml file of your web application --&gt;
&lt;Call name="setRealmName"&gt;
  &lt;Arg&gt;Example Authentication Area&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- Set the class Jetty has to use to authenticate the user and a title name for
     the pop-up window --&gt;
&lt;Call name="setRealm"&gt;
  &lt;Arg&gt;
    &lt;New class="org.ow2.jonas.web.jetty6.security.Realm"&gt;
      &lt;Arg&gt;JAAS on Jetty&lt;/Arg&gt;
    &lt;/New&gt;
  &lt;/Arg&gt;
&lt;/Call&gt;
...
&lt;/Configure&gt;</screen>

          <para>The class specified uses the JAAS model to authenticate the
          users. Thus, to choose the correct <emphasis>realm</emphasis> to be
          used for authentication, JAAS must be configured, see in <xref
          linkend="config.JAAS" />.</para>
        </listitem>

        <listitem>
          <para>Jetty SSL configuration:</para>

          <para>In the global deployment descriptor of Jetty (the jetty6.xml
          file), located in the $JONAS_BASE/conf directory, uncomment this
          part:</para>

          <para><screen> &lt;!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --&gt;
  &lt;!-- Add a HTTPS SSL listener on port 9043                           --&gt;
  &lt;!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --&gt;
  &lt;!-- UNCOMMENT TO ACTIVATE
  &lt;Call name="addListener"&gt;
    &lt;Arg&gt;
      &lt;New class="org.mortbay.http.SunJsseListener"&gt;
        &lt;Set name="Port"&gt;9043&lt;/Set&gt;
        &lt;Set name="MinThreads"&gt;5&lt;/Set&gt;
        &lt;Set name="MaxThreads"&gt;100&lt;/Set&gt;
        &lt;Set name="MaxIdleTimeMs"&gt;30000&lt;/Set&gt;
        &lt;Set name="LowResourcePersistTimeMs"&gt;2000&lt;/Set&gt;
        &lt;Set name="Keystore"&gt;&lt;SystemProperty name="jetty.home" default="."/&gt;/etc/demokeystore&lt;/Set&gt;
  &lt;Set name="Password"&gt;OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4&lt;/Set&gt;
  &lt;Set name="KeyPassword"&gt;OBF:1u2u1wml1z7s1z7a1wnl1u2g&lt;/Set&gt;
      &lt;/New&gt;
    &lt;/Arg&gt;
  &lt;/Call&gt;
  --&gt;
</screen> A complete description of howto configure SSL for Jetty may be founf
          <link
          xlink:href="http://jetty.mortbay.org/jetty5/faq/faq_s_400-Security_t_ssl.html">here</link></para>
        </listitem>

        <listitem>
          <para>webapp configuration</para>

          <para>is similar to the <link linkend="config.webapp2">webapp
          configuration with Tomcat</link></para>
        </listitem>

        <listitem>
          <para>jonas-realm configuration</para>

          <para>is similar to the <link
          linkend="config.jonas-realm">jonas-realm configuration with
          Tomcat</link></para>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section>
    <info>
      <title>Client container Authentication</title>
    </info>

    <para>To enable authentication mechanism in a client container it is
    necessary to</para>

    <itemizedlist>
      <listitem>
        <para>choose a <emphasis>callback handler</emphasis></para>

        <para>Callback handlers are responsible to get the user identity and
        to store it.</para>

        <para>The choice of the <emphasis>callback handler</emphasis> is done
        in the <filename>application-xml </filename>file, for example:</para>

        <screen>&lt;application-client&gt;
  &lt;callback-handler&gt;org.ow2.jonas.security.auth.callback.LoginCallbackHandler&lt;/callback-handler&gt;
&lt;/application-client&gt;</screen>

        <para>JOnAS provides several <emphasis>callback handlers<footnote>
            <para>all these handlers are defined in the package
            <classname>org.ow2.jonas.security.auth.callback</classname></para>
          </footnote>:</emphasis></para>

        <itemizedlist>
          <listitem>
            <para><classname>LoginCallbackHandler</classname> : it is a text
            based handler that gets the user and password via stdin</para>
          </listitem>

          <listitem>
            <para><classname>DialogCallbackHandler:</classname> handler using
            a Swing dialog window to query user and password</para>
          </listitem>

          <listitem>
            <para><classname>NoInputCallbackHandler</classname>: is
            responsible to store a user/password</para>
          </listitem>

          <listitem>
            <para><classname>CertificateCallback</classname>: is responsible
            to store a certificate</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>configure JASS for setting the LoginModules to be used to
        perform authentication see <xref linkend="config.JAAS" /><varname
        remap="structname"></varname></para>
      </listitem>
    </itemizedlist>

    <para>In the <filename
    class="directory">$JONAS_ROOT/examples/java</filename>ee5-earsample
    directory can be found examples of clients using JAAS authentication as
    well as one java client without container client that uses also
    JAAS.</para>
  </section>

  <section xml:id="config.JAAS">
    <info>
      <title>JAAS configuration</title>
    </info>

    <para>The JAAS configuration is made via the <emphasis>JAAS Login
    Configuration File</emphasis></para>

    <para>A login configuration file consists of one or more entries, each
    specifying which underlying authentication technology should be used for a
    particular application or applications.</para>

    <para>The contents of the JAAS configuration file has the structure
    below:</para>

    <para><screen>Application_1 {
  LoginModuleClassA Flag Options;
  LoginModuleClassB Flag Options;
  LoginModuleClassC Flag Options;
};

Application_2  {
  LoginModuleClassB Flag Options;
  LoginModuleClassC Flag Options;
};

Other {
  LoginModuleClassC Flag Options;
  LoginModuleClassA Flag Options;
};
  </screen></para>

    <para>There is a flag associated with all the LoginModules to configure
    their behaviour in case of success or failure:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis role="bold">required</emphasis> - The LoginModule is
        required to succeed. If it succeeds or fails, authentication still
        proceeds through the LoginModule list.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">requisite</emphasis> - The LoginModule is
        required to succeed. If it succeeds, authentication continues through
        the LoginModule list. If it fails, control immediately returns to the
        application (authentication does not proceed through the LoginModule
        list).</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">sufficient </emphasis>- The LoginModule is
        not required to succeed. If it does succeed, control immediately
        returns to the application (authentication does not proceed through
        the LoginModule list). If it fails, authentication continues through
        the LoginModule list.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">optional</emphasis> - The LoginModule is
        not required to succeed. If it succeeds or fails, authentication still
        proceeds through the LoginModule list.</para>
      </listitem>
    </itemizedlist>

    <section>
      <info>
        <title>Default JAAS configuration</title>
      </info>

      <para>JOnAS provides in
      <filename>$JONAS_BASE/conf/jaas.config</filename> a <emphasis>JAAS Login
      Configuration File</emphasis> already configured with some login
      configuration.</para>

      <para>There are two requirements: the entry dedicated to Tomcat must be
      named <emphasis role="bold">tomcat</emphasis>, and the entry for Jetty,
      <emphasis role="bold">jetty.</emphasis> Note that everything in this
      file is case-sensitive.</para>

      <para>The predifined entries are:</para>

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">tomcat</emphasis> used for
          authentication with the web container Tomcat</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">jetty</emphasis> used for authentication
          with the web container Jetty</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">jaasclient</emphasis> may be used for
          autentication in a fat client</para>
        </listitem>
      </itemizedlist>

      <para>The default configuration for the web container Tomcat is the
      following:</para>

      <screen>tomcat {
    org.ow2.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"
    ;
};</screen>

      <para>this indicates that the
      <classname>JResourceLoginModule</classname> Login Module must be used on
      the memory realm named <literal>memrlm_1.</literal></para>

      <para>The default configuration for the web container Jetty is the same
      than the previous:</para>

      <screen>jetty {
    org.ow2.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"
    ;
};</screen>

      <para>the configuration for the container clients examples :</para>

      <screen>jaasclient {
    // Login Module to use for the example jaasclient.

    org.ow2.jonas.security.auth.spi.JResourceLoginModule required
    resourceName="memrlm_1"

    org.ow2.jonas.security.auth.spi.ClientLoginModule  required
    globalCtx="true"
    ;
};</screen>

      <para>Here two Login Modules are used, one for checking the identity in
      the memoty realm, the second for propagating a security context with the
      client request.</para>

      <para>To change the location and name of the
      <filename>jaas.config</filename> file, edit the
      <filename>$JONAS_BASE/bin/jonas</filename> script and modify the
      following line:<screen>-Djava.security.auth.login.config=$JONAS_BASE/conf/jaas.config</screen></para>
    </section>

    <section>
      <info>
        <title>JOnAS LoginModules</title>
      </info>

      <para>JOnAS provides some predefined LoginModules:</para>

      <variablelist>
        <varlistentry>
          <term>JResourceLoginModule</term>

          <listitem>
            <para>This is the main LoginModule. It is highly recommended that
            this one be used in every authentication, as it checks the user
            authentication information in the specified realm database, LDAP
            or memory.</para>

            <para>This LoginModule delegates the authentication to the server
            . Here are the possible attributes to set:</para>

            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry align="center">attribute name</entry>

                    <entry align="center">description</entry>
                  </row>

                  <row>
                    <entry>resourceName</entry>

                    <entry>name of the realm</entry>
                  </row>

                  <row>
                    <entry>serverName</entry>

                    <entry>name of JOnAS instance (default value=
                    jonas)</entry>
                  </row>

                  <row>
                    <entry>useUpperCaseUsername</entry>

                    <entry>if true Convert the username into uppercase for the
                    authentication (default value=false)</entry>
                  </row>

                  <row>
                    <entry>certCallback</entry>

                    <entry>if true use certificate callback</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>

            <para></para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>CRLLoginModule</term>

          <listitem>
            <para>This LoginModule contains authentication based on
            certificates. However, when enabled, it will also permit
            non-certificate based accesses. It verifies that the certificate
            presented by the user has not been revoked by the Certification
            Authority that signed it. To use it, the directory in which to
            store the revocation lists (<emphasis>CRLs</emphasis>) files or an
            LDAP repository must exist.</para>

            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry align="center">attribute name</entry>

                    <entry align="center">description</entry>
                  </row>

                  <row>
                    <entry>CRLsResourceName</entry>

                    <entry>specifies how the <emphasis>CRLs </emphasis>are
                    stored:Two possible values "Directory" or "LDAP"</entry>
                  </row>

                  <row>
                    <entry>CRLsDirectoryName</entry>

                    <entry>The directory containing the
                    <emphasis>CRL</emphasis> files (the extension for these
                    files must be<filename class="extension">
                    .crl</filename>).</entry>
                  </row>

                  <row>
                    <entry>address</entry>

                    <entry>address of the server that hosts the LDAP
                    repository</entry>
                  </row>

                  <row>
                    <entry>port</entry>

                    <entry>port used by the LDAP repository; <emphasis>CRLs
                    </emphasis>are retrieved from an LDAP directory using the
                    LDAP schema defined in <link
                    xlink:href="http://www.ietf.org/rfc/rfc2587.txt">RFC
                    2587</link></entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>SignLoginModule</term>

          <listitem>
            <para>login module that signs the current Subject ,. Here are the
            possible attributes to set:</para>

            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry align="center">attribute name</entry>

                    <entry align="center">description</entry>
                  </row>

                  <row>
                    <entry>keystoreFile</entry>

                    <entry>Name of the key store</entry>
                  </row>

                  <row>
                    <entry>keystorePass</entry>

                    <entry>password for the keystore</entry>
                  </row>

                  <row>
                    <entry>keyPass</entry>

                    <entry>password for the private key</entry>
                  </row>

                  <row>
                    <entry>alias</entry>

                    <entry>alias</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>ClientLoginModule</term>

          <listitem>
            <para>login module used for propagating the Principal and roles to
            the server, it doesn't make any authentication. This login module
            must be used when authentication for a client container. Here is
            the possible attribute to set:</para>

            <informaltable>
              <tgroup cols="2">
                <tbody>
                  <row>
                    <entry align="center">attribute name</entry>

                    <entry align="center">description</entry>
                  </row>

                  <row>
                    <entry>globalCtx</entry>

                    <entry>if true set the security context for all the
                    threads of the client container instead of only on the
                    current thread. Useful for swing client. (default value=
                    false)</entry>
                  </row>
                </tbody>
              </tgroup>
            </informaltable>
          </listitem>
        </varlistentry>
      </variablelist>

      <para></para>
    </section>
  </section>
</section>
