View Javadoc

1   /*
2    * Licensed to the University Corporation for Advanced Internet Development, 
3    * Inc. (UCAID) under one or more contributor license agreements.  See the 
4    * NOTICE file distributed with this work for additional information regarding
5    * copyright ownership. The UCAID licenses this file to You under the Apache 
6    * License, Version 2.0 (the "License"); you may not use this file except in 
7    * compliance with the License.  You may obtain a copy of the License at
8    *
9    *    http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  package edu.internet2.middleware.shibboleth.idp.authn;
19  
20  import java.util.List;
21  
22  import javax.servlet.http.HttpServletRequest;
23  import javax.servlet.http.HttpServletResponse;
24  
25  /**
26   * Authentication handlers authenticate a user in an implementation specific manner. Some examples of this might be by
27   * collecting a user name and password and validating it against an LDAP directory, validating a client certificate, or
28   * validating one-time password.
29   * 
30   * When a login handler is invoked the user's {@link edu.internet2.middleware.shibboleth.idp.session.Session} is bound
31   * to the {@link javax.servlet.http.HttpSession} under the attribute with the name
32   * {@link edu.internet2.middleware.shibboleth.idp.session.Session#HTTP_SESSION_BINDING_ATTRIBUTE}.
33   * 
34   * After a successful authentication has been completed the handler <strong>MUST</strong> either:
35   * <ul>
36   * <li>Bind a {@link javax.security.auth.Subject} to the attribute identified by {@link #SUBJECT_KEY} if one was created
37   * during the authentication process. The principals, public, and private credentials from this subject will be merged
38   * with those in the {@link javax.security.auth.Subject} within the
39   * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
40   * <li>Bind a {@link java.security.Principal} for the user to the request attribute identified by {@link #PRINCIPAL_KEY}
41   * . Such a {@link java.security.Principal} <strong>MUST</strong> implement {@link java.io.Serializable}. This principal
42   * will be added to the {@link javax.security.auth.Subject} within the
43   * {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
44   * <li>Bind a principal name string to the request attribute identified by {@link #PRINCIPAL_NAME_KEY}. In this case the
45   * {@link AuthenticationEngine} will create a {@link java.security.Principal} object of type
46   * {@link edu.internet2.middleware.shibboleth.idp.authn.UsernamePrincipal} and add that to the
47   * {@link javax.security.auth.Subject} within the {@link edu.internet2.middleware.shibboleth.idp.session.Session}.</li>
48   * </ul>
49   * 
50   * The handler <strong>MAY</strong> also:
51   * <ul>
52   * <li>Bind a URI string, representing the authentication method actually used, to a request attribute identified by
53   * {@link #AUTHENTICATION_METHOD_KEY}. This may be used if a handler is capable of performing multiple types of
54   * authentication.</li>
55   * <li>Bind an error message, if an error occurred during authentication to the request attribute identified by
56   * {@link LoginHandler#AUTHENTICATION_ERROR_KEY}.</li>
57   * <li>Bind a {@link AuthenticationException}, if an exception occurred during authentication to the request attribute
58   * identified by {@link LoginHandler#AUTHENTICATION_EXCEPTION_KEY}.</li>
59   * </ul>
60   * 
61   * Finally, the handler must return control to the authentication engine by invoking
62   * {@link AuthenticationEngine#returnToAuthenticationEngine(HttpServletRequest, HttpServletResponse)}. After which the
63   * authentication handler must immediately return.
64   * 
65   * Handlers <strong>MUST NOT</strong> change or add any data to the user's {@link javax.servlet.http.HttpSession} that
66   * persists past the process of authenticating the user, that is no additional session data may be added and no existing
67   * session data may be changed when the handler returns control to the authentication engine.
68   */
69  public interface LoginHandler {
70  
71      /** Request attribute to which user's principal should be bound. */
72      public static final String PRINCIPAL_KEY = "principal";
73  
74      /** Request attribute to which user's principal name should be bound. */
75      public static final String PRINCIPAL_NAME_KEY = "principal_name";
76  
77      /** Request attribute to which user's subject should be bound. */
78      public static final String SUBJECT_KEY = "subject";
79  
80      /** Request attribute to which an authentication method URI may be bound. */
81      public static final String AUTHENTICATION_METHOD_KEY = "authnMethod";
82  
83      /** Request attribute to which an authentication timestamp may be bound. */
84      public static final String AUTHENTICATION_INSTANT_KEY = "authnInstant";
85      
86      /** Request attribute to which an error message may be bound. */
87      public static final String AUTHENTICATION_ERROR_KEY = "authnError";
88  
89      /** Request attribute to which an {@link AuthenticationException} may be bound. */
90      public static final String AUTHENTICATION_EXCEPTION_KEY = "authnException";
91  
92      /**
93       * Gets the list of authentication methods this handler supports.
94       * 
95       * @return authentication methods this handler supports
96       */
97      public List<String> getSupportedAuthenticationMethods();
98  
99      /**
100      * Gets the length of time, in milliseconds, after which a user authenticated by this handler should be
101      * re-authenticated.
102      * 
103      * @return length of time, in milliseconds, after which a user should be re-authenticated
104      */
105     public long getAuthenticationDuration();
106 
107     /**
108      * Gets whether this handler supports passive authentication.
109      * 
110      * @return whether this handler supports passive authentication
111      */
112     public boolean supportsPassive();
113 
114     /**
115      * Returns if this handler supports the ability to force a user to (re-)authenticate.
116      * 
117      * @return if this handler can force a user to (re-)authenticate.
118      */
119     public boolean supportsForceAuthentication();
120 
121     /**
122      * Authenticate the user making the request.
123      * 
124      * @param httpRequest user request
125      * @param httpResponse response to user
126      */
127     public void login(HttpServletRequest httpRequest, HttpServletResponse httpResponse);
128 }