View Javadoc

    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.servlet.http.HttpServletRequest;
    22  import javax.servlet.http.HttpServletResponse;
    23
    24  /**
    25   * Authentication handlers authenticate a user in an implementation specific manner. Some examples of this might be by
    26   * collecting a user name and password and validating it against an LDAP directory, validating a client certificate, or
    27   * validating one-time password.
    28   *
    29   * When a login handler is invoked the user's {@link edu.internet2.middleware.shibboleth.idp.session.Session} is bound
    30   * to the {@link javax.servlet.http.HttpSession} under the attribute with the name
    31   * {@link edu.internet2.middleware.shibboleth.idp.session.Session#HTTP_SESSION_BINDING_ATTRIBUTE}.
    32   *
    33   * After a successful authentication has been completed the handler <strong>MUST</strong> either:
    34   * <ul>
    35   * <li>Bind a {@link javax.security.auth.Subject} to the attribute identified by {@link #SUBJECT_KEY} if one was
    36   * created during the authentication process. The principals, public, and private credentials from this subject will be
    37   * merged with those in the {@link javax.security.auth.Subject} within the
    38   * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
    39   * <li>Bind a {@link java.security.Principal} for the user to the request attribute identified by
    40   * {@link #PRINCIPAL_KEY}. Such a {@link java.security.Principal} <strong>MUST</strong> implement
    41   * {@link java.io.Serializable}. This principal will be added to the {@link javax.security.auth.Subject} within the
    42   * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
    43   * <li>Bind a principal name string to the request attribute identified by {@link #PRINCIPAL_NAME_KEY}. In this case
    44   * the {@link AuthenticationEngine} will create a {@link java.security.Principal} object of type
    45   * {@link edu.internet2.middleware.shibboleth.idp.authn.UsernamePrincipal} and add that to the
    46   * {@link javax.security.auth.Subject} within the {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
    47   * </ul>
    48   *
    49   * The handler <strong>MAY</strong> also:
    50   * <ul>
    51   * <li>Bind a URI string, representing the authentication method actually used, to a request attribute identified by
    52   * {@link #AUTHENTICATION_METHOD_KEY}. This may be used if a handler is capable of performing multiple types of
    53   * authentication.</li>
    54   * <li>bind an error message, if an error occurred during authentication to the request attribute identified by
    55   * {@link LoginHandler#AUTHENTICATION_ERROR_KEY}.</li>
    56   * </ul>
    57   *
    58   * Finally, the handler must return control to the authentication engine by invoking
    59   * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the
    60   * authentication handler must immediately return.
    61   *
    62   * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that
    63   * persists past the process of authenticating the user, that is no additional session data may be added and no existing
    64   * session data may be changed when the handler returns control to the authentication engine.
    65   */
    66  public interface LoginHandler {
    67
    68      /** Request attribute to which user's principal should be bound. */
    69      public static final String PRINCIPAL_KEY = "principal";
    70
    71      /** Request attribute to which user's principal name should be bound. */
    72      public static final String PRINCIPAL_NAME_KEY = "principal_name";
    73
    74      /** Request attribute to which user's subject should be bound. */
    75      public static final String SUBJECT_KEY = "subject";
    76
    77      /** Request attribute to which an authentication method URI may be bound. */
    78      public static final String AUTHENTICATION_METHOD_KEY = "authnMethod";
    79
    80      /** Request attribute to which an error message may be bound. */
    81      public static final String AUTHENTICATION_ERROR_KEY = "authnError";
    82
    83      /**
    84       * Gets the list of authentication methods this handler supports.
    85       *
    86       * @return authentication methods this handler supports
    87       */
    88      public List<String> getSupportedAuthenticationMethods();
    89
    90      /**
    91       * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be
    92       * re-authenticated.
    93       *
    94       * @return length of time, in milliseconds, after which a user should be re-authenticated
    95       */
    96      public long getAuthenticationDuration();
    97
    98      /**
    99       * Gets whether this handler supports passive authentication.
    100      *
    101      * @return whether this handler supports passive authentication
    102      */
    103     public boolean supportsPassive();
    104
    105     /**
    106      * Returns if this handler supports the ability to force a user to (re-)authenticate.
    107      *
    108      * @return if this handler can force a user to (re-)authenticate.
    109      */
    110     public boolean supportsForceAuthentication();
    111
    112     /**
    113      * Authenticate the user making the request.
    114      *
    115      * @param httpRequest user request
    116      * @param httpResponse response to user
    117      */
    118     public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse);
    119 }