Rework authentication and session management code:
[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.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, validating a client certificate, or
27  * validating one-time password.
28  * 
29  * When a login handler is invoked the user's {@link edu.internet2.middleware.shibboleth.idp.session.Session} is bound
30  * to the {@link javax.servlet.http.HttpSession} under the attribute with the name
31  * {@link edu.internet2.middleware.shibboleth.idp.session.Session#HTTP_SESSION_BINDING_ATTRIBUTE}.
32  * 
33  * After a successful authentication has been completed the handler <strong>MUST</strong> either:
34  * <ul>
35  * <li>Bind a {@link javax.security.auth.Subject} to the attribute identified by {@link #SUBJECT_KEY} if one was
36  * created during the authentication process. The principals, public, and private credentials from this subject will be
37  * merged with those in the {@link javax.security.auth.Subject} within the
38  * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
39  * <li>Bind a {@link java.security.Principal} for the user to the request attribute identified by
40  * {@link #PRINCIPAL_KEY}. Such a {@link java.security.Principal} <strong>MUST</strong> implement
41  * {@link java.io.Serializable}. This principal will be added to the {@link javax.security.auth.Subject} within the
42  * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
43  * <li>Bind a principal name string to the request attribute identified by {@link #PRINCIPAL_NAME_KEY}. In this case
44  * the {@link AuthenticationEngine} will create a {@link java.security.Principal} object of type
45  * {@link edu.internet2.middleware.shibboleth.idp.authn.UsernamePrincipal} and add that to the
46  * {@link javax.security.auth.Subject} within the {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
47  * </ul>
48  * 
49  * The handler <strong>MAY</strong> also:
50  * <ul>
51  * <li>Bind a URI string, representing the authentication method actually used, to a request attribute identified by
52  * {@link #AUTHENTICATION_METHOD_KEY}. This may be used if a handler is capable of performing multiple types of
53  * authentication.</li>
54  * <li>bind an error message, if an error occurred during authentication to the request attribute identified by
55  * {@link LoginHandler#AUTHENTICATION_ERROR_KEY}.</li>
56  * </ul>
57  * 
58  * Finally, the handler must return control to the authentication engine by invoking
59  * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the
60  * authentication handler must immediately return.
61  * 
62  * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that
63  * persists past the process of authenticating the user, that is no additional session data may be added and no existing
64  * session data may be changed when the handler returns control to the authentication engine.
65  */
66 public interface LoginHandler {
67
68     /** Request attribute to which user's principal should be bound. */
69     public static final String PRINCIPAL_KEY = "principal";
70
71     /** Request attribute to which user's principal name should be bound. */
72     public static final String PRINCIPAL_NAME_KEY = "principal_name";
73
74     /** Request attribute to which user's subject should be bound. */
75     public static final String SUBJECT_KEY = "subject";
76
77     /** Request attribute to which an authentication method URI may be bound. */
78     public static final String AUTHENTICATION_METHOD_KEY = "authnMethod";
79
80     /** Request attribute to which an error message may be bound. */
81     public static final String AUTHENTICATION_ERROR_KEY = "authnError";
82
83     /**
84      * Gets the list of authentication methods this handler supports.
85      * 
86      * @return authentication methods this handler supports
87      */
88     public List<String> getSupportedAuthenticationMethods();
89
90     /**
91      * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be
92      * re-authenticated.
93      * 
94      * @return length of time, in milliseconds, after which a user should be re-authenticated
95      */
96     public long getAuthenticationDuration();
97
98     /**
99      * Gets whether this handler supports passive authentication.
100      * 
101      * @return whether this handler supports passive authentication
102      */
103     public boolean supportsPassive();
104
105     /**
106      * Returns if this handler supports the ability to force a user to (re-)authenticate.
107      * 
108      * @return if this handler can force a user to (re-)authenticate.
109      */
110     public boolean supportsForceAuthentication();
111
112     /**
113      * Authenticate the user making the request.
114      * 
115      * @param httpRequest user request
116      * @param httpResponse response to user
117      */
118     public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse);
119 }