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 created
36 * during the authentication process. The principals, public, and private credentials from this subject will be merged
37 * 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 {@link #PRINCIPAL_KEY}
40 * . Such a {@link java.security.Principal} <strong>MUST</strong> implement {@link java.io.Serializable}. This principal
41 * 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 the
44 * {@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 * <li>Bind a {@link AuthenticationException}, if an exception occurred during authentication to the request attribute
57 * identified by {@link LoginHandler#AUTHENTICATION_EXCEPTION_KEY}.</li>
58 * </ul>
59 *
60 * Finally, the handler must return control to the authentication engine by invoking
61 * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the
62 * authentication handler must immediately return.
63 *
64 * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that
65 * persists past the process of authenticating the user, that is no additional session data may be added and no existing
66 * session data may be changed when the handler returns control to the authentication engine.
67 */
68 public interface LoginHandler {
69
70 /** Request attribute to which user's principal should be bound. */
71 public static final String PRINCIPAL_KEY = "principal";
72
73 /** Request attribute to which user's principal name should be bound. */
74 public static final String PRINCIPAL_NAME_KEY = "principal_name";
75
76 /** Request attribute to which user's subject should be bound. */
77 public static final String SUBJECT_KEY = "subject";
78
79 /** Request attribute to which an authentication method URI may be bound. */
80 public static final String AUTHENTICATION_METHOD_KEY = "authnMethod";
81
82 /** Request attribute to which an error message may be bound. */
83 public static final String AUTHENTICATION_ERROR_KEY = "authnError";
84
85 /** Request attribute to which an {@link AuthenticationException} may be bound. */
86 public static final String AUTHENTICATION_EXCEPTION_KEY = "authnException";
87
88 /**
89 * Gets the list of authentication methods this handler supports.
90 *
91 * @return authentication methods this handler supports
92 */
93 public List<String> getSupportedAuthenticationMethods();
94
95 /**
96 * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be
97 * re-authenticated.
98 *
99 * @return length of time, in milliseconds, after which a user should be re-authenticated
100 */
101 public long getAuthenticationDuration();
102
103 /**
104 * Gets whether this handler supports passive authentication.
105 *
106 * @return whether this handler supports passive authentication
107 */
108 public boolean supportsPassive();
109
110 /**
111 * Returns if this handler supports the ability to force a user to (re-)authenticate.
112 *
113 * @return if this handler can force a user to (re-)authenticate.
114 */
115 public boolean supportsForceAuthentication();
116
117 /**
118 * Authenticate the user making the request.
119 *
120 * @param httpRequest user request
121 * @param httpResponse response to user
122 */
123 public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse);
124 }