KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > caucho > server > security > ServletAuthenticator


1 /*
2  * Copyright (c) 1998-2006 Caucho Technology -- all rights reserved
3  *
4  * This file is part of Resin(R) Open Source
5  *
6  * Each copy or derived work must preserve the copyright notice and this
7  * notice unmodified.
8  *
9  * Resin Open Source is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License as published by
11  * the Free Software Foundation; either version 2 of the License, or
12  * (at your option) any later version.
13  *
14  * Resin Open Source is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
17  * of NON-INFRINGEMENT. See the GNU General Public License for more
18  * details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with Resin Open Source; if not, write to the
22  *
23  * Free Software Foundation, Inc.
24  * 59 Temple Place, Suite 330
25  * Boston, MA 02111-1307 USA
26  *
27  * @author Scott Ferguson
28  */
29
30 package com.caucho.server.security;
31
32 import javax.servlet.ServletContext JavaDoc;
33 import javax.servlet.ServletException JavaDoc;
34 import javax.servlet.http.HttpServletRequest JavaDoc;
35 import javax.servlet.http.HttpServletResponse JavaDoc;
36 import javax.servlet.http.HttpSession JavaDoc;
37 import java.security.Principal JavaDoc;
38
39 /**
40  * Used in conjunction with AbstractLogin to authenticate users in
41  * a servlet request. The ServletAuthenticator is typically responsible for
42  * the actual authentication and AbstractLogin is responsible for extracting
43  * credentials (user and password) from the request and returning any
44  * error pages. Since Login classes typically delegate to the Authenticator,
45  * the same authenticator can be used for "basic", "form" or a custom login.
46  *
47  * <p>In general, applications should extend AbstractAuthenticator instead
48  * to protect from API changes in the Authenticator.
49  *
50  * <p>The authenticator is configured using init-param in the resin.conf.
51  * For example, if test.MyAuthenticator defines a <code>setFoo</code> method,
52  * it can be configured with &lt;init-param foo='bar'/>.
53  *
54  * <code><pre>
55  * &lt;authenticator id='name'>
56  * &lt;class-name>test.MyAuthenticator&lt;/class-name>
57  * &lt;init-param foo='bar'/>
58  * &lt;/authenticator>
59  * </pre></code>
60  *
61  * <p>Authenticator instances can be specific to a web-app, host, or
62  * server-wide. If the authenticator is configured for the host, it
63  * is shared for all web-apps in that host, enabling single-signon.
64  *
65  * <code><pre>
66  * &lt;host id='foo'>
67  * &lt;authenticator id='myauth'>...&lt;/authenticator>
68  *
69  * &lt;web-app id='/a'>
70  * ...
71  * &lt;/web-app>
72  *
73  * &lt;web-app id='/a'>
74  * ...
75  * &lt;/web-app>
76  * &lt;/host>
77  * </pre></code>
78  */
79 public interface ServletAuthenticator {
80   /**
81    * Initialize the authenticator. <code>init()</code> is called after all
82    * the bean parameter have been set.
83    */
84   public void init()
85     throws ServletException JavaDoc;
86   
87   /**
88    * Logs a user in with a user name and a password. The login method
89    * is generally called during servlet security checks. The
90    * ServletRequest.getUserPrincipal call will generally call
91    * getUserPrincipal.
92    *
93    * <p>The implementation may only use the response to set cookies
94    * and headers. It may not write output or set the response status.
95    * If the application needs to send a custom error reponse,
96    * it must implement a custom AbstractLogin instead.
97    *
98    * @param request servlet request
99    * @param response servlet response, in case any cookie need sending.
100    * @param application servlet application
101    * @param user the user name.
102    * @param password the users input password.
103    *
104    * @return the logged in principal on success, null on failure.
105    */
106   public Principal JavaDoc login(HttpServletRequest JavaDoc request,
107                          HttpServletResponse JavaDoc response,
108                          ServletContext JavaDoc application,
109                          String JavaDoc user, String JavaDoc password)
110     throws ServletException JavaDoc;
111   
112   /**
113    * Gets the authenticated user for the current request. If the user
114    * has not logged in, just returns null.
115    *
116    * <p>getUserPrincipal is called in response to an application's call to
117    * HttpServletRequest.getUserPrincipal.
118    *
119    * <p>The implementation may only use the response to set cookies
120    * and headers. It may not write output.
121    *
122    * @param request the request trying to authenticate.
123    * @param response the response for setting headers and cookies.
124    * @param application the servlet context
125    *
126    * @return the authenticated user or null if none has logged in
127    */
128   public Principal JavaDoc getUserPrincipal(HttpServletRequest JavaDoc request,
129                                     HttpServletResponse JavaDoc response,
130                                     ServletContext JavaDoc application)
131     throws ServletException JavaDoc;
132   
133   /**
134    * Validates the user when using HTTP Digest authentication.
135    * DigestLogin will call this method. Most other AbstractLogin
136    * implementations, like BasicLogin and FormLogin, will use
137    * getUserPrincipal instead.
138    *
139    * <p>The HTTP Digest authentication uses the following algorithm
140    * to calculate the digest. The digest is then compared to
141    * the client digest.
142    *
143    * <code><pre>
144    * A1 = MD5(username + ':' + realm + ':' + password)
145    * A2 = MD5(method + ':' + uri)
146    * digest = MD5(A1 + ':' + nonce + A2)
147    * </pre></code>
148    *
149    * @param request the request trying to authenticate.
150    * @param response the response for setting headers and cookies.
151    * @param app the servlet context
152    * @param user the username
153    * @param realm the authentication realm
154    * @param nonce the nonce passed to the client during the challenge
155    * @param uri te protected uri
156    * @param qop
157    * @param nc
158    * @param cnonce the client nonce
159    * @param clientDigest the client's calculation of the digest
160    *
161    * @return the logged in principal if successful
162    */
163   public Principal JavaDoc loginDigest(HttpServletRequest JavaDoc request,
164                                HttpServletResponse JavaDoc response,
165                                ServletContext JavaDoc app,
166                                String JavaDoc user, String JavaDoc realm,
167                                String JavaDoc nonce, String JavaDoc uri,
168                                String JavaDoc qop, String JavaDoc nc, String JavaDoc cnonce,
169                                byte []clientDigset)
170     throws ServletException JavaDoc;
171   
172   /**
173    * Returns true if the user plays the named role.
174    *
175    * <p>This method is called in response to the
176    * HttpServletResponse.isUserInRole call and for security-constraints
177    * that check the use role.
178    *
179    * @param request the request testing the role.
180    * @param application the owning application
181    * @param user the user's Principal.
182    * @param role role name.
183    */
184   public boolean isUserInRole(HttpServletRequest JavaDoc request,
185                               HttpServletResponse JavaDoc response,
186                               ServletContext JavaDoc application,
187                               Principal JavaDoc user, String JavaDoc role)
188     throws ServletException JavaDoc;
189   
190   /**
191    * Logs the user out from the given request.
192    *
193    * <p>Called via the session.logout() method.
194    *
195    * @param session for timeout, the session timing out. null if force logout
196    */
197   public void logout(ServletContext JavaDoc application,
198              HttpSession JavaDoc session,
199                      String JavaDoc sessionId,
200                      Principal JavaDoc user)
201     throws ServletException JavaDoc;
202 }
203
Popular Tags