<chapter id="Securing_Jakarta_REST_and_RESTeasy">
<title>Securing &REST-API; and RESTEasy</title>

<para>

Because RESTEasy is deployed as a servlet, you must use standard web.xml constraints to enable authentication and authorization.  
</para>
<para>

Unfortunately, web.xml constraints do not mesh very well with &REST-API; in some situations.  The problem is that web.xml URL pattern matching is very very limited.  URL patterns in web.xml only support simple wildcards, so &REST-API; resources like:
</para>
<para>

<programlisting>/{pathparam1}/foo/bar/{pathparam2} </programlisting>
</para>
<para>

Cannot be mapped as a web.xml URL pattern like:
</para>
<para>

<programlisting>/*/foo/bar/*</programlisting>
</para>
<para>

To get around this problem you will need to use the security annotations defined below on your &REST-API; methods.  You will still need to set up some general security constraint elements in web.xml to turn on authentication.
</para>
<para>


</para>
<para>

RESTEasy supports the @RolesAllowed, @PermitAll and @DenyAll annotations on &REST-API; methods.   By default though, RESTEasy does not recognize these annotations.  You have to
configure RESTEasy to turn on role-based security by setting the appropriate parameter.  NOTE!!!  Do not turn on this switch if you are using &ENTERPRISE-BEANS;.  The &ENTERPRISE-BEANS; container will provide this
functionality instead of RESTEasy. To configure this switch as a context-param, do this:

</para>
<programlisting>
<![CDATA[
<web-app>
...
   <context-param>
      <param-name>resteasy.role.based.security</param-name>
      <param-value>true</param-value>
   </context-param>
</web-app>]]>
</programlisting>

<para>See <xref linkend="microprofile_config"/> for more information about application configuration. </para>

<para>There is a bit of quirkiness with this approach.   You will have to declare all roles used within the RESTEasy war file that you are using in your &REST-API; classes and set up a security constraint that permits all of these roles access to every URL handled by the &REST-API; runtime.  You'll just have to trust that RESTEasy &REST-API; authorizes properly.
</para>
<para>

How does RESTEasy do authorization?  Well, its really simple.  It just sees if a method is annotated with @RolesAllowed and then just does HttpServletRequest.isUserInRole.  If one of the @RolesAllowed passes, then allow the request, otherwise, a response is sent back with a 401 (Unauthorized) response code.
</para>
<para>

So, here's an example of a modified RESTEasy WAR file.  You'll notice that every role declared is allowed access to every URL controlled by the RESTEasy servlet.
</para>
<para>

<programlisting>

&lt;web-app&gt;

   &lt;context-param&gt;
      &lt;param-name>resteasy.role.based.security&lt;/param-name&gt;
      &lt;param-value>true&lt;/param-value&gt;
   &lt;/context-param&gt;

   &lt;security-constraint&gt;
      &lt;web-resource-collection&gt;
         &lt;web-resource-name&gt;Resteasy&lt;/web-resource-name&gt;
         &lt;url-pattern&gt;/security&lt;/url-pattern&gt;
      &lt;/web-resource-collection&gt;
       &lt;auth-constraint&gt;
         &lt;role-name&gt;admin&lt;/role-name&gt;
         &lt;role-name&gt;user&lt;/role-name&gt;
      &lt;/auth-constraint&gt;
  &lt;/security-constraint&gt;

   &lt;login-config&gt;
      &lt;auth-method&gt;BASIC&lt;/auth-method&gt;
      &lt;realm-name&gt;Test&lt;/realm-name&gt;
   &lt;/login-config&gt;

   &lt;security-role&gt;
      &lt;role-name&gt;admin&lt;/role-name&gt;
   &lt;/security-role&gt;
   &lt;security-role&gt;
      &lt;role-name&gt;user&lt;/role-name&gt;
   &lt;/security-role&gt;

   ...
&lt;/web-app&gt;


</programlisting>
</para>
<para>


</para>
</chapter>
