| <!-- |
| /*************************************************************************************************************************** |
| * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations under the License. |
| ***************************************************************************************************************************/ |
| --> |
| |
| Guards |
| |
| <p> |
| Guards are classes that control access to REST classes and methods. |
| </p> |
| <p> |
| Guards are associated with resource classes and methods via the following: |
| </p> |
| <ul class='javatree'> |
| <li class='ja'>{@link oajr.annotation.Rest#guards() Rest(guards)} |
| <li class='ja'>{@link oajr.annotation.RestMethod#guards() RestMethod(guards)} |
| <li class='jm'>{@link oajr.RestContextBuilder#guards(Class...)} |
| </ul> |
| <p class='bpcode w800'> |
| <jc>// Define a guard that only lets Billy make a request</jc> |
| <jk>public</jk> BillyGuard <jk>extends</jk> RestGuard { |
| |
| <ja>@Override</ja> <jc>/* RestGuard */</jc> |
| <jk>public boolean</jk> isRequestAllowed(RestRequest req) { |
| <jk>return</jk> req.getUserPrincipal().getName().equals(<js>"Billy"</js>); |
| } |
| } |
| |
| <jc>// Servlet with class-level guard applied</jc> |
| <ja>@Rest</ja>(guards=BillyGuard.<jk>class</jk>) |
| <jk>public</jk> MyRestServlet <jk>extends</jk> BasicRestServlet { |
| |
| <jc>// Delete method that only Billy is allowed to call.</jc> |
| <ja>@RestMethod</ja>(name=<js>"DELETE"</js>) |
| <jk>public</jk> doDelete(RestRequest req, RestResponse res) <jk>throws</jk> Exception {...} |
| } |
| </p> |
| <p> |
| A common use for guards is to only allow admin access to certain Java methods... |
| </p> |
| <p class='bpcode w800'> |
| <jc>// DELETE method</jc> |
| <ja>@RestMethod</ja>(name=<jsf>DELETE</jsf>, guards={AdminGuard.<jk>class</jk>}) |
| <jk>public void</jk> doDelete(RestRequest req, RestResponse res) <jk>throws</jk> Exception {...} |
| </p> |
| <p class='bpcode w800'> |
| <jk>public class</jk> AdminGuard <jk>extends</jk> RestGuard { |
| |
| <ja>@Override</ja> <jc>/* RestGuard */</jc> |
| <jk>public boolean</jk> isRequestAllowed(RestRequest req) { |
| <jk>return</jk> req.getUserPrincipal().isUserInRole(<js>"ADMIN"</js>); |
| } |
| } |
| </p> |
| <p> |
| A guard failure results in an <l>HTTP 401 Unauthorized</l> response. |
| However, this can be configured by overriding the |
| {@link oajr.RestGuard#guard(RestRequest,RestResponse)} and processing the response |
| yourself. |
| </p> |
| <p class='bpcode w800'> |
| <jk>public class</jk> AdminGuard <jk>extends</jk> RestGuard { |
| |
| <ja>@Override</ja> <jc>/* RestGuard */</jc> |
| <jk>public boolean</jk> guard(RestRequest req, RestResponse res) <jk>throws</jk> RestException { |
| <jk>if</jk> (! isOkay(req)) |
| <jk>throw new</jk> RestException(<jsf>SC_FORBIDDEN</jsf>, <js>"Access denied!!!"</js>); |
| <jk>return true</jk>; |
| } |
| } |
| </p> |
| <p> |
| When guards are associated at the class-level, it's equivalent to associating guards on all Java methods on |
| the servlet. |
| If multiple guards are present, ALL guards must pass. |
| </p> |
| <ul class='seealso'> |
| <li class='jf'>{@link oajr.RestContext#REST_guards} |
| </ul> |