First part of mavenizing IdP
[java-idp.git] / src / main / java / edu / internet2 / middleware / shibboleth / idp / authn / LoginHandler.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.security.auth.Subject;
22 import javax.servlet.http.HttpServletRequest;
23 import javax.servlet.http.HttpServletResponse;
24
25 import edu.internet2.middleware.shibboleth.idp.session.AuthenticationMethodInformation;
26
27 /**
28  * Authentication handlers authenticate a user in an implementation specific manner. Some examples of this might be by
29  * collecting a user name and password and validating it against an LDAP directory or collecting and validating a client
30  * certificate or one-time password.
31  * 
32  * After the handler has authenticated the user it <strong>MUST</strong> bind the user's principal name to the
33  * {@link HttpServletRequest} attribute identified by {@link LoginHandler#PRINCIPAL_NAME_KEY}.
34  * 
35  * The handler may bind a {@link Subject} to the attribute identified by {@link #SUBJECT_KEY} if one was created during
36  * the authentication process. This Subject is stored in the {@link AuthenticationMethodInformation}, created for this
37  * authentication, in the user's session.
38  * 
39  * The handler may designate the a URI representing the authentication method actually used, for example if a handler is
40  * capable of performing multiple types of authentication, by binding the URI, as a String, to a request attribute
41  * identified by {@link #AUTHENTICATION_METHOD_KEY}.
42  * 
43  * The handler may also bind an error message, if an error occurred during authentication to the request attribute
44  * identified by {@link LoginHandler#AUTHENTICATION_ERROR_KEY}.
45  * 
46  * Finally, the handler must return control to the authentication engine by invoking
47  * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the
48  * authentication handler must immediately return.
49  * 
50  * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that
51  * persists past the process of authenticating the user, that is no additional session data may be added and no existing
52  * session data may be changed when the handler returns control to the authentication engine.
53  */
54 public interface LoginHandler {
55
56     /** Request attribute to which user's principal name should be bound. */
57     public static final String PRINCIPAL_NAME_KEY = "principal";
58
59     /** Request attribute to which user's subject should be bound. */
60     public static final String SUBJECT_KEY = "subject";
61
62     /** Request attribute to which an authentication method URI may be bound. */
63     public static final String AUTHENTICATION_METHOD_KEY = "authnMethod";
64
65     /** Request attribute to which an error message may be bound. */
66     public static final String AUTHENTICATION_ERROR_KEY = "authnError";
67
68     /**
69      * Gets the list of authentication methods this handler supports.
70      * 
71      * @return authentication methods this handler supports
72      */
73     public List<String> getSupportedAuthenticationMethods();
74
75     /**
76      * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be
77      * re-authenticated.
78      * 
79      * @return length of time, in milliseconds, after which a user should be re-authenticated
80      */
81     public long getAuthenticationDuration();
82
83     /**
84      * Gets whether this handler supports passive authentication.
85      * 
86      * @return whether this handler supports passive authentication
87      */
88     public boolean supportsPassive();
89
90     /**
91      * Returns if this handler supports the ability to force a user to (re-)authenticate.
92      * 
93      * @return if this handler can force a user to (re-)authenticate.
94      */
95     public boolean supportsForceAuthentication();
96
97     /**
98      * Authenticate the user making the request.
99      * 
100      * @param httpRequest user request
101      * @param httpResponse response to user
102      */
103     public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse);
104 }