Introduction
Most Web applications require some sort of authentication, either just to access an "administrative"
section, or for the whole application. Orbeon Forms Web applications use the standard authentication
mechanism provided by your J2EE application server. This section provides an overview of the standard
J2EE authentication mechanism.
Restricting access using web.xml
Access control is provided by adding three sections to the
web.xml file:
- In
<security-constraint> you define which role (with
<role-name>) is required to access which part of the
application (with <url-pattern>). - In
<login-config> you define how the user will
authenticate himself. In other words, what method is used to get the user name
and password. This can be done either with a form in an HTML page or with
standard HTTP authentication. The names of those methods are: FORM
and BASIC. In the example below, the form mechanism is
demonstrated. <form-login-page> must point to a page with an
HTML form where: - In
<login-config> the
security roles used in
<security-constraint> section are declared.
Mapping roles to users
In the web.xml file, the example declared that to access the page
/admin the user needs to have the administrator role. But
how do you declare users and how are those users mapped to roles? This is
application server dependent, so you won't find an exact answer to this question in
the Orbeon Forms User Guide and you should refer to your application server
documentation.
Usually the process is straightforward. For example, with Tomcat using the memory
realm, you can declare the users and their role in
conf/tomcat-users.xml:
<tomcat-users>
<user name="root" password="olleh" roles="administrator"/>
<user name="jdoh" password="olleh" roles="administrator"/>
</tomcat-users>
For more information on how to setup users and assign roles to users, see your
application server documentation. Links are provided below for Tomcat and WebLogic.
Accessing security information from the application
The Request Security processor extracts information about the currently logged user
from the client request. Its configuration contains a list of roles the application
developer is interested in. Only those roles will be listed in the processor's
output if the role is present. For instance, the output of the Request Security
processor could be:
<request-security>
<auth-type>FORM</auth-type>
<secure>true</secure>
<remote-user>scott</remote-user>
<user-principal>scott</user-principal>
<role>user</role>
</request-security>
The auth-type element contains either BASIC,
FORM, CLIENT_CERT, or DIGEST. The
secure element is true if the request was made using a secure channel,
such as HTTPS. See the Servlet
API for more information.
<p:processor xmlns:p="http://www.orbeon.com/oxf/pipeline" xmlns:xforms="http://www.w3.org/2002/xforms" name="oxf:request-security">
<p:input name="config">
<config>
<role>user</role>
<role>admin</role>
</config>
</p:input>
<p:output name="data" id="request-security"/>
</p:processor>
Logout
In order to log the current user out, the Session Invalidator processor must be
used:
<p:processor name="oxf:session-invalidator"/>
The Session Invalidator processor does not take any configuration or other inputs
and outputs. It must be included in a pipeline or branch of pipeline executed when
the action of logging out the user is requested.
