| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
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.
login-configConfigures 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 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-methodSelects the authentication method.
form-login-configConfigures 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.
The form itself must have the action . It must also have the parameters and . Optionally, it can also have and . gives the next page to display when login succeeds. allows Resin to send a persistent cookie to the user to make following login easier.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.
The following is an example of a servlet-standard login page:
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 adds a new configured user. The value contains the username, password, and the roles the user plays.
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.
The passwords can be specified in a separate *.xml file. The password file looks like:
Sites should use password-digest to protect the passwords.
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 option, or the JNDI by default. refers to a DataSource configured with database . The following are the attributes for the JdbcAuthenticator:
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.
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.. The use of a password digest is more completely described in Digest Passwords .
"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:
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:
|