edu.internet2.middleware.shibboleth.idp.authn
Class AuthenticationEngine

java.lang.Object
  extended by javax.servlet.GenericServlet
      extended by javax.servlet.http.HttpServlet
          extended by edu.internet2.middleware.shibboleth.idp.authn.AuthenticationEngine
All Implemented Interfaces:
Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public class AuthenticationEngine
extends javax.servlet.http.HttpServlet

Manager responsible for handling authentication requests.

See Also:
Serialized Form

Field Summary
static String IDP_SESSION_COOKIE_NAME
          Name of the IdP Cookie containing the IdP session ID.
static String LOGIN_CONTEXT_KEY_NAME
          Name of the key under which to bind the storage service key for a login context.
static String LOGIN_CONTEXT_LIFETIME_INIT_PARAM_NAME
          Name of the Servlet config init parameter that holds lifetime of a login context in the storage service.
static String LOGIN_CONTEXT_PARTITION_NAME_INIT_PARAM_NAME
          Name of the Servlet config init parameter that holds the partition name for login contexts.
 
Constructor Summary
AuthenticationEngine()
           
 
Method Summary
protected  void addSessionCookie(javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse, Session userSession)
          Adds an IdP session cookie to the outbound response.
protected  void completeAuthentication(LoginContext loginContext, javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          Completes the authentication process.
protected  Map<String,LoginHandler> determinePossibleLoginHandlers(LoginContext loginContext)
          Determines which configured login handlers will support the requested authentication methods.
protected  void filterByForceAuthentication(Session idpSession, LoginContext loginContext, Map<String,LoginHandler> loginHandlers)
          Filters out any login handler based on the requirement for forced authentication.
protected  void filterByPassiveAuthentication(Session idpSession, LoginContext loginContext, Map<String,LoginHandler> loginHandlers)
          Filters out any login handler that doesn't support passive authentication if the login context indicates passive authentication is required.
protected static void forwardRequest(String forwardPath, javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          Forwards a request to the given path.
protected  Subject getLoginHandlerSubject(javax.servlet.http.HttpServletRequest httpRequest)
          Gets the subject from the request coming back from the login handler.
 void init(javax.servlet.ServletConfig config)
          
protected  Subject mergeSubjects(Subject subject1, Subject subject2)
          Merges the principals and public and private credentials from two subjects into a new subject.
protected static LoginContext retrieveLoginContext(javax.servlet.http.HttpServletRequest httpRequest, boolean removeFromStorageService)
          Retrieves a login context.
static void returnToAuthenticationEngine(javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          Returns control back to the authentication engine.
static void returnToProfileHandler(LoginContext loginContext, javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          Returns control back to the profile handler that invoked the authentication engine.
protected  void service(javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          
protected  void startUserAuthentication(LoginContext loginContext, javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          Begins the authentication process.
protected  void storeLoginContext(LoginContext loginContext, javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          Stores the login context in the storage service.
protected  void updateUserSession(LoginContext loginContext, Subject authenticationSubject, String authenticationMethod, javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)
          Updates the user's Shibboleth session with authentication information.
protected  void validateForcedReauthentication(Session idpSession, String authnMethod, Subject subject)
          If forced authentication was required this method checks to ensure that the re-authenticated subject contains a principal name that is equal to the principal name associated with the authentication method.
protected  void validateSuccessfulAuthentication(LoginContext loginContext, javax.servlet.http.HttpServletRequest httpRequest)
          Validates that the authentication was successfully performed by the login handler.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOGIN_CONTEXT_PARTITION_NAME_INIT_PARAM_NAME

public static final String LOGIN_CONTEXT_PARTITION_NAME_INIT_PARAM_NAME
Name of the Servlet config init parameter that holds the partition name for login contexts.

See Also:
Constant Field Values

LOGIN_CONTEXT_LIFETIME_INIT_PARAM_NAME

public static final String LOGIN_CONTEXT_LIFETIME_INIT_PARAM_NAME
Name of the Servlet config init parameter that holds lifetime of a login context in the storage service.

See Also:
Constant Field Values

IDP_SESSION_COOKIE_NAME

public static final String IDP_SESSION_COOKIE_NAME
Name of the IdP Cookie containing the IdP session ID.

See Also:
Constant Field Values

LOGIN_CONTEXT_KEY_NAME

public static final String LOGIN_CONTEXT_KEY_NAME
Name of the key under which to bind the storage service key for a login context.

See Also:
Constant Field Values
Constructor Detail

AuthenticationEngine

public AuthenticationEngine()
Method Detail

init

public void init(javax.servlet.ServletConfig config)
          throws javax.servlet.ServletException

Specified by:
init in interface javax.servlet.Servlet
Overrides:
init in class javax.servlet.GenericServlet
Throws:
javax.servlet.ServletException

retrieveLoginContext

protected static LoginContext retrieveLoginContext(javax.servlet.http.HttpServletRequest httpRequest,
                                                   boolean removeFromStorageService)
Retrieves a login context.

Parameters:
httpRequest - current HTTP request
removeFromStorageService - whether the login context should be removed from the storage service as it is retrieved
Returns:
the login context or null if one is not available (e.g. because it has expired)

returnToAuthenticationEngine

public static void returnToAuthenticationEngine(javax.servlet.http.HttpServletRequest httpRequest,
                                                javax.servlet.http.HttpServletResponse httpResponse)
Returns control back to the authentication engine.

Parameters:
httpRequest - current HTTP request
httpResponse - current HTTP response

returnToProfileHandler

public static void returnToProfileHandler(LoginContext loginContext,
                                          javax.servlet.http.HttpServletRequest httpRequest,
                                          javax.servlet.http.HttpServletResponse httpResponse)
Returns control back to the profile handler that invoked the authentication engine.

Parameters:
loginContext - current login context
httpRequest - current HTTP request
httpResponse - current HTTP response

forwardRequest

protected static void forwardRequest(String forwardPath,
                                     javax.servlet.http.HttpServletRequest httpRequest,
                                     javax.servlet.http.HttpServletResponse httpResponse)
Forwards a request to the given path.

Parameters:
forwardPath - path to forward the request to
httpRequest - current HTTP request
httpResponse - current HTTP response

service

protected void service(javax.servlet.http.HttpServletRequest httpRequest,
                       javax.servlet.http.HttpServletResponse httpResponse)
                throws javax.servlet.ServletException,
                       IOException

Overrides:
service in class javax.servlet.http.HttpServlet
Throws:
javax.servlet.ServletException
IOException

startUserAuthentication

protected void startUserAuthentication(LoginContext loginContext,
                                       javax.servlet.http.HttpServletRequest httpRequest,
                                       javax.servlet.http.HttpServletResponse httpResponse)
Begins the authentication process. Determines if forced re-authentication is required or if an existing, active, authentication method is sufficient. Also determines, when authentication is required, which handler to use depending on whether passive authentication is required.

Parameters:
loginContext - current login context
httpRequest - current HTTP request
httpResponse - current HTTP response

determinePossibleLoginHandlers

protected Map<String,LoginHandler> determinePossibleLoginHandlers(LoginContext loginContext)
                                                           throws AuthenticationException
Determines which configured login handlers will support the requested authentication methods.

Parameters:
loginContext - current login context
Returns:
login methods that may be used to authenticate the user
Throws:
AuthenticationException - thrown if no login handler meets the given requirements

filterByForceAuthentication

protected void filterByForceAuthentication(Session idpSession,
                                           LoginContext loginContext,
                                           Map<String,LoginHandler> loginHandlers)
                                    throws ForceAuthenticationException
Filters out any login handler based on the requirement for forced authentication. During forced authentication any handler that has not previously been used to authenticate the user or any handlers that have been and support force re-authentication may be used. Filter out any of the other ones.

Parameters:
idpSession - user's current IdP session
loginContext - current login context
loginHandlers - login handlers to filter
Throws:
ForceAuthenticationException - thrown if no handlers remain after filtering

filterByPassiveAuthentication

protected void filterByPassiveAuthentication(Session idpSession,
                                             LoginContext loginContext,
                                             Map<String,LoginHandler> loginHandlers)
                                      throws PassiveAuthenticationException
Filters out any login handler that doesn't support passive authentication if the login context indicates passive authentication is required.

Parameters:
idpSession - user's current IdP session
loginContext - current login context
loginHandlers - login handlers to filter
Throws:
PassiveAuthenticationException - thrown if no handlers remain after filtering

storeLoginContext

protected void storeLoginContext(LoginContext loginContext,
                                 javax.servlet.http.HttpServletRequest httpRequest,
                                 javax.servlet.http.HttpServletResponse httpResponse)
Stores the login context in the storage service. The key for the stored login context is then bound to an HTTP request attribute and set a cookie.

Parameters:
loginContext - login context to store
httpRequest - current HTTP request
httpResponse - current HTTP response

completeAuthentication

protected void completeAuthentication(LoginContext loginContext,
                                      javax.servlet.http.HttpServletRequest httpRequest,
                                      javax.servlet.http.HttpServletResponse httpResponse)
Completes the authentication process. The principal name set by the authentication handler is retrieved and pushed in to the login context, a Shibboleth session is created if needed, information indicating that the user has logged into the service is recorded and finally control is returned back to the profile handler.

Parameters:
loginContext - current login context
httpRequest - current HTTP request
httpResponse - current HTTP response

validateSuccessfulAuthentication

protected void validateSuccessfulAuthentication(LoginContext loginContext,
                                                javax.servlet.http.HttpServletRequest httpRequest)
                                         throws AuthenticationException
Validates that the authentication was successfully performed by the login handler. An authentication is considered successful if no error is bound to the request attribute LoginHandler.AUTHENTICATION_ERROR_KEY and there is a value for at least one of the following request attributes: LoginHandler.SUBJECT_KEY, LoginHandler.PRINCIPAL_KEY, or LoginHandler.PRINCIPAL_NAME_KEY.

Parameters:
loginContext - current login context
httpRequest - current HTTP request
Throws:
AuthenticationException - thrown if the authentication was not successful

getLoginHandlerSubject

protected Subject getLoginHandlerSubject(javax.servlet.http.HttpServletRequest httpRequest)
                                  throws AuthenticationException
Gets the subject from the request coming back from the login handler.

Parameters:
httpRequest - request coming back from the login handler
Returns:
the Subject created from the request
Throws:
AuthenticationException - thrown if no subject can be retrieved from the request

validateForcedReauthentication

protected void validateForcedReauthentication(Session idpSession,
                                              String authnMethod,
                                              Subject subject)
                                       throws AuthenticationException
If forced authentication was required this method checks to ensure that the re-authenticated subject contains a principal name that is equal to the principal name associated with the authentication method. If this is the first time the subject has authenticated with this method than this check always passes.

Parameters:
idpSession - user's IdP session
authnMethod - method used to authenticate the user
subject - subject that was authenticated
Throws:
AuthenticationException - thrown if this check fails

updateUserSession

protected void updateUserSession(LoginContext loginContext,
                                 Subject authenticationSubject,
                                 String authenticationMethod,
                                 javax.servlet.http.HttpServletRequest httpRequest,
                                 javax.servlet.http.HttpServletResponse httpResponse)
Updates the user's Shibboleth session with authentication information. If no session exists a new one will be created.

Parameters:
loginContext - current login context
authenticationSubject - subject created from the authentication method
authenticationMethod - the method used to authenticate the subject
httpRequest - current HTTP request
httpResponse - current HTTP response

mergeSubjects

protected Subject mergeSubjects(Subject subject1,
                                Subject subject2)
Merges the principals and public and private credentials from two subjects into a new subject.

Parameters:
subject1 - first subject to merge, may be null
subject2 - second subject to merge, may be null
Returns:
subject containing the merged information

addSessionCookie

protected void addSessionCookie(javax.servlet.http.HttpServletRequest httpRequest,
                                javax.servlet.http.HttpServletResponse httpResponse,
                                Session userSession)
Adds an IdP session cookie to the outbound response.

Parameters:
httpRequest - current request
httpResponse - current response
userSession - user's session


Copyright © 2006-2008 Internet2. All Rights Reserved.