AuthenticationEngine (Shibboleth Identity Provider 2.2.0 Java API.)
Date: 2010-09-23

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

    java.lang.Object
      javax.servlet.GenericServlet
          javax.servlet.http.HttpServlet
              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.
`static String` | `RETAIN_PRIVATE_CREDENTIALS` Name of the Servlet config init parameter that indicates whether the private credentials of a `Subject` are retained after authentication.
`static String` | `RETAIN_PUBLIC_CREDENTIALS` Name of the Servlet config init parameter that indicates whether the public credentials of a `Subject` are retained after authentication.

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(Session idpSession, 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 void` | `filterPreviousSessionLoginHandler(Map<String,LoginHandler> supportedLoginHandlers, Session idpSession, LoginContext loginContext)` Filters out the previous session login handler if there is no existing IdP session, no active authentication methods, or if at least one of the active authentication methods do not match the requested authentication methods.
`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 two `Subject`s in to a new `Subject`.
`static void` | `returnToAuthenticationEngine(javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)` Returns control back to the authentication engine.
`static void` | `returnToProfileHandler(javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse)` Returns control back to the profile handler that invoked the authentication engine.
`protected LoginHandler` | `selectLoginHandler(Map<String,LoginHandler> possibleLoginHandlers, LoginContext loginContext, Session idpSession)` Selects a login handler from a list of possible login handlers that could be used for the request.
`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` | `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, String authenticationMethod)` 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

### RETAIN_PUBLIC_CREDENTIALS

    public static final String RETAIN_PUBLIC_CREDENTIALS

  Name of the Servlet config init parameter that indicates whether the public credentials of a `Subject` are retained after authentication.

  See Also:
    Constant Field Values

### RETAIN_PRIVATE_CREDENTIALS

    public static final String RETAIN_PRIVATE_CREDENTIALS

  Name of the Servlet config init parameter that indicates whether the private credentials of a `Subject` are retained after authentication.

  See Also:
    Constant Field Values

### 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`

### 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(javax.servlet.http.HttpServletRequest httpRequest,
                                              javax.servlet.http.HttpServletResponse httpResponse)

  Returns control back to the profile handler that invoked the authentication engine.

  Parameters:
    `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(Session idpSession,
                                                                      LoginContext loginContext)
                                                               throws AuthenticationException

  Determines which configured login handlers will support the requested authentication methods.

  Parameters:
    `loginContext` - current login context
    `idpSession` - current user's session, or null if they don't have one
  Returns:
    login methods that may be used to authenticate the user
  Throws:
    `AuthenticationException` - thrown if no login handler meets the given requirements

### filterPreviousSessionLoginHandler

    protected void filterPreviousSessionLoginHandler(Map<String,LoginHandler> supportedLoginHandlers,
                                                     Session idpSession,
                                                     LoginContext loginContext)

  Filters out the previous session login handler if there is no existing IdP session, no active authentication methods, or if at least one of the active authentication methods do not match the requested authentication methods.

  Parameters:
    `supportedLoginHandlers` - login handlers supported by the authentication engine for this request, never null
    `idpSession` - current IdP session, may be null if no session currently exists
    `loginContext` - current login context, never null

### 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

### selectLoginHandler

    protected LoginHandler selectLoginHandler(Map<String,LoginHandler> possibleLoginHandlers,
                                              LoginContext loginContext,
                                              Session idpSession)
                                       throws AuthenticationException

  Selects a login handler from a list of possible login handlers that could be used for the request.

  Parameters:
    `possibleLoginHandlers` - list of possible login handlers that could be used for the request
    `loginContext` - current login context
    `idpSession` - current IdP session, if one exists
  Returns:
    the login handler to use for this request
  Throws:
    `AuthenticationException` - thrown if no handler can be used for this request

### 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,
                                                    String authenticationMethod)
                                             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
    `authenticationMethod` - the authentication method used to authenticate the user
  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 two `Subject`s in to a new `Subject`. The new subjects contains all the `Principal`s from both subjects. If `retainSubjectsPrivateCredentials` is true then the new subject will contain all the private credentials from both subjects, if not the new subject will not contain private credentials. If `retainSubjectsPublicCredentials` is true then the new subject will contain all the public credentials from both subjects, if not the new subject will not contain public credentials.

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2006-2010 Internet2. All Rights Reserved.