Index

auth-method

form-login-config

security-constraint

security-constraint/auth-constraint

security-constraint/user-data-constraint

security-constraint/web-resource-collection

<http-server>  <resource-ref> <res-ref-name>jdbc/auth</res-ref-name> <res-type>javax.sql.DataSource</res-type> <init-param driver-name="org.gjt.mm.mysql.Driver"/> <init-param url="jdbc:mysql://localhost:3306/test"/> </resource-ref> <login-config auth-method='form'> <form-login-config> <form-login-page>/login.html</form-login-page> <form-error-page>/error.html</form-error-page> </form-login-config>  <authenticator id='com.caucho.http.security.JdbcAuthenticator'> <password-query> SELECT password FROM LOGIN WHERE username=? </password-query> </authenticator> </login-config> </http-server>

auth-method

Selects the authentication method.

basic HTTP Basic 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 The form's mandatory action

j_username The user name

j_password The password

j_uri Optional Resin extension for the successful display page.

j_use_cookie_auth Optional Resin extension to allow cookie login.

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 ServletAuthenticator and AbstractAuthenticator. To protect your application from API changes, you should extend AbstractAuthenticator rather than implementing Authenticator directly.

The JdbcAuthenticator (com.caucho.http.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 resource-ref.

The following are the attributes for the JdbcAuthenticator:

pool-name The database pool. Looks in the application attributes first, then in the global database pools.

password-query A SQL query to get the user's password. The default query is given below.

cookie-auth-query A SQL query to authenticate the user by a persistent cookie.

cookie-auth-update A SQL update to match a persistent cookie to a user.

role-query A SQL query to determine the user's role. By default, all users are in role "user", but no others.

password-digest Specifies the digest algorithm and format (Resin 2.0.4)

<authenticator id='com.caucho.http.security.JdbcAuthenticator'> <pool-name>test</pool-name> <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>

Resin 2.0.4 adds the capability to store 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 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.

The authenticator will create a digest of the username and password. Since that digest is a byte array, it is then converted to a string.

MD5(username:password)

Using password-digest with XmlAuthenticator

<authenticator> <class-name>com.caucho.http.security.XmlAuthenticator</class-name> <init-param password-digest='MD5-base64'/> <init-param user='harry:Syvian7bcPDKI261QvH9Cw:user'/> </authenticator>

Of course, storing the digest password take a bit more work. When the user registers, the application needs to compute the digest to store it. You can use the PasswordDigest class to do that.

import com.caucho.http.security.PasswordDigest; ... PasswordDigest digest = new PasswordDigest(); digest.setAlgorithm("MD5"); digest.setFormat("base64"); String password = digest.getDigestPassword("harry", "quidditch");

security-constraint

Selects protected areas of the web site. Sites using authentication as an optional personalization feature will typically not use any security constraints.

Security constraints can also be custom classes.

<security-constraint> <web-resource-collection> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint role-name='user'> </security-constraint>

security-constraint/web-resource-collection

Specifies a collection os areas of the web site.

url-pattern url patterns describing the resource

method HTTP methods to be restricted.

security-constraint/auth-constraint

Requires that authenticated users fill the specified role. In Resin's JdbcAuthenticator, normal users are in the "user" role. Think of a role as a group of users.

role-name Roles which are allowed to access the resource.

security-constraint/user-data-constraint

Restricts access to secure transports, i.e. SSL

transport-guarantee Required transport properties. NONE, INTEGRAL, and CONFIDENTIAL are allowed values.