Caucho maker of Resin Server | Application Server (Java EE Certified) and Web Server


 

Resin Documentation

home company blog docs 
app server 
 Resin Server | Application Server (Java EE Certified) and Web Server
 

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>

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
ATTRIBUTEMEANINGDEFAULT
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-queryAn SQL query to authenticate the user by a persistent cookie.None
cookie-auth-updateA 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-timeoutIf 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>

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
ATTRIBUTEMEANINGDEFAULT
init-paramAdds a property to the LoginModule.None
login-moduleThe fully qualified class name of the LoginModule implementation.Required
logout-on-session-timeoutIf 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>

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

<resin:LdapAuthenticator> Attributes
ATTRIBUTEMEANINGDEFAULT
dn-prefixString to prepend to query before portion selecting user by name.None
dn-suffixString to append to query after portion selecting user by name.None
jndi-envAdd a property to the JNDI provider used for connecting to the LDAP server.See below
logout-on-session-timeoutIf true, the user will be logged out when the session times out.true
security-authenticationSets the Context.SECURITY_AUTHENTICATION for the LDAP environment.
security-principalSets the Context.SECURITY_PRINCIPAL for the LDAP environment.
security-credentialsSets 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-attributeThe attribute name to use in the query for matching the user.uid
password-attributeThe attribute name to use for obtaining the password.userPassword
urlThe 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>

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
ATTRIBUTEMEANINGDEFAULT
pathPath 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>

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.

ATTRIBUTEMEANINGDEFAULT
userSpecifies 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
pathSpecifies the path to an XML file containing users and passwords.None
logout-on-session-timeoutIf 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;
  }
}

Copyright © 1998-2015 Caucho Technology, Inc. All rights reserved. Resin ® is a registered trademark. Quercustm, and Hessiantm are trademarks of Caucho Technology.