Securing RESTful Web Services and Clients

About RESTful Web Service Security

You can secure your RESTful web services so that they can support authentication, authorization, or encryption. You can use one of the following methods:

Updating the web.xml deployment descriptor to access information about the authenticated users. See Securing RESTful Web Services Using web.xml.
Using the javax.ws.rs.core.SecurityContext interface to access security-related information for a request. See Securing RESTful Web Services Using SecurityContext.
Applying annotations to your JAX-RS classes. See Securing RESTful Web Services Using Java Security Annotations.

For information about developing RESTful web service clients using Oracle JDeveloper, see How to Attach Policies to RESTful Web Services and Clients in Developing Applications with Oracle JDeveloper.

Securing RESTful Web Services Using web.xml

You secure RESTful web services using the web.xml deployment descriptor as you would for other Java EE Web applications. For complete details, see:

Developing Secure Web Applications in Developing Applications with the WebLogic Security Service.
Securing Web Applications in The Java EE 8 Tutorial.

For example, to secure your RESTful web service using basic authentication, perform the following steps:

Define a <security-constraint> for each set of RESTful resources (URIs) that you plan to protect.
Use the <login-config> element to define the type of authentication you want to use and the security realm to which the security constraints will be applied.
Define one or more security roles using the <security-role> tag and map them to the security constraints defined in step 1. See security-role in Developing Applications with the WebLogic Security Service.
To enable encryption, add the <user-data-constraint> element and set the <transport-guarantee> subelement to CONFIDENTIAL. See user-data-constraint in Developing Applications with the WebLogic Security Service.

Example 5-1 Securing RESTful Web Services Using Basic Authentication

The following example demonstrates how to secure a Jersey 2.x (JAX-RS 2.0) RESTful web service using basic authentication.

<web-app>
    <servlet>
        <servlet-name>RestServlet</servlet-name>

        <servlet-class>org.glassfish.jersey.servlet.ServletContainer</servlet-class>

    </servlet>
    <servlet-mapping>
        <servlet-name>RestServlet</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
    <security-constraint>
         <web-resource-collection>
             <web-resource-name>Orders</web-resource-name>
             <url-pattern>/orders</url-pattern>
             <http-method>GET</http-method>
             <http-method>POST</http-method>
         </web-resource-collection>
         <auth-constraint>
             <role-name>admin</role-name> 
         </auth-constraint>
    </security-constraint>
    <login-config>
        <auth-method>BASIC</auth-method>
        <realm-name>default</realm-name>
    </login-config>
    <security-role>
        <role-name>admin</role-name>
    </security-role>
</web-app>

Securing RESTful Web Services Using SecurityContext

The javax.ws.rs.core.SecurityContext interface provides access to security-related information for a request. The SecurityContext provides functionality similar to javax.servlet.http.HttpServletRequest, enabling you to access the following security-related information:

java.security.Principal object containing the name of the user making the request.
Authentication type used to secure the resource, such as BASIC_AUTH, FORM_AUTH, and CLIENT_CERT_AUTH.
Whether the authenticated user is included in a particular role.
Whether the request was made using a secure channel, such as HTTPS.

You access the SecurityContext by injecting an instance into a class field, setter method, or method parameter using the javax.ws.rs.core.Context annotation.

For more information, see the following topics in the Java EE 8 Specification APIs:

SecurityContext interface
@Context annotation

Example 5-2 shows how to inject an instance of SecurityContext into the sc method parameter using the @Context annotation, and check whether the authorized user is included in the admin role before returning the response.

Example 5-2 Securing RESTful Web Service Using SecurityContext

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.SecurityContext;
import javax.ws.rs.core.Context;

...

@Path("/stateless")
@Stateless(name = "JaxRSStatelessEJB")
public class StlsEJBApp {
...
        @GET
        @Produces("text/plain;charset=UTF-8")
        @Path("/hello")
        public String sayHello(@Context SecurityContext sc) {
                if (sc.isUserInRole("admin"))  return "Hello World!";
                throw new SecurityException("User is unauthorized.");
        }

Securing RESTful Web Services Using Java Security Annotations

The javax.annotation.security package provides annotations that you can use to secure your RESTful web services.These annotations are defined in Table 5-1.

Table 5-1 Annotations for Securing RESTful Web Services

Annotation	Description
`@DenyAll`	Specifies that no security roles are allowed to invoke the specified methods.
`@PermitAll`	Specifies that all security roles are allowed to invoke the specified methods.
`@RolesAllowed`	Specifies the list of security roles that are allowed to invoke the methods in the application.

Before you can use the annotations defined in Table 5-1, you must register the roles-allowed feature, as described in Securing JAX-RS resources with standard javax.annotation.security annotations in the Jersey 2.29 User Guide.

Example 5-3 shows how to define the security roles that are allowed, by default, to access the methods defined in the helloWorld class. The sayHello method is annotated with the @RolesAllows annotation to override the default and only allow users that belong to the ADMIN security role.

Example 5-3 Securing RESTful Web Service Using Java Security Annotations

package samples.helloworld;
 
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.annotation.Security.RolesAllowed;

 
@Path("/helloworld")
@RolesAllowed({"ADMIN", "ORG1"})
public class helloWorld {

   @GET
   @Path("sayHello")  
   @Produces("text/plain")
   @RolesAllows("ADMIN")
   public String sayHello() {
      return "Hello World!";
   }
}