Application Authentication

CloudBees supports the standard Servlet API mechanisms for enabling application authentication using the login-config elements in web.xml. CloudBees 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.

This is separate to "privacy mode" where your app is locked down to CloudBees users in your account (which you can turn on at any time and it is taken care of for you).

Create a new User Database

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

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 application deployment descriptor (cloudbees-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>