e25443c4733b847b5295c8fddbc2b7fb8c2e0a6e
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / idp / authn / AuthenticationHandler.java
1 /*
2  * Copyright [2006] [University Corporation for Advanced Internet Development, Inc.]
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 package edu.internet2.middleware.shibboleth.idp.authn;
18
19 import java.util.List;
20
21 import javax.servlet.http.HttpServletRequest;
22 import javax.servlet.http.HttpServletResponse;
23
24 /**
25  * Authentication handlers authenticate a user in an implementation specific manner. Some examples of this might be by
26  * collecting a user name and password and validating it against an LDAP directory or collecting and validating a client
27  * certificate or one-time password.
28  * 
29  * After the handler has authenticated the user it <strong>MUST</strong> bind the user's principal name to the
30  * {@link HttpServletRequest} attribute identified by {@link AuthenticationHandler#PRINCIPAL_NAME_KEY}. The handler may
31  * also bind an error message, if an error occurred during authentication to the request attribute identified by
32  * {@link AuthenticationHandler#AUTHENTICATION_ERROR_KEY}. Finally, the handler must return control to the
33  * authentication engine by invoking
34  * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the
35  * authentication handler must immediately return.
36  * 
37  * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that
38  * persists past the process of authenticating the user, that is no additional session data may be added and no existing
39  * session data may be changed when the handler returns control to the authentication engine.
40  */
41 public interface AuthenticationHandler {
42
43     /** Request attribute to which user's principal name should be bound. */
44     public static final String PRINCIPAL_NAME_KEY = "principal";
45
46     /** Request attribute to which an error message may be bound. */
47     public static final String AUTHENTICATION_ERROR_KEY = "authnError";
48
49     /**
50      * Gets the list of authentication methods this handler supports.
51      * 
52      * @return authentication methods this handler supports
53      */
54     public List<String> getSupportedAuthenticationMethods();
55     
56     /**
57      * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be
58      * re-authenticated.
59      * 
60      * @return length of time, in milliseconds, after which a user should be re-authenticated
61      */
62     public long getAuthenticationDuration();
63
64     /**
65      * Gets whether this handler supports passive authentication.
66      * 
67      * @return whether this handler supports passive authentication
68      */
69     public boolean supportsPassive();
70
71     /**
72      * Returns if this handler supports the ability to force a user to (re-)authenticate.
73      * 
74      * @return if this handler can force a user to (re-)authenticate.
75      */
76     public boolean supportsForceAuthentication();
77
78     /**
79      * Authenticate the user making the request.
80      * 
81      * @param httpRequest user request
82      * @param httpResponse response to user
83      */
84     public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse);
85
86     /**
87      * Logs out the given user from the authentication mechanism represented by this handler.
88      * 
89      * @param request user request
90      * @param response response to user
91      * @param principal principal named as returned during authentication
92      */
93     public void logout(HttpServletRequest request, HttpServletResponse response, String principal);
94 }