Authentication

From Stax

Stax supports the standard Servlet API mechanisms for enabling application authentication using the login-config elements in web.xml. Stax currently relies on the underlying Tomcat Realms implementation for authentication. The following guide will show you how to configure a DataSourceRealm for authenticating your application users.

Contents 1 Create a new User Database 2 Defining the Application Realm 3 Configure a login mechanism 3.1 Basic Authentication 3.2 Form Authentication 4 Protecting Resource URLs

Create a new User Database

• Login to the Stax application console, and create a new database
• Register the database as a DataSource in stax-application.xml [cloudbees-web.xml] (refer to the DB's cribsheet panel)

<resource name="jdbc/DATASOURCE_NAME" auth="Container" type="javax.sql.DataSource">
 <param name="username" value="STAX_DB_USERNAME" />
 <param name="password" value=""STAX_DB_USERNAME" />
 <param name="url" value="jdbc:stax://STAX_DB_NAME" />
</resource>

• Initialize the database with a user/role schema by executing the following SQL

create table users (
 user_name         varchar(15) not null primary key,
 user_pass         varchar(15) not null
);
create table user_roles (
 user_name         varchar(15) not null,
 role_name         varchar(15) not null,
 primary key (user_name, role_name)
);

Insert some users into the users table, and register them with some roles

insert into users (user_name, user_pass) values ('user1', 'mypass');
insert into user_roles (user_name, role_name) values ('user1', 'member');

Defining the Application Realm

To define the realm that will perform authentication using the new user database, you need to add the following XML snippet to your Stax application deployment descriptor (stax-application.xml or stax-web.xml).

<realm>
 <param name="className" value="org.apache.catalina.realm.DataSourceRealm" />
 <param name="dataSourceName" value="jdbc/DATASOURCE_NAME" />
 <param name="localDataSource" value="true" />
 <param name="userTable" value="users" />
 <param name="userNameCol" value="user_name" />
 <param name="userCredCol" value="user_pass" />
 <param name="userRoleTable" value="user_roles" />
 <param name="roleNameCol" value="role_name" />
</realm>

Configure a login mechanism

At this point, your application should be ready to use the authentication realm. Now, you just need to update your web.xml to specify how you'd like to prompt users to login, and which URLs you want to protect. This is done by using the standard Servlet API mechanisms.

Basic Authentication

If you want users to be prompted to login using the standard browser login dialog, then add the following XML to your web.xml file.

<login-config>
 <auth-method>BASIC</auth-method>
</login-config>

Form Authentication

If you want users to be prompted to login using a custom login form, then add the following XML to your web.xml file.

<login-config>
 <auth-method>FORM</auth-method>
 <form-login-config>
  <form-login-page>/loginForm.jsp</form-login-page>
  <form-error-page>/loginError.jsp</form-error-page>
 </form-login-config>
</login-config>

Your custom form (loginForm.jsp based on the above configuration) then needs to provide the j_username and j_password form fields and submit to the j_security_check URL:

<form action='j_security_check' method='post'>
 Username: <input type='text' name='j_username'>
 Password: <input type='text' name='j_password'>
 <input type='submit' value='login'> 
</form>

Known issue: Form logins do not currently work in clustered configurations

Protecting Resource URLs

To protect a given set of URLs using Servlet authentication, you need to configure Security Contraints in web.xml to protect a set of URL patterns so that only users in the specified role can access them.

<security-constraint>
 <web-resource-collection>
  <web-resource-name>Secure Files</web-resource-name>
   <url-pattern>/secure/*</url-pattern>
  </web-resource-collection>
  <auth-constraint>  
    <role-name>member</role-name>
  </auth-constraint>
</security-constraint>

(You must specify some URLs to protect - if you do not, then the login-config specified above will not do anything)