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 }