1 /* 2 * Licensed to the University Corporation for Advanced Internet Development, 3 * Inc. (UCAID) under one or more contributor license agreements. See the 4 * NOTICE file distributed with this work for additional information regarding 5 * copyright ownership. The UCAID licenses this file to You under the Apache 6 * License, Version 2.0 (the "License"); you may not use this file except in 7 * compliance with the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package edu.internet2.middleware.shibboleth.idp.authn; 19 20 import java.util.List; 21 22 import javax.servlet.http.HttpServletRequest; 23 import javax.servlet.http.HttpServletResponse; 24 25 /** 26 * Authentication handlers authenticate a user in an implementation specific manner. Some examples of this might be by 27 * collecting a user name and password and validating it against an LDAP directory, validating a client certificate, or 28 * validating one-time password. 29 * 30 * When a login handler is invoked the user's {@link edu.internet2.middleware.shibboleth.idp.session.Session} is bound 31 * to the {@link javax.servlet.http.HttpSession} under the attribute with the name 32 * {@link edu.internet2.middleware.shibboleth.idp.session.Session#HTTP_SESSION_BINDING_ATTRIBUTE}. 33 * 34 * After a successful authentication has been completed the handler <strong>MUST</strong> either: 35 * <ul> 36 * <li>Bind a {@link javax.security.auth.Subject} to the attribute identified by {@link #SUBJECT_KEY} if one was created 37 * during the authentication process. The principals, public, and private credentials from this subject will be merged 38 * with those in the {@link javax.security.auth.Subject} within the 39 * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li> 40 * <li>Bind a {@link java.security.Principal} for the user to the request attribute identified by {@link #PRINCIPAL_KEY} 41 * . Such a {@link java.security.Principal} <strong>MUST</strong> implement {@link java.io.Serializable}. This principal 42 * will be added to the {@link javax.security.auth.Subject} within the 43 * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li> 44 * <li>Bind a principal name string to the request attribute identified by {@link #PRINCIPAL_NAME_KEY}. In this case the 45 * {@link AuthenticationEngine} will create a {@link java.security.Principal} object of type 46 * {@link edu.internet2.middleware.shibboleth.idp.authn.UsernamePrincipal} and add that to the 47 * {@link javax.security.auth.Subject} within the {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li> 48 * </ul> 49 * 50 * The handler <strong>MAY</strong> also: 51 * <ul> 52 * <li>Bind a URI string, representing the authentication method actually used, to a request attribute identified by 53 * {@link #AUTHENTICATION_METHOD_KEY}. This may be used if a handler is capable of performing multiple types of 54 * authentication.</li> 55 * <li>Bind an error message, if an error occurred during authentication to the request attribute identified by 56 * {@link LoginHandler#AUTHENTICATION_ERROR_KEY}.</li> 57 * <li>Bind a {@link AuthenticationException}, if an exception occurred during authentication to the request attribute 58 * identified by {@link LoginHandler#AUTHENTICATION_EXCEPTION_KEY}.</li> 59 * </ul> 60 * 61 * Finally, the handler must return control to the authentication engine by invoking 62 * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the 63 * authentication handler must immediately return. 64 * 65 * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that 66 * persists past the process of authenticating the user, that is no additional session data may be added and no existing 67 * session data may be changed when the handler returns control to the authentication engine. 68 */ 69 public interface LoginHandler { 70 71 /** Request attribute to which user's principal should be bound. */ 72 public static final String PRINCIPAL_KEY = "principal"; 73 74 /** Request attribute to which user's principal name should be bound. */ 75 public static final String PRINCIPAL_NAME_KEY = "principal_name"; 76 77 /** Request attribute to which user's subject should be bound. */ 78 public static final String SUBJECT_KEY = "subject"; 79 80 /** Request attribute to which an authentication method URI may be bound. */ 81 public static final String AUTHENTICATION_METHOD_KEY = "authnMethod"; 82 83 /** Request attribute to which an authentication timestamp may be bound. */ 84 public static final String AUTHENTICATION_INSTANT_KEY = "authnInstant"; 85 86 /** Request attribute to which an error message may be bound. */ 87 public static final String AUTHENTICATION_ERROR_KEY = "authnError"; 88 89 /** Request attribute to which an {@link AuthenticationException} may be bound. */ 90 public static final String AUTHENTICATION_EXCEPTION_KEY = "authnException"; 91 92 /** 93 * Gets the list of authentication methods this handler supports. 94 * 95 * @return authentication methods this handler supports 96 */ 97 public List<String> getSupportedAuthenticationMethods(); 98 99 /** 100 * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be 101 * re-authenticated. 102 * 103 * @return length of time, in milliseconds, after which a user should be re-authenticated 104 */ 105 public long getAuthenticationDuration(); 106 107 /** 108 * Gets whether this handler supports passive authentication. 109 * 110 * @return whether this handler supports passive authentication 111 */ 112 public boolean supportsPassive(); 113 114 /** 115 * Returns if this handler supports the ability to force a user to (re-)authenticate. 116 * 117 * @return if this handler can force a user to (re-)authenticate. 118 */ 119 public boolean supportsForceAuthentication(); 120 121 /** 122 * Authenticate the user making the request. 123 * 124 * @param httpRequest user request 125 * @param httpResponse response to user 126 */ 127 public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse); 128 }