001: /*
002: * Copyright (c) 1998-2008 Caucho Technology -- all rights reserved
003: *
004: * This file is part of Resin(R) Open Source
005: *
006: * Each copy or derived work must preserve the copyright notice and this
007: * notice unmodified.
008: *
009: * Resin Open Source is free software; you can redistribute it and/or modify
010: * it under the terms of the GNU General Public License as published by
011: * the Free Software Foundation; either version 2 of the License, or
012: * (at your option) any later version.
013: *
014: * Resin Open Source is distributed in the hope that it will be useful,
015: * but WITHOUT ANY WARRANTY; without even the implied warranty of
016: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, or any warranty
017: * of NON-INFRINGEMENT. See the GNU General Public License for more
018: * details.
019: *
020: * You should have received a copy of the GNU General Public License
021: * along with Resin Open Source; if not, write to the
022: *
023: * Free Software Foundation, Inc.
024: * 59 Temple Place, Suite 330
025: * Boston, MA 02111-1307 USA
026: *
027: * @author Scott Ferguson
028: */
029:
030: package com.caucho.server.security;
031:
032: import javax.servlet.ServletContext;
033: import javax.servlet.ServletException;
034: import javax.servlet.http.HttpServletRequest;
035: import javax.servlet.http.HttpServletResponse;
036: import javax.servlet.http.HttpSession;
037: import java.security.Principal;
038:
039: /**
040: * Used in conjunction with AbstractLogin to authenticate users in
041: * a servlet request. The ServletAuthenticator is typically responsible for
042: * the actual authentication and AbstractLogin is responsible for extracting
043: * credentials (user and password) from the request and returning any
044: * error pages. Since Login classes typically delegate to the Authenticator,
045: * the same authenticator can be used for "basic", "form" or a custom login.
046: *
047: * <p>In general, applications should extend AbstractAuthenticator instead
048: * to protect from API changes in the Authenticator.
049: *
050: * <p>The authenticator is configured using init-param in the resin.conf.
051: * For example, if test.MyAuthenticator defines a <code>setFoo</code> method,
052: * it can be configured with <init-param foo='bar'/>.
053: *
054: * <code><pre>
055: * <authenticator url='scheme:param1=value1;param2=value2'>
056: * <init>
057: * <param3>value4</param3>
058: * </init>
059: * </authenticator>
060: * </pre></code>
061: *
062: * <p>Authenticator instances can be specific to a web-app, host, or
063: * server-wide. If the authenticator is configured for the host, it
064: * is shared for all web-apps in that host, enabling single-signon.
065: *
066: * <code><pre>
067: * <host id='foo'>
068: * <authenticator id='myauth'>...</authenticator>
069: *
070: * <web-app id='/a'>
071: * ...
072: * </web-app>
073: *
074: * <web-app id='/a'>
075: * ...
076: * </web-app>
077: * </host>
078: * </pre></code>
079: */
080: public interface ServletAuthenticator {
081: /**
082: * Initialize the authenticator. <code>init()</code> is called after all
083: * the bean parameter have been set.
084: */
085: public void init() throws ServletException;
086:
087: /**
088: * Logs a user in with a user name and a password. The login method
089: * is generally called during servlet security checks. The
090: * ServletRequest.getUserPrincipal call will generally call
091: * getUserPrincipal.
092: *
093: * <p>The implementation may only use the response to set cookies
094: * and headers. It may not write output or set the response status.
095: * If the application needs to send a custom error reponse,
096: * it must implement a custom AbstractLogin instead.
097: *
098: * @param request servlet request
099: * @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 login(HttpServletRequest request,
107: HttpServletResponse response, ServletContext application,
108: String user, String password) throws ServletException;
109:
110: /**
111: * Gets the authenticated user for the current request. If the user
112: * has not logged in, just returns null.
113: *
114: * <p>getUserPrincipal is called in response to an application's call to
115: * HttpServletRequest.getUserPrincipal.
116: *
117: * <p>The implementation may only use the response to set cookies
118: * and headers. It may not write output.
119: *
120: * @param request the request trying to authenticate.
121: * @param response the response for setting headers and cookies.
122: * @param application the servlet context
123: *
124: * @return the authenticated user or null if none has logged in
125: */
126: public Principal getUserPrincipal(HttpServletRequest request,
127: HttpServletResponse response, ServletContext application)
128: throws ServletException;
129:
130: /**
131: * Validates the user when using HTTP Digest authentication.
132: * DigestLogin will call this method. Most other AbstractLogin
133: * implementations, like BasicLogin and FormLogin, will use
134: * getUserPrincipal instead.
135: *
136: * <p>The HTTP Digest authentication uses the following algorithm
137: * to calculate the digest. The digest is then compared to
138: * the client digest.
139: *
140: * <code><pre>
141: * A1 = MD5(username + ':' + realm + ':' + password)
142: * A2 = MD5(method + ':' + uri)
143: * digest = MD5(A1 + ':' + nonce + A2)
144: * </pre></code>
145: *
146: * @param request the request trying to authenticate.
147: * @param response the response for setting headers and cookies.
148: * @param app the servlet context
149: * @param user the username
150: * @param realm the authentication realm
151: * @param nonce the nonce passed to the client during the challenge
152: * @param uri te protected uri
153: * @param qop
154: * @param nc
155: * @param cnonce the client nonce
156: * @param clientDigest the client's calculation of the digest
157: *
158: * @return the logged in principal if successful
159: */
160: public Principal loginDigest(HttpServletRequest request,
161: HttpServletResponse response, ServletContext app,
162: String user, String realm, String nonce, String uri,
163: String qop, String nc, String cnonce, byte[] clientDigset)
164: throws ServletException;
165:
166: /**
167: * Returns true if the user plays the named role.
168: *
169: * <p>This method is called in response to the
170: * HttpServletResponse.isUserInRole call and for security-constraints
171: * that check the use role.
172: *
173: * @param request the request testing the role.
174: * @param application the owning application
175: * @param user the user's Principal.
176: * @param role role name.
177: */
178: public boolean isUserInRole(HttpServletRequest request,
179: HttpServletResponse response, ServletContext application,
180: Principal user, String role) throws ServletException;
181:
182: /**
183: * Logs the user out from the given request.
184: *
185: * <p>Called via the session.logout() method.
186: *
187: * @param session for timeout, the session timing out. null if force logout
188: */
189: public void logout(ServletContext application, HttpSession session,
190: String sessionId, Principal user) throws ServletException;
191: }
|