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

<para>
Because RESTEasy is deployed as a servlet, standard web.xml constraints must be used 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 limited.  URL patterns in web.xml only support simple wildcards,
    so &REST-API; resources such as the following:
</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 resolve this issue, use the security annotations defined below on your &REST-API;
    methods.  Some general security constraint elements will still need to be declared 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, RESTEasy does not recognize these annotations.  RESTEasy must be configured
    to turn on role-based security by setting the appropriate parameter.  The code fragment below
    show how to enable security.
</para>
<para>
    NOTE!!!  Do not turn on this switch if using &ENTERPRISE-BEANS;.  The &ENTERPRISE-BEANS; container
    will provide this functionality instead of RESTEasy.
</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>
    RESTEasy requires that all roles used within the application be declared in the war's web.xml file.
    A security constraint that permits all of those roles access
    to every URL handled by the &REST-API; runtime must also be declared in the web.xml.
</para>
<para>
    RESTEasy performs authorization by checking the method annotations. If a method is annotated with
    @RolesAllowed. It calls HttpServletRequest.isUserInRole.  If one of the @RolesAllowed passes,
    the request is processed, otherwise, a response is returned with a 401 (Unauthorized) response code.
</para>
<para>
Here is an example of a modified RESTEasy WAR file.  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>
