com.caucho.server.security

Interface ServletAuthenticator

All Known Subinterfaces:

ServletAuthenticator

All Known Implementing Classes:

AuthenticatorList

public interface ServletAuthenticator

Used in conjunction with AbstractLogin to authenticate users in a servlet request. The ServletAuthenticator is typically responsible for the actual authentication and AbstractLogin is responsible for extracting credentials (user and password) from the request and returning any error pages. Since Login classes typically delegate to the Authenticator, the same authenticator can be used for "basic", "form" or a custom login.

In general, applications should extend AbstractAuthenticator instead to protect from API changes in the Authenticator.

The authenticator is configured using init-param in the resin.conf. For example, if test.MyAuthenticator defines a setFoo method, it can be configured with <init-param foo='bar'/>.

 <authenticator url='scheme:param1=value1;param2=value2'>
   <init>
     <param3>value4</param3>
   </init>
 </authenticator>
 

Authenticator instances can be specific to a web-app, host, or server-wide. If the authenticator is configured for the host, it is shared for all web-apps in that host, enabling single-signon.

 <host id='foo'>
   <authenticator id='myauth'>...</authenticator>

   <web-app id='/a'>
     ...
   </web-app>

   <web-app id='/a'>
     ...
   </web-app>
 </host>
 

Method Summary

Modifier and Type	Method and Description
java.security.Principal	getUserPrincipal(HttpServletRequest request, HttpServletResponse response, ServletContext application) Gets the authenticated user for the current request.
void	init() Initialize the authenticator.
boolean	isUserInRole(HttpServletRequest request, HttpServletResponse response, ServletContext application, java.security.Principal user, java.lang.String role) Returns true if the user plays the named role.
java.security.Principal	login(HttpServletRequest request, HttpServletResponse response, ServletContext application, java.lang.String user, java.lang.String password) Logs a user in with a user name and a password.
java.security.Principal	loginDigest(HttpServletRequest request, HttpServletResponse response, ServletContext app, java.lang.String user, java.lang.String realm, java.lang.String nonce, java.lang.String uri, java.lang.String qop, java.lang.String nc, java.lang.String cnonce, byte[] clientDigset) Validates the user when using HTTP Digest authentication.
void	logout(ServletContext application, HttpSession session, java.lang.String sessionId, java.security.Principal user) Logs the user out from the given request.

Method Detail

init

void init()
   throws ServletException

Initialize the authenticator. init() is called after all the bean parameter have been set.

Throws:

ServletException

login

java.security.Principal login(HttpServletRequest request,
                              HttpServletResponse response,
                              ServletContext application,
                              java.lang.String user,
                              java.lang.String password)
                       throws ServletException

Logs a user in with a user name and a password. The login method is generally called during servlet security checks. The ServletRequest.getUserPrincipal call will generally call getUserPrincipal.

The implementation may only use the response to set cookies and headers. It may not write output or set the response status. If the application needs to send a custom error reponse, it must implement a custom AbstractLogin instead.

Parameters:

request - servlet request

response - servlet response, in case any cookie need sending.

application - servlet application

user - the user name.

password - the users input password.

Returns:

the logged in principal on success, null on failure.

Throws:

ServletException

getUserPrincipal

java.security.Principal getUserPrincipal(HttpServletRequest request,
                                         HttpServletResponse response,
                                         ServletContext application)
                                  throws ServletException

Gets the authenticated user for the current request. If the user has not logged in, just returns null.

getUserPrincipal is called in response to an application's call to HttpServletRequest.getUserPrincipal.

The implementation may only use the response to set cookies and headers. It may not write output.

Parameters:

request - the request trying to authenticate.

response - the response for setting headers and cookies.

application - the servlet context

Returns:

the authenticated user or null if none has logged in

Throws:

ServletException

loginDigest

java.security.Principal loginDigest(HttpServletRequest request,
                                    HttpServletResponse response,
                                    ServletContext app,
                                    java.lang.String user,
                                    java.lang.String realm,
                                    java.lang.String nonce,
                                    java.lang.String uri,
                                    java.lang.String qop,
                                    java.lang.String nc,
                                    java.lang.String cnonce,
                                    byte[] clientDigset)
                             throws ServletException

Validates the user when using HTTP Digest authentication. DigestLogin will call this method. Most other AbstractLogin implementations, like BasicLogin and FormLogin, will use getUserPrincipal instead.

The HTTP Digest authentication uses the following algorithm to calculate the digest. The digest is then compared to the client digest.

 A1 = MD5(username + ':' + realm + ':' + password)
 A2 = MD5(method + ':' + uri)
 digest = MD5(A1 + ':' + nonce + A2)
 

Parameters:

request - the request trying to authenticate.

response - the response for setting headers and cookies.

app - the servlet context

user - the username

realm - the authentication realm

nonce - the nonce passed to the client during the challenge

uri - te protected uri

qop -

nc -

cnonce - the client nonce

clientDigest - the client's calculation of the digest

Returns:

the logged in principal if successful

Throws:

ServletException

isUserInRole

boolean isUserInRole(HttpServletRequest request,
                     HttpServletResponse response,
                     ServletContext application,
                     java.security.Principal user,
                     java.lang.String role)
              throws ServletException

Returns true if the user plays the named role.

This method is called in response to the HttpServletResponse.isUserInRole call and for security-constraints that check the use role.

Parameters:

request - the request testing the role.

application - the owning application

user - the user's Principal.

role - role name.

Throws:

ServletException

logout

void logout(ServletContext application,
            HttpSession session,
            java.lang.String sessionId,
            java.security.Principal user)
     throws ServletException

Logs the user out from the given request.

Called via the session.logout() method.

Parameters:

session - for timeout, the session timing out. null if force logout

Throws:

ServletException