| <!-- |
| /*************************************************************************************************************************** |
| * 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. |
| ***************************************************************************************************************************/ |
| --> |
| |
| Role guards |
| |
| <p> |
| Specialized guards are provided for controlling access to servlet classes and methods based on user roles. |
| These are controlled via annotations on the REST class and methods: |
| </p> |
| <ul class='javatree'> |
| <li class='ja'>{@link oajr.annotation.RestResource} |
| <ul> |
| <li class='jf'>{@link oajr.annotation.RestResource#roleGuard() roleGuard()} |
| <li class='jf'>{@link oajr.annotation.RestResource#rolesDeclared() rolesDeclared()} |
| </ul> |
| <li class='ja'>{@link oajr.annotation.RestMethod} |
| <ul> |
| <li class='jf'>{@link oajr.annotation.RestMethod#roleGuard() roleGuard()} |
| <li class='jf'>{@link oajr.annotation.RestMethod#rolesDeclared() rolesDeclared()} |
| </ul> |
| </ul> |
| <p> |
| The <c>roleGuard()</c> annotation is an expression that defines whether a user with specified roles are allowed |
| to access methods. |
| </p> |
| <h5 class='figure'>Example:</h5> |
| <p class='bpcode w800'> |
| <jc>// Only admin users or users with both read/write and special access |
| // can run any methods on this class.</jc> |
| <ja>@RestResource</ja>( |
| path=<js>"/foo"</js>, |
| roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE && ROLE_SPECIAL)"</js> |
| ) |
| <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { |
| ... |
| } |
| </p> |
| <p> |
| The syntax allows for any of the following: |
| </p> |
| <ul> |
| <li><js>"foo"</js> - Single arguments. |
| <li><js>"foo,bar,baz"</js> - Multiple OR'ed arguments. |
| <li><js>"foo | bar | baz"</js> - Multiple OR'ed arguments, pipe syntax. |
| <li><js>"foo || bar || baz"</js> - Multiple OR'ed arguments, Java-OR syntax. |
| <li><js>"fo*"</js> - Patterns including <js>'*'</js> and <js>'?'</js>. |
| <li><js>"fo* & *oo"</js> - Multiple AND'ed arguments, ampersand syntax. |
| <li><js>"fo* && *oo"</js> - Multiple AND'ed arguments, Java-AND syntax. |
| <li><js>"fo* || (*oo || bar)"</js> - Parenthesis. |
| </ul> |
| |
| <p> |
| If patterns are used, you must specify the list of declared roles using the <c>rolesDeclared()</c> annotations. |
| This declares the list of all possible user roles and is needed because the servlet API does not provide this |
| capability. |
| </p> |
| |
| <h5 class='figure'>Example:</h5> |
| <p class='bpcode w800'> |
| <ja>@RestResource</ja>( |
| rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>, |
| roleGuard=<js>"ROLE_ADMIN || (*WRITE* && *SPECIAL*)"</js> |
| ) |
| <jk>public class</jk> MyResource <jk>extends</jk> RestServlet { |
| ... |
| } |
| </p> |