Authentication with Resin

Authentication provides a method for a username and password combination to be provided by a user and then verified by the web server. By using Resin's Authenticator API for login support, applications can add security without writing an entire authentication library.

Resin provides a predefined XML authenticator for user and password lookup in an XML file and a database authenticator for lookup in a database using JDBC. If the predefined authentication methods are inadequate, Resin provides an API to write custom authentication code.

The easiest authenticator to understand is the XmlAuthenticator. It lets you put users and passwords directly in the configuration file. The following example uses "Basic" authentication for login. Basic authentication asks the browser to pop open a window prompting for a username and password. (Basic authentication is discouraged because it is not secure unless you use it with SSL, but it's the easiest example.) The only user defined here is "Harry Potter" and he has the password "quidditch". He also plays the "user" role.

Using the XmlAuthenticator

<web-app xmlns="http://caucho.com/ns/resin">

  ...

  <authenticator type="com.caucho.server.security.XmlAuthenticator">
    <init>
      <user>Harry Potter:quidditch:user</user>
      <password-digest>none</password-digest>
    </init>
  </authenticator>

  <login-config auth-method='basic'/>

  <security-constraint url-pattern='/users-only/*' role-name='user'/>

  ...

</web-app>

In the above example, the <security-constraint> checks for authorization. Only users playing the "user" role can access the /users-only directory.

Another often used authenticator is the JdbcAuthenticator, which uses usernames, passwords, and roles stored in a database.

<web-app xmlns="http://caucho.com/ns/resin">

  ...

  <!-- Resin-specific JdbcAuthenticator -->
  <authenticator type='com.caucho.server.security.JdbcAuthenticator'>
    <init>
      <data-source>test</data-source>
      <password-query>
        SELECT password FROM LOGIN WHERE username=?
      </password-query>
      <cookie-auth-query>
        SELECT username FROM LOGIN WHERE cookie=?
      </cookie-auth-query>
      <cookie-auth-update>
        UPDATE LOGIN SET cookie=? WHERE username=?
      </cookie-auth-update>
      <role-query>
        SELECT role FROM LOGIN WHERE username=?
      </role-query>
    </init>
  </authenticator>

  <login-config auth-method='basic'/>

  <security-constraint url-pattern='/users-only/*' role-name='user'/>

  ...

</web-app>

Configures the login class. The web.xml configuration describes the configuration in more detail.

The login can be customized by selecting the com.caucho.server.security.AbstractLogin. The type attribute will select that class. More sophisticated applications may want to add their own custom AbstractLogin class to replace the predefined values.

Typically a custom login would only be necessary if the application needed a custom way of extracting credentials from the request.

auth-method

Selects the authentication method.

auth-method values
auth-method Meaning

basic HTTP Basic authentication

digest HTTP Digest authentication

form Form-based authentication

form-login-config

Configures authentication for forms. The login form has specific parameters that the servlet engine's login form processing understands. If the login succeeds, the user will see the original page. If it fails, she will see the error page.

form-login-page The page to be used to prompt the user login none

form-error-page The error page for unsuccessful login none

internal-forward Use an internal redirect on success or a sendRedirect false

form-uri-priority If true, the form's j_uri will override a stored URI false

The form itself must have the action j_security_check. It must also have the parameters j_username and j_password. Optionally, it can also have j_uri and j_use_cookie_auth. j_uri gives the next page to display when login succeeds. j_use_cookie_auth allows Resin to send a persistent cookie to the user to make following login easier.

j_use_cookie_auth gives control to the user whether to generate a persistent cookie. It lets you implement the "remember me" button. By default, the authentication only lasts for a single session.

j_security_check Parameters
Parameter Meaning)

j_username The user name

j_password The password

j_uri Resin extension for the successful display page (Optional).

j_use_cookie_auth Resin extension to allow cookie login (Optional).

The following is an example of a servlet-standard login page:

<form action='j_security_check' method='POST'> <table> <tr><td>User:<td><input name='j_username'> <tr><td>Password:<td><input name='j_password'> <tr><td colspan=2>hint: the password is 'quidditch' <tr><td><input type=submit> </table> </form>

Specifies a class to authenticate users. This Resin-specific option lets you control your authentication. You can either create your own custom authenticator, or use Resin's JdbcAuthenticator.

The authenticator is responsible for taking the username and password and returning a UserPrincipal if the username and password match.

Users wanting to implement an authenticator should look at the JavaDoc for class com.caucho.server.security.ServletAuthenticator and class com.caucho.server.security.AbstractAuthenticator . To protect your application from API changes, you should extend AbstractAuthenticator rather than implementing Authenticator directly.

The XmlAuthenticator (com.caucho.serer.security.XmlAuthenticator), stores the authentication in either an xml file or in the configuration itself.

When configuring the XmlAuthenticator in the resin.conf (or web.xml), each user adds a new configured user. The value contains the username, password, and the roles the user plays.

XmlAuthenticator in resin.conf

<authenticator type="com.caucho.server.security.XmlAuthenticator">
  <init>
    <user>Harry Potter:quidditch:user,gryffindor</user>
    <user>Draco Malfoy:pureblood:user,slytherin</user>
    <password-digest>none</password-digest>
  </init>
</authenticator>

Because the plain text passwords in the example above are a serious security issue, most sites will use the password-digest attribute described below to protect the passwords.

attribute	meaning	default
user	specifies an allowed user. May be repeated.	none
password-digest	selects the signature method to protect the password	md5-base64
path	specifies a path to an XML file containing the users and passwords.	none
logout-on-session-timeout	If true, the user will be logged out when the session times out	true

The passwords can be specified in a separate *.xml file. The password file looks like:

password.xml
<authenticator> <user name='Harry Potter' password='quidditch' role='gryffindor'/> <user name='Draco Malfoy' password='pureblood' role='slytherin'/> </authenticator>

The JdbcAuthenticator (class com.caucho.server.security.JdbcAuthenticator ) asks a backend database for the password matching the user's name. It uses the DataSource specified by the pool-name option, or the JNDI java:comp/env/jdbc/db-pool by default. pool-name refers to a DataSource configured with database .

attribute	meaning	default
data-source	The database pool. Looks in the application attributes first, then in the global database pools.	none
password-query	A SQL query to get the user's password. The default query is given below.	see below
cookie-auth-query	A SQL query to authenticate the user by a persistent cookie.	none
cookie-auth-update	A SQL update to match a persistent cookie to a user.	none
role-query	A SQL query to determine the user's role. By default, all users are in role "user", but no others.	none
password-digest	Specifies the digest algorithm and format (Resin 2.0.4)	md5-base64
logout-on-session-timeout	If true, the user will be logged out when the session times out (Resin 2.0.6)	true

<web-app xmlns="http://caucho.com/ns/resin">

  ...

  <!-- Resin-specific JdbcAuthenticator -->
  <authenticator type='com.caucho.server.security.JdbcAuthenticator'>
    <init>
      <data-source>test</data-source>
      <password-query>
        SELECT password FROM LOGIN WHERE username=?
      </password-query>
      <cookie-auth-query>
        SELECT username FROM LOGIN WHERE cookie=?
      </cookie-auth-query>
      <cookie-auth-update>
        UPDATE LOGIN SET cookie=? WHERE username=?
      </cookie-auth-update>
      <role-query>
        SELECT role FROM LOGIN WHERE username=?
      </role-query>
    </init>
  </authenticator>

  <login-config auth-method='basic'/>

  <security-constraint url-pattern='/users-only/*' role-name='user'/>

  ...

</web-app>

AuthenticatorList (class com.caucho.server.security.AuthenticatorList ) is used to configure more than one authenticator in a list, each authenticator is tried in turn and if the authentication fails the next authenticator in the list is attempted.

  <authenticator type="com.caucho.server.security.AuthenticatorList">
    <init>
      <authenticator resin:type="com.caucho.server.security.XmlAuthenticator">
        <user>admin:NIHlOSafJN2H7emQCkOQ2w==:user,admin</user>
      </authenticator>

      <authenticator resin:type='com.caucho.server.security.JdbcAuthenticator'>
        <data-source>jdbc/users</data-source>
        <password-query>
          SELECT password FROM LOGIN WHERE username=?
        </password-query>
        <cookie-auth-query>
          SELECT username FROM LOGIN WHERE cookie=?
        </cookie-auth-query>
        <cookie-auth-update>
          UPDATE LOGIN SET cookie=? WHERE username=?
        </cookie-auth-update>
        <role-query>
          SELECT role FROM LOGIN WHERE username=?
        </role-query>
      </authenticator>
    </init>
  </authenticator>

  <login-config auth-method='basic'/>

  <security-constraint url-pattern='/users/*' role-name='user'/>
  <security-constraint url-pattern='/admin/*' role-name='admin'/>

Resin has the capability of storing the digest of a password instead of the password itself. By using the password digest, the application can avoid storing the password in a form that someone can read.

Setting <password-digest> of any authenticator extending class com.caucho.server.security.AbstractAuthenticator will create a digest of the password. The password-digest has two parts: the digest algorithm and the encoding format. "MD5-base64" is a typical digest format, and is the default for the Resin authenticators..

"Single signon" refers to allowing for a single login for more than one context, for example, logging in to all web-apps in a server at once. You can implement single signon by configuring the authenticator in the proper environment: web-app, host, or server. The login will last for all the web-apps in that environment.

The authenticator is a resource which is shared across its environment . For example, to configure the XML authenticator for all web-apps in foo.com, you might configure as follows:

Single Signon for foo.com

<resin xmlns="http://caucho.com/ns/resin">
  <server>
    <http port="8080"/>

    <host id="foo.com">
      <root-directory>/opt/foo.com</root-directory>

      <authenticator type="com.caucho.server.security.XmlAuthenticator">
        <init>
          
          <user>harry:uTOZTGaB6pooMDvqvl2LBu:user,gryffindor</user>
          <!-- password: pureblood -->
          <user>dmalfoy:yI2uN1l97Rv5E6mdRnDFDB:user,slytherin</user>
        </init>
      </authenticator>

      <web-app-deploy path="webapps"/>
    </host>
  </server>
</resin>

Any .war in the webapps directory will share the same signon for the host. You will still need to implement a login-config for each web-app.

The Login is primarily responsible for extracting the credentials from the request (typically username and password) and passing those to the ServletAuthenticator.

The Servlet API calls the Login in two contexts: directly from ServletRequest.getUserPrincipal(), and during security checking. When called from the Servlet API, the login class can't change the response. In other words, if an application calls getUserPrincipal(), the Login class can't return a forbidden error page. When the servlet engine calls authenticate(), the login class can return an error page (or forward internally.)

Normally, Login implementations will defer the actual authentication to a ServletAuthenticator class. That way, both "basic" and "form" login can use the same JdbcAuthenticator. Some applications, like SSL client certificate login, may want to combine the Login and authentication into one class.

Login instances are configured through bean introspection. Adding a public setFoo(String foo) method will be configured with the following login-config:

<login-config type="test.CustomLogin">
  <init>
    <foo>bar</bar>
  </init>
</login-config>