blob: 3cf56cd418559608bb0feec1ea8b08f0fcb8cfd9 [file] [log] [blame]
<!--
/***************************************************************************************************************************
* 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.Rest}
<ul>
<li class='jf'>{@link oajr.annotation.Rest#roleGuard() roleGuard()}
<li class='jf'>{@link oajr.annotation.Rest#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>@Rest</ja>(
path=<js>"/foo"</js>,
roleGuard=<js>"ROLE_ADMIN || (ROLE_READ_WRITE &amp;&amp; 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* &amp; *oo"</js> - Multiple AND'ed arguments, ampersand syntax.
<li><js>"fo* &amp;&amp; *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>@Rest</ja>(
rolesDeclared=<js>"ROLE_ADMIN,ROLE_READ_WRITE,ROLE_READ_ONLY,ROLE_SPECIAL"</js>,
roleGuard=<js>"ROLE_ADMIN || (*WRITE* &amp;&amp; *SPECIAL*)"</js>
)
<jk>public class</jk> MyResource <jk>extends</jk> RestServlet {
...
}
</p>