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 javax.servlet.RequestDispatcher;
  20 import javax.servlet.http.HttpServletRequest;
  21 import javax.servlet.http.HttpServletResponse;
  22 import javax.servlet.http.HttpSession;
  23
  24 import org.opensaml.saml2.core.AuthnRequest;
  25
  26 /**
  27  * Authentication handlers are responsible for authenticating a user using a particular authentication context class.
  28  *
  29  * The request incoming to the authentication handler will contain a {@link AuthnRequest} attribute registered under the
  30  * name <strong>AuthnRequest</strong>. If the authentication request coming into the IdP is not a SAML 2 request the
  31  * receiving profile handler will translate the incoming details into a {@link AuthnRequest}.
  32  *
  33  * Upon successfull authentication the handler <strong>must</strong> set a request attribute called <strong>principal</strong>
  34  * with the principal name of the authenticated user. It must then forward the request/response to the provided return
  35  * location by means of the
  36  * {@link RequestDispatcher#forward(javax.servlet.ServletRequest, javax.servlet.ServletResponse)} method.
  37  *
  38  * AuthentcationHandlers <strong>MUST NOT</strong> change or add any data to the user's {@link HttpSession} that
  39  * persists past the process of authenticating the user, that is no additional session data may be added and no existing
  40  * session data may be changed when the handler redirects back to the return location.
  41  */
  42 public interface AuthenticationHandler {
  43
  44     /**
  45      * Authenticates the user making the request.
  46      *
  47      * @param request user request
  48      * @param response response to use
  49      * @param passive whether the authentication must be passive
  50      * @param force whether the handler must force an authentication
  51      */
  52     public void authenticate(HttpServletRequest request, HttpServletResponse response, boolean passive, boolean force);
  53
  54     /**
  55      * Gets whether this handler supports passive authentication.
  56      *
  57      * @return whether this handler supports passive authentication
  58      */
  59     public boolean supportsPassive();
  60
  61     /**
  62      * Gets whether this handler supports the ability to force a user's to authenticate.
  63      *
  64      * @return whether this handler supports the ability to force a user's to authenticate
  65      */
  66     public boolean supportsForceAuthentication();
  67
  68     /**
  69      * Sets the location to return the user to once authenticated.
  70      *
  71      * @param location location to return the user to once authenticated
  72      */
  73     public void setReturnLocation(String location);
  74 }