| Red Hat Docs > Manuals > Red Hat Web Application Framework > |
|
The intended audience for this document is developers who want to understand, configure, or extend the Red Hat Web Application Framework authentication system. Red Hat Web Application Framework is designed to support a variety of authentication technologies using Pluggable Authentication (PAM). Administrators can configure Red Hat Web Application Framework to use any of the provided login modules, or they can define and use new modules. Red Hat Web Application Framework uses the Java Authentication and Authorization (JAAS) API and supports new login modules that implement this API.
This tutorial describes the provided login modules and explains how to implement new modules. It assumes familiarity with PAM and the JAAS API.
All Red Hat Web Application Framework Java classes related to pluggable authentication are located in the com.arsdigita.kernel.security package.
The classes that make up the authentication system include:
com.arsdigita.kernel.security.LoginContext An in-house implementation of JAAS's LoginContext . This class is needed due to a bug in JAAS 1.0 that prevents LoginModules from being loaded through web servlets. This bug will be fixed in JDK 1.4. This implementation behaves just like the JAAS implementation in all known respects.
com.arsdigita.kernel.security.LoginConfig Parses the loginConfig for the kernel.security.Initializer into a JAAS Configuration. Defines which login modules are used when logging in a user.
com.arsdigita.kernel.security.PartyPrincipal A Java Principal that stores an ID number, such as a Red Hat Web Application Framework user ID.
com.arsdigita.kernel.security.AdminLoginModule This module is used to allow administrators to log in as other users. This module succeeds if the Subject contains a PartyPrincipal. Because of this, PartyPrincipals should be added to Subjects with extreme care; UserContext checks the current user's privileges before allowing this module to succeed. This module may be changed in the future to do the privilege check itself.
com.arsdigita.kernel.security.PasswordLoginModule Abstract superclass of login modules that authenticate a user from a username and password. Subclasses should override checkPassword(username, password) appropriately.
com.arsdigita.kernel.security.LocalLoginModule A PasswordLoginModule that checks a username and password using the Red Hat Web Application Framework database.
com.arsdigita.kernel.security.MappingLoginModule Abstract superclass of login modules that map usernames to Red Hat Web Application Framework user IDs. Subclasses should override getUserID(username) appropriately. If authentication succeeds, this class adds a PartyPrincipal containing the mapped user ID to the Subject.
com.arsdigita.kernel.security.UserIDLoginModule A MappingLoginModule that maps a username to a user ID using the Red Hat Web Application Framework database.
com.arsdigita.kernel.security.CredentialManager Provides methods to get, set, and delete a string value from an HTTP request and response. Used by CredentialLoginModule to persist the credential value between requests.
com.arsdigita.kernel.security.CookieManager A CredentialManager that loads and saves its value in a cookie. If the user requests a "forever" login, the cookie is set to expire in three years; otherwise, the cookie will be deleted when the user closes their browser.
com.arsdigita.kernel.security.URLManager A CredentialManager that loads and saves its value in a URL parameter. This parameter is automatically inserted into every link and form presented to the User, so that it continues frm request to request.
com.arsdigita.kernel.security.CredentialLoginModule Abstract superclass of login modules that check whether a user presents a valid authentication credential. If the user does not have a credential but authenticates successfully using some other module, this module sets a new credential. This class uses a CredentialManager instance to get, set, and delete the credential value from the HTTP request and response.
com.arsdigita.kernel.security.UserLoginModule A CredentialLoginModule that authenticates a user by reading the user ID from a credential. Invalidates the user's session if the client logs in with a different user ID than the credential contains.
com.arsdigita.kernel.security.CookieLoginModule A UserLoginModule that uses a CookieManager to authenticate the user from a cookie.
com.arsdigita.kernel.security.URLLoginModule A CredentialLoginModule that uses a URLManager to authenticate the user from a URL parameter.
com.arsdigita.kernel.security.SessionLoginModule A CredentialLoginModule that tracks a user's session by reading the session ID from a credential. The session credential includes a cryptographic hash of the session ID assigned by the servlet, so this login module can detect when a client attempts to hijack another user's session.
com.arsdigita.kernel.security.SessionCookieLoginModule A SessionLoginModule that uses a CookieManager to track the user's session ID using a cookie.
com.arsdigita.kernel.security.SessionURLLoginModule A SessionLoginModule that uses a URLManager to track the user's session ID using a URL parameter.
com.arsdigita.kernel.security.RecoveryLoginModule A UserLoginModule that uses a URLManagerto authenticate the user using a URL parameter. This model allows users to change their password without entering their old one first (used to recover from forgotten passwords). To allow a user to recover, send the user to the change-password page with the URL parameter named getParamName() set to the value returned by getParamValue(). This should only be done once the system has verified that the user is who they claim to be, say by answering their password question correctly. This URL parameter does not automatically propagate to subsequent requests, since the recovery login should only be used for password recovery.
Red Hat Web Application Framework authenticates users at two times: upon each HTTP request and at the registration page. The Request login is automatic and uses information stored in the user's HTTP request, such as form variables, HTTP authentication parameters, URL parameters, and cookies. The Register login is interactive and uses a username and password provided by the user (although it can also access the HTTP request).
The configuration for both logins is defined in the loginConfig entry under the kernel.security.Initializer in enterprise.init. The syntax for this configuration is described in the LoginConfig constructor documentation.
The default Request configuration requires that AdminLoginModule, RecoveryLoginModule, or CookieLoginModule succeed. If all fail, the user is not logged in, but the request continues. If any succeed, the user is logged in and the user's authentication cookie is refreshed, if needed.
The default Register configuration first runs LocalLoginModule, which succeeds if the user enters a valid username and password. UserIDLoginModule then translates the given username into a Red Hat Web Application Framework user ID. Finally, CookieLoginModule sets a new cookie for the user, if needed.
If the user enters a bad password, LocalLoginModule throws a FailedLoginException, which causes the user to receive a "Bad Password" error. If the user does not exist, LocalLoginModule (or UserIDLoginModule) throws an AccountNotFoundException, which causes the user to be redirected to a "New User" page. Any login module can throw these exceptions to get the same results. If any other LoginException is thrown, the user registration form displays an error.
Red Hat Web Application Framework provides alternate authentication technologies that can be configured by editing the login configuration in enterprise.init (see loginConfig above). To configure cookie-less login (needed for certain types of wireless clients), simply replace the instances of CookieLoginModule with URLLoginModule in the login configuration.
Session tracking is handled separately from authentication. Change the sessionTrackingMethod option from "cookie" to "url" for cookie-less session tracking. This automatically selects whether SessionCookieLoginModule or SessionURLLoginModule should be used for session tracking.
The main strength of Pluggable Authentication is that the system may be extended with new authentication technologies. This is done by implementing new LoginModules. For example, an LDAP server can be used to authenticate a user by username and password. To integrate this behavior into Red Hat Web Application Framework, a new login module (for example, LDAPLoginModule) must be defined.
LDAPLoginModule would replace LocalLoginModule in the login configuration. It needs its own configuration information to determine how to connect to the LDAP serve. This information can be hard-coded into the module, read from a file, provided by an Initializer, or passed as an option in the login configuration.
If the LDAP username does not match the Red Hat Web Application Framework username, another login module must be defined to map the LDAP username to a Red Hat Web Application Framework user ID. This module, (for example, LDAPUserLoginModule), would replace UserIDLoginModule and must implement MappingLoginModule.getUserID(username) appropriately.
Another way to change the way authentication works is to edit the sequence of login modules in the login configuration. By replacing, changing the order of, or changing the control flag of login modules in the login configuration, you can create a variety of authentication sequences (not all of which make sense or are secure, so be careful!). See the JAAS Configuration documentation for more information.