src/edu/internet2/middleware/shibboleth/idp/authn/AuthenticationHandler.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 AuthenticationHandler#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 also bind an error message, if an error occurred during authentication to the request attribute
  40  * identified by {@link AuthenticationHandler#AUTHENTICATION_ERROR_KEY}.
  41  *
  42  * Finally, the handler must return control to the authentication engine by invoking
  43  * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the
  44  * authentication handler must immediately return.
  45  *
  46  * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that
  47  * persists past the process of authenticating the user, that is no additional session data may be added and no existing
  48  * session data may be changed when the handler returns control to the authentication engine.
  49  */
  50 public interface AuthenticationHandler {
  51
  52     /** Request attribute to which user's principal name should be bound. */
  53     public static final String PRINCIPAL_NAME_KEY = "principal";
  54
  55     /** Request attribute to which user's subject should be bound. */
  56     public static final String SUBJECT_KEY = "subject";
  57
  58     /** Request attribute to which an error message may be bound. */
  59     public static final String AUTHENTICATION_ERROR_KEY = "authnError";
  60
  61     /**
  62      * Gets the list of authentication methods this handler supports.
  63      *
  64      * @return authentication methods this handler supports
  65      */
  66     public List<String> getSupportedAuthenticationMethods();
  67
  68     /**
  69      * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be
  70      * re-authenticated.
  71      *
  72      * @return length of time, in milliseconds, after which a user should be re-authenticated
  73      */
  74     public long getAuthenticationDuration();
  75
  76     /**
  77      * Gets whether this handler supports passive authentication.
  78      *
  79      * @return whether this handler supports passive authentication
  80      */
  81     public boolean supportsPassive();
  82
  83     /**
  84      * Returns if this handler supports the ability to force a user to (re-)authenticate.
  85      *
  86      * @return if this handler can force a user to (re-)authenticate.
  87      */
  88     public boolean supportsForceAuthentication();
  89
  90     /**
  91      * Authenticate the user making the request.
  92      *
  93      * @param httpRequest user request
  94      * @param httpResponse response to user
  95      */
  96     public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse);
  97
  98     /**
  99      * Logs out the given user from the authentication mechanism represented by this handler.
 100      *
 101      * @param request user request
 102      * @param response response to user
 103      * @param principal principal named as returned during authentication
 104      */
 105     public void logout(HttpServletRequest request, HttpServletResponse response, String principal);
 106 }