1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.shiro.web.filter;
20
21 import org.apache.shiro.SecurityUtils;
22 import org.apache.shiro.subject.Subject;
23 import org.apache.shiro.web.util.WebUtils;
24
25 import javax.servlet.ServletRequest;
26 import javax.servlet.ServletResponse;
27 import java.io.IOException;
28
29 /**
30 * Superclass for any filter that controls access to a resource and may redirect the user to the login page
31 * if they are not authenticated. This superclass provides the method
32 * {@link #saveRequestAndRedirectToLogin(javax.servlet.ServletRequest, javax.servlet.ServletResponse)}
33 * which is used by many subclasses as the behavior when a user is unauthenticated.
34 *
35 * @since 0.9
36 */
37 public abstract class AccessControlFilter extends PathMatchingFilter {
38
39 /**
40 * Simple default login URL equal to <code>/login.jsp</code>, which can be overridden by calling the
41 * {@link #setLoginUrl(String) setLoginUrl} method.
42 */
43 public static final String DEFAULT_LOGIN_URL = "/login.jsp";
44
45 /**
46 * Constant representing the HTTP 'GET' request method, equal to <code>GET</code>.
47 */
48 public static final String GET_METHOD = "GET";
49
50 /**
51 * Constant representing the HTTP 'POST' request method, equal to <code>POST</code>.
52 */
53 public static final String POST_METHOD = "POST";
54
55 /**
56 * The login url to used to authenticate a user, used when redirecting users if authentication is required.
57 */
58 private String loginUrl = DEFAULT_LOGIN_URL;
59
60 /**
61 * Returns the login URL used to authenticate a user.
62 * <p/>
63 * Most Shiro filters use this url
64 * as the location to redirect a user when the filter requires authentication. Unless overridden, the
65 * {@link #DEFAULT_LOGIN_URL DEFAULT_LOGIN_URL} is assumed, which can be overridden via
66 * {@link #setLoginUrl(String) setLoginUrl}.
67 *
68 * @return the login URL used to authenticate a user, used when redirecting users if authentication is required.
69 */
70 public String getLoginUrl() {
71 return loginUrl;
72 }
73
74 /**
75 * Sets the login URL used to authenticate a user.
76 * <p/>
77 * Most Shiro filters use this url as the location to redirect a user when the filter requires
78 * authentication. Unless overridden, the {@link #DEFAULT_LOGIN_URL DEFAULT_LOGIN_URL} is assumed.
79 *
80 * @param loginUrl the login URL used to authenticate a user, used when redirecting users if authentication is required.
81 */
82 public void setLoginUrl(String loginUrl) {
83 this.loginUrl = loginUrl;
84 }
85
86 /**
87 * Convenience method that acquires the Subject associated with the request.
88 * <p/>
89 * The default implementation simply returns
90 * {@link org.apache.shiro.SecurityUtils#getSubject() SecurityUtils.getSubject()}.
91 *
92 * @param request the incoming <code>ServletRequest</code>
93 * @param response the outgoing <code>ServletResponse</code>
94 * @return the Subject associated with the request.
95 */
96 protected Subject getSubject(ServletRequest request, ServletResponse response) {
97 return SecurityUtils.getSubject();
98 }
99
100 /**
101 * Returns <code>true</code> if the request is allowed to proceed through the filter normally, or <code>false</code>
102 * if the request should be handled by the
103 * {@link #onAccessDenied(ServletRequest,ServletResponse,Object) onAccessDenied(request,response,mappedValue)}
104 * method instead.
105 *
106 * @param request the incoming <code>ServletRequest</code>
107 * @param response the outgoing <code>ServletResponse</code>
108 * @param mappedValue the filter-specific config value mapped to this filter in the URL rules mappings.
109 * @return <code>true</code> if the request should proceed through the filter normally, <code>false</code> if the
110 * request should be processed by this filter's
111 * {@link #onAccessDenied(ServletRequest,ServletResponse,Object)} method instead.
112 * @throws Exception if an error occurs during processing.
113 */
114 protected abstract boolean isAccessAllowed(ServletRequest request, ServletResponse response, Object mappedValue) throws Exception;
115
116 /**
117 * Processes requests where the subject was denied access as determined by the
118 * {@link #isAccessAllowed(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Object) isAccessAllowed}
119 * method, retaining the {@code mappedValue} that was used during configuration.
120 * <p/>
121 * This method immediately delegates to {@link #onAccessDenied(ServletRequest,ServletResponse)} as a
122 * convenience in that most post-denial behavior does not need the mapped config again.
123 *
124 * @param request the incoming <code>ServletRequest</code>
125 * @param response the outgoing <code>ServletResponse</code>
126 * @param mappedValue the config specified for the filter in the matching request's filter chain.
127 * @return <code>true</code> if the request should continue to be processed; false if the subclass will
128 * handle/render the response directly.
129 * @throws Exception if there is an error processing the request.
130 * @since 1.0
131 */
132 protected boolean onAccessDenied(ServletRequest request, ServletResponse response, Object mappedValue) throws Exception {
133 return onAccessDenied(request, response);
134 }
135
136 /**
137 * Processes requests where the subject was denied access as determined by the
138 * {@link #isAccessAllowed(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Object) isAccessAllowed}
139 * method.
140 *
141 * @param request the incoming <code>ServletRequest</code>
142 * @param response the outgoing <code>ServletResponse</code>
143 * @return <code>true</code> if the request should continue to be processed; false if the subclass will
144 * handle/render the response directly.
145 * @throws Exception if there is an error processing the request.
146 */
147 protected abstract boolean onAccessDenied(ServletRequest request, ServletResponse response) throws Exception;
148
149 /**
150 * Returns <code>true</code> if
151 * {@link #isAccessAllowed(ServletRequest,ServletResponse,Object) isAccessAllowed(Request,Response,Object)},
152 * otherwise returns the result of
153 * {@link #onAccessDenied(ServletRequest,ServletResponse,Object) onAccessDenied(Request,Response,Object)}.
154 *
155 * @return <code>true</code> if
156 * {@link #isAccessAllowed(javax.servlet.ServletRequest, javax.servlet.ServletResponse, Object) isAccessAllowed},
157 * otherwise returns the result of
158 * {@link #onAccessDenied(javax.servlet.ServletRequest, javax.servlet.ServletResponse) onAccessDenied}.
159 * @throws Exception if an error occurs.
160 */
161 public boolean onPreHandle(ServletRequest request, ServletResponse response, Object mappedValue) throws Exception {
162 return isAccessAllowed(request, response, mappedValue) || onAccessDenied(request, response, mappedValue);
163 }
164
165 /**
166 * Returns <code>true</code> if the incoming request is a login request, <code>false</code> otherwise.
167 * <p/>
168 * The default implementation merely returns <code>true</code> if the incoming request matches the configured
169 * {@link #getLoginUrl() loginUrl} by calling
170 * <code>{@link #pathsMatch(String, String) pathsMatch(loginUrl, request)}</code>.
171 *
172 * @param request the incoming <code>ServletRequest</code>
173 * @param response the outgoing <code>ServletResponse</code>
174 * @return <code>true</code> if the incoming request is a login request, <code>false</code> otherwise.
175 */
176 protected boolean isLoginRequest(ServletRequest request, ServletResponse response) {
177 return pathsMatch(getLoginUrl(), request);
178 }
179
180 /**
181 * Convenience method for subclasses to use when a login redirect is required.
182 * <p/>
183 * This implementation simply calls {@link #saveRequest(javax.servlet.ServletRequest) saveRequest(request)}
184 * and then {@link #redirectToLogin(javax.servlet.ServletRequest, javax.servlet.ServletResponse) redirectToLogin(request,response)}.
185 *
186 * @param request the incoming <code>ServletRequest</code>
187 * @param response the outgoing <code>ServletResponse</code>
188 * @throws IOException if an error occurs.
189 */
190 protected void saveRequestAndRedirectToLogin(ServletRequest request, ServletResponse response) throws IOException {
191 saveRequest(request);
192 redirectToLogin(request, response);
193 }
194
195 /**
196 * Convenience method merely delegates to
197 * {@link WebUtils#saveRequest(javax.servlet.ServletRequest) WebUtils.saveRequest(request)} to save the request
198 * state for reuse later. This is mostly used to retain user request state when a redirect is issued to
199 * return the user to their originally requested url/resource.
200 * <p/>
201 * If you need to save and then immediately redirect the user to login, consider using
202 * {@link #saveRequestAndRedirectToLogin(javax.servlet.ServletRequest, javax.servlet.ServletResponse)
203 * saveRequestAndRedirectToLogin(request,response)} directly.
204 *
205 * @param request the incoming ServletRequest to save for re-use later (for example, after a redirect).
206 */
207 protected void saveRequest(ServletRequest request) {
208 WebUtils.saveRequest(request);
209 }
210
211 /**
212 * Convenience method for subclasses that merely acquires the {@link #getLoginUrl() getLoginUrl} and redirects
213 * the request to that url.
214 * <p/>
215 * <b>N.B.</b> If you want to issue a redirect with the intention of allowing the user to then return to their
216 * originally requested URL, don't use this method directly. Instead you should call
217 * {@link #saveRequestAndRedirectToLogin(javax.servlet.ServletRequest, javax.servlet.ServletResponse)
218 * saveRequestAndRedirectToLogin(request,response)}, which will save the current request state so that it can
219 * be reconstructed and re-used after a successful login.
220 *
221 * @param request the incoming <code>ServletRequest</code>
222 * @param response the outgoing <code>ServletResponse</code>
223 * @throws IOException if an error occurs.
224 */
225 protected void redirectToLogin(ServletRequest request, ServletResponse response) throws IOException {
226 String loginUrl = getLoginUrl();
227 WebUtils.issueRedirect(request, response, loginUrl);
228 }
229
230 }