Caucho Technology
  • 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>

    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-2011 Caucho Technology, Inc. All rights reserved.
    Resin ® is a registered trademark, and Quercustm, Ambertm, and Hessiantm are trademarks of Caucho Technology.