Orbeon Forms User Guide

Authentication

1. 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.

2. 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>).

    <security-constraint><web-resource-collection><web-resource-name>Administration</web-resource-name><url-pattern>/admin</url-pattern><url-pattern>/users</url-pattern></web-resource-collection><auth-constraint><role-name>administrator</role-name></auth-constraint></security-constraint>

  • 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:

    • The form action is set to j_security_check.
    • The name of the field used to get the username is j_username.
    • The name of the field used to get the password is j_password.
    <login-config><auth-method>FORM</auth-method><form-login-config><form-login-page>/login</form-login-page><form-error-page>/login-error</form-error-page></form-login-config></login-config>

  • In <login-config> the security roles used in <security-constraint> section are declared.

    <security-role><role-name>administrator</role-name></security-role>

3. 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.

4. 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 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>

5. 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.