View Javadoc

1   //
2   //  ========================================================================
3   //  Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
4   //  ------------------------------------------------------------------------
5   //  All rights reserved. This program and the accompanying materials
6   //  are made available under the terms of the Eclipse Public License v1.0
7   //  and Apache License v2.0 which accompanies this distribution.
8   //
9   //      The Eclipse Public License is available at
10  //      http://www.eclipse.org/legal/epl-v10.html
11  //
12  //      The Apache License v2.0 is available at
13  //      http://www.opensource.org/licenses/apache2.0.php
14  //
15  //  You may elect to redistribute this code under either of these licenses.
16  //  ========================================================================
17  //
18  
19  package org.eclipse.jetty.security;
20  
21  import java.util.Set;
22  
23  import javax.servlet.ServletContext;
24  import javax.servlet.ServletRequest;
25  import javax.servlet.ServletResponse;
26  
27  import org.eclipse.jetty.server.Authentication;
28  import org.eclipse.jetty.server.Authentication.User;
29  import org.eclipse.jetty.server.Server;
30  
31  /**
32   * Authenticator Interface
33   * <p>
34   * An Authenticator is responsible for checking requests and sending
35   * response challenges in order to authenticate a request.
36   * Various types of {@link Authentication} are returned in order to
37   * signal the next step in authentication.
38   *
39   * @version $Rev: 4793 $ $Date: 2009-03-19 00:00:01 +0100 (Thu, 19 Mar 2009) $
40   */
41  public interface Authenticator
42  {
43      /* ------------------------------------------------------------ */
44      /**
45       * Configure the Authenticator
46       * 
47       * @param configuration the configuration
48       */
49      void setConfiguration(AuthConfiguration configuration);
50  
51      /* ------------------------------------------------------------ */
52      /**
53       * @return The name of the authentication method
54       */
55      String getAuthMethod();
56      
57      
58      /* ------------------------------------------------------------ */
59      /**
60       * Called prior to validateRequest. The authenticator can
61       * manipulate the request to update it with information that
62       * can be inspected prior to validateRequest being called.
63       * The primary purpose of this method is to satisfy the Servlet
64       * Spec 3.1 section 13.6.3 on handling Form authentication
65       * where the http method of the original request causing authentication
66       * is not the same as the http method resulting from the redirect
67       * after authentication.
68       * 
69       * @param request the request to manipulate
70       */
71      void prepareRequest(ServletRequest request);
72      
73  
74      /* ------------------------------------------------------------ */
75      /** 
76       * Validate a request
77       * 
78       * @param request The request
79       * @param response The response
80       * @param mandatory True if authentication is mandatory.
81       * @return An Authentication.  If Authentication is successful, this will be a {@link org.eclipse.jetty.server.Authentication.User}. If a response has
82       * been sent by the Authenticator (which can be done for both successful and unsuccessful authentications), then the result will
83       * implement {@link org.eclipse.jetty.server.Authentication.ResponseSent}.  If Authentication is not manditory, then a
84       * {@link org.eclipse.jetty.server.Authentication.Deferred} may be returned.
85       *
86       * @throws ServerAuthException if unable to validate request
87       */
88      Authentication validateRequest(ServletRequest request, ServletResponse response, boolean mandatory) throws ServerAuthException;
89  
90      /* ------------------------------------------------------------ */
91      /**
92       * is response secure
93       * 
94       * @param request the request 
95       * @param response the response
96       * @param mandatory if security is mandator
97       * @param validatedUser the user that was validated
98       * @return true if response is secure
99       * @throws ServerAuthException if unable to test response
100      */
101     boolean secureResponse(ServletRequest request, ServletResponse response, boolean mandatory, User validatedUser) throws ServerAuthException;
102 
103 
104     /* ------------------------------------------------------------ */
105     /* ------------------------------------------------------------ */
106     /* ------------------------------------------------------------ */
107     /**
108      * Authenticator Configuration
109      */
110     interface AuthConfiguration
111     {
112         String getAuthMethod();
113         String getRealmName();
114 
115         /** 
116          * Get a SecurityHandler init parameter
117          * @see SecurityHandler#getInitParameter(String)
118          * @param param parameter name
119          * @return Parameter value or null
120          */
121         String getInitParameter(String param);
122 
123         /* ------------------------------------------------------------ */
124         /** Get a SecurityHandler init parameter names
125          * @see SecurityHandler#getInitParameterNames()
126          * @return Set of parameter names
127          */
128         Set<String> getInitParameterNames();
129 
130         LoginService getLoginService();
131         IdentityService getIdentityService();
132         boolean isSessionRenewedOnAuthentication();
133     }
134 
135     /* ------------------------------------------------------------ */
136     /* ------------------------------------------------------------ */
137     /* ------------------------------------------------------------ */
138     /**
139      * Authenticator Factory
140      */
141     interface Factory
142     {
143         Authenticator getAuthenticator(Server server, ServletContext context, AuthConfiguration configuration, IdentityService identityService, LoginService loginService);
144     }
145 }