Resin Documentation

Aug 2012: Resin outscales C-based web server nginx in AutoBench benchmark
Feb 2012: NetCraft survey says Resin experiencing strong growth in last year and used in number of the Million Busiest Sites.

home company blog wiki docs
app server web server
health cloud java ee pro

resin 4.0

resin authenticators

The following are details on the authenticators that can be used with Resin, along with example code to utilize as a starting point for your applications:

<resin:DatabaseAuthenticator>
<resin:JaasAuthenticator>
<resin:LdapAuthenticator>
<resin:PropertiesAuthenticator>
<resin:XmlAuthenticator>
AbstractAuthenticator

<resin:DatabaseAuthenticator>

child of cluster,host,web-app

javadoc <resin:DatabaseAuthenticator>

The DatabaseAuthenticator asks a back-end relational database for the password matching a user's name. It uses the DataSource specified by the data-source attribute. data-source refers to an existing configured DataSource.

<resin:DatabaseAuthenticator> Attributes
ATTRIBUTE	MEANING	DEFAULT
data-source	The pooled JDBC data source. Looks in the application attributes first, then in the global database pools.	None
password-query	An SQL query to get the user's password given the user name. The default query is shown in the code example below.	See below
cookie-auth-query	An 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 used to secure the password (see following section in this document for details).	md5-base64
logout-on-session-timeout	If true, the user will be logged out when the session times out.	true

WEB-INF/resin-web.xml for DatabaseAuthenticator

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  <-- Authentication mechanism -->
  <resin:BasicLogin/>

  <-- Role-based authorization -->
  <resin:Allow url-pattern="/foo/*">
     <resin:IfUserInRole role="user"/>
  </resin:Allow>
  
  <-- The authenticator -->
  <resin:DatabaseAuthenticator'>
    <resin:data-source>test</resin:data-source>   
    <resin:password-query>
      SELECT password FROM login WHERE username=?
    </resin:password-query>
    <resin:cookie-auth-query>
      SELECT username FROM LOGIN WHERE cookie=?
    </resin:cookie-auth-query>    
    <resin:cookie-auth-update>
      UPDATE LOGIN SET cookie=? WHERE username=?
    </resin:cookie-auth-update>
    <resin:role-query>
      SELECT role FROM LOGIN WHERE username=?
    </resin:role-query>
  </resin:DatabaseAuthenticator>
</web-app>

<resin:JaasAuthenticator>

child of cluster,host,web-app

javadoc <resin:JaasAuthenticator>

The JaasAuthenticator uses a JAAS LoginModule for authentication. A common use of the JaasAuthenticator is to serve as an adapter for the large number of JAAS LoginModule's included in the Sun JDK for authentication purposes. However, the JAAS authenticator can be used with any valid JAAS login module.

<resin:JaasAuthenticator> Attributes
ATTRIBUTE	MEANING	DEFAULT
init-param	Adds a property to the LoginModule.	None
login-module	The fully qualified class name of the LoginModule implementation.	Required
logout-on-session-timeout	If true, the user will be logged out when the session times out.	true
password-digest	Specifies the digest algorithm and format used to secure the password (see following section in this document for details).	md5-base64

WEB-INF/resin-web.xml for JaasAuthenticator

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:JaasAuthenticator>
    <resin:login-module>com.sun.security.auth.module.Krb5LoginModule</resin:login-module>
    <resin:init-param>
      <debug>true</debug>
    </resin:init-param>
  </resin:JaasAuthenticator>
  ...
</web-app>

<resin:LdapAuthenticator>

child of cluster,host,web-app

javadoc <resin:LdapAuthenticator>

The LdapAuthenticator uses JNDI to connect to an LDAP (or Active Directory) server for authentication.

<resin:LdapAuthenticator> Attributes
ATTRIBUTE	MEANING	DEFAULT
dn-prefix	String to prepend to query before portion selecting user by name.	None
dn-suffix	String to append to query after portion selecting user by name.	None
jndi-env	Add a property to the JNDI provider used for connecting to the LDAP server.	See below
logout-on-session-timeout	If true, the user will be logged out when the session times out.	true
security-authentication	Sets the Context.SECURITY_AUTHENTICATION for the LDAP environment.
security-principal	Sets the Context.SECURITY_PRINCIPAL for the LDAP environment.
security-credentials	Sets the Context.SECURITY_CREDENTIALS for the LDAP environment.
password-digest	Specifies the digest algorithm and format used to secure the password (see following section in this document for details).	md5-base64
user-attribute	The attribute name to use in the query for matching the user.	uid
password-attribute	The attribute name to use for obtaining the password.	userPassword
url	The URL for the server.	ldap://localhost:389

WEB-INF/resin-web.xml for LdapAuthenticator

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:LdapAuthenticator password-digest="none">
    <resin:url>ldap://localhost:389</resin:url>
    <resin:dn-suffix>dc=hogwarts,dc=com</resin:dn-suffix>
  </resin:LdapAuthenticator>
  ...
</web-app>

jndi-env

jndi-env configures properties of the LDAP provider implementation. Prior to 3.1.1, the URL of the server is specified with jndi-env and the java.naming.provider.url property.

The following example shows the usage of the jndi-env configuration property:

WEB-INF/resin-web.xml LdapAuthenticator jndi-env

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:LdapAuthenticator password-digest="none">
    <resin:jndi-env java.naming.factory.initial="com.sun.jndi.ldap.LdapCtxFactory"/>
    <resin:jndi-env java.naming.provider.url="ldap://localhost:389"/>
    <resin:dn-suffix>dc=hogwarts,dc=com</dn-suffix>
  </resin:LdapAuthenticator>
  ...
<web-app>

<resin:PropertiesAuthenticator>

child of cluster,host,web-app

javadoc <resin:PropertiesAuthenticator>

The PropertiesAuthenticator allows you to use Java properties to store authentication information. This is very useful for a variety of applications such as very small sites, developement, unit testing or integration testing. You can either specify properties in-line in XML or via an external properties file.

<resin:PropertiesAuthenticator> Attributes
ATTRIBUTE	MEANING	DEFAULT
path	Path to the properties file.	None
password-digest	Specifies the digest algorithm and format used to secure the password (see following section in this document for details).	md5-base64

The following is an example of in-lining properties with the authenticator. This is useful for extremely simple web-sites maintained by developers as well as testing.

WEB-INF/resin-web.xml - in-line Properties

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:PropertiesAuthenticator password-digest="none">
     harry=quidditch,user,admin
     draco=mudblood,disabled,user
  </resin:PropertiesAuthenticator>
  ...
</web-app>

Alternatively, external properties files can be used as in the example below. This is useful for a simple site where authentication may be managed by administrators or non-technical users.

WEB-INF/resin-web.xml - File Property

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin"
  ...
  <resin:PropertiesAuthenticator path="WEB-INF/users.properties"/>
  ...
</web-app>

WEB-INF/users.properties

harry=/Tj/54ylCloUeMi2YQIVCQ===,user,admin

As the example indicates, the properties file includes the user as property name while the value is the password (that may be hashed as in the example or may be in plain-text) and any roles that are assigned to the user separated by commas. The password and role values are also separated by a comma.

<resin:XmlAuthenticator>

child of cluster,host,web-app

javadoc <resin:XmlAuthenticator>

In a similar vein to the properties authenticator, the XML authenticator allows you to store authentication information in XML - either in-line or in an external file. This authenticator has some of the same use-cases as the properties file authenticator, in a slight more human readable form, especially for a non-technical user.

ATTRIBUTE	MEANING	DEFAULT
user	Specifies a user authentication record. There maybe zero, one or more records.	None
password-digest	Specifies the digest algorithm and format used to secure the password (see following section in this document for details).	md5-base64
path	Specifies the path to an XML file containing users and passwords.	None
logout-on-session-timeout	If true, the user will be logged out when the session times out.	true

The following example uses in-line XML for authentication. When configuring the XmlAuthenticator in resin.xml (or resin-web.xml), each user adds a new configured user. The user value contains the username, password, and the roles for the user.

XmlAuthenticator in resin-web.xml

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:resin="urn:java:com.caucho.resin">
  ...
  <resin:XmlAuthenticator password-digest="none">
    <resin:user name="Harry Potter" password="quidditch" group="user,gryffindor"/>
    <resin:user name="Draco Malfoy" password="pureblood" group="user,slytherin"/>
  </resin:XmlAuthenticator>
  ...
</web-app>

This example shows how to use an external XML file for authentication:

WEB-INF/resin-web.xml - File XML

<web-app xmlns="http://caucho.com/ns/resin">
  ...
  <resin:XmlAuthenticator path="WEB-INF/users.xml"/>
  ...
</web-app>

WEB-INF/users.xml

<users>
  <user name="harry password="/Tj/54ylCloUeMi2YQIVCQ===" roles="user,admin"/>
<users>

AbstractAuthenticator

While this case is rare, it may sometimes be useful to create your own Resin custom authenticator (for example to use a legacy resource as an authentication store). The Resin security framework provides an abtract base class (com.caucho.security.AbstractAuthenticator) that you can extend to do this.

The following is a simple example that you can use a starting point for your application:

WEB-INF/resin-web.xml - Custom Authenticator Configuration

<web-app xmlns="http://caucho.com/ns/resin"
            xmlns:foo="urn:java:com.caucho.foo">
  ...
  <foo:MyAuthenticator>
    <foo:foo>bar</foo:foo>
  </foo:MyAuthenticator>
  ...
</web-app>

MyAuthenticator.java

package com.foo;

import com.caucho.security.AbstractAuthenticator;
import com.caucho.security.PasswordUser;

public class MyAuthenticator extends AbstractAuthenticator {
  private PasswordUser _user;

  public MyAuthenticator()
  {
    _user = new PasswordUser("harry", "quidditch",
                             new String[] { "user" });
  }

  public PasswordUser getUser(String userName)
  {
    if (userName.equals(_user.getName()))
      return _user;
    else
      return null;
  }
}