Chapter 17. Security

As described above, the SecurityContext by default (if not overwritten by a request filter) only exposes security information from the underlying container. In the case you deploy a Jersey application in a Servlet container, you need to configure the Servlet container security aspects (<security-constraint>, <auth-constraint> and user to roles mappings) in order to be able to secure requests via calls to to the JAX-RS SecurityContext.

The SecurityContext can be directly retrieved from ContainerRequestContext via getSecurityContext() method. You can also replace the default SecurityContext in a request context with a custom one using the setSecurityContext(SecurityContext) method. If you set a custom SecurityContext instance in your ContainerRequestFilter, this security context instance will be used for injection into JAX-RS resource class fields. This way you can implement a custom authentication filter that may setup your own SecurityContext to be used. To ensure the early execution of your custom authentication request filter, set the filter priority to AUTHENTICATION using constants from Priorities. An early execution of you authentication filter will ensure that all other filters, resources, resource methods and sub-resource locators will execute with your custom SecurityContext instance.

In cases where a Jersey application is deployed in a Servlet container you can rely only on the standard Java/Jakarta EE Web application security mechanisms offered by the Servlet container and configurable via application's web.xml descriptor. You need to define the <security-constraint> elements in the web.xml and assign roles which are able to access these resources. You can also define HTTP methods that are allowed to be executed. See the following example.

<security-constraint>
    <web-resource-collection>
        <url-pattern>/rest/admin/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>
<security-constraint>
    <web-resource-collection>
        <url-pattern>/rest/orders/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>customer</role-name>
    </auth-constraint>
</security-constraint>
<login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>my-default-realm</realm-name>
</login-config>

The example secures two kinds of URI namespaces using the HTTP Basic Authentication. rest/admin/* will be accessible only for user group "admin" and rest/orders/* will be accessible for "customer" user group. This security configuration does not use JAX-RS or Jersey features at all as it is enforced by the Servlet container even before a request reaches the Jersey application. Keeping these security constrains up to date with your JAX-RS application might not be easy as whenever you change the @Path annotations on your resource classes you may need to update also the web.xml security configurations to reflect the changed JAX-RS resource paths. Therefore Jersey offers a more flexible solution based on placing standard Java/Jakarta EE security annotations directly on JAX-RS resource classes and methods.

With Jersey you can define the access to resources based on the user group using annotations. You can, for example, define that only a user group "admin" can execute specific resource method. To do that you firstly need to register RolesAllowedDynamicFeature as a provider. The following example shows how to register the feature if your deployment is based on a ResourceConfig.

final ResourceConfig resourceConfig = new ResourceConfig(MyResource.class);
resourceConfig.register(RolesAllowedDynamicFeature.class);
                        

Alternatively, typically when deploying your application to a Servlet container, you can implement your JAX-RS Application subclass by extending from the Jersey ResourceConfig and registering the RolesAllowedDynamicFeature in the constructor:

public class MyApplication extends ResourceConfig {
    public MyApplication() {
        super(MyResource.class);
        register(RolesAllowedDynamicFeature.class);
    }
}

Once the feature is registered, you can use annotations from package javax.annotation.security defined by JSR-250. See the following example.

@Path("/")
@PermitAll
public class Resource {
    @RolesAllowed("user")
    @GET
    public String get() { return "GET"; }

    @RolesAllowed("admin")
    @POST
    public String post(String content) { return content; }

    @Path("sub")
    public SubResource getSubResource() {
        return new SubResource();
    }
}

The resource class Resource defined in the example is annotated with a @PermitAll annotation. This means that all methods in the class which do not override this annotation will be permitted for all user groups (no restrictions are defined). In our example, the annotation will only apply to the getSubResource() method as it is the only method that does not override the annotation by defining custom role-based security settings using the @RolesAllowed annotation. @RolesAllowed annotations present on the other methods define a role or a set of roles that are allowed to execute a particular method.

These Java/Jakarta EE security annotations are processed internally in the request filter registered using the Jersey RolesAllowedDynamicFeature. The roles defined in the annotations are tested against current roles set in the SecurityContext using the SecurityContext.isUserInRole(String role) method. In case the caller is not in the role specified by the annotation, the HTTP 403 (Forbidden) error response is returned.

To add support for OAuth into your server-side application, add the following dependency to your pom.xml:

<dependency>
    <groupId>org.glassfish.jersey.security</groupId>
    <artifactId>oauth1-server</artifactId>
    <version>2.35</version>
</dependency>

Again, there is no need to add a direct dependency to the signature module, it will be transitively included.

Let's now briefly go over the most important server Jersey OAuth APIs and SPIs:

First step in enabling Jersey OAuth 1 support is to register a OAuth1ServerFeature instance initialized with an instance of OAuth1Provider. Additionally, you may configure the Request Token URI and Access Token URI - the endpoints accessible on the OAuth server that issue Request and Access Tokens. These endpoints are defined in the OAuth 1 specification and are contacted as part of the OAuth authorization flow.

Next, when a client initiates the OAuth authorization flow, the provided implementation of OAuth1Provider will be invoked as to create new tokens, get tokens and finally to store the issued Access Token. If a consumer already has a valid Access Token and makes Authenticated Requests (with OAuth 1 Authorization information in the HTTP header), the provider will be invoked to provide the OAuth1Token for the Access Token information in the header.

To add support for OAuth into your Jersey client application, add the following dependency to your pom.xml:

<dependency>
    <groupId>org.glassfish.jersey.security</groupId>
    <artifactId>oauth1-client</artifactId>
    <version>2.35</version>
</dependency>

As mentioned earlier, there is no need to add a direct dependency to the signature module, it will be transitively included.

OAuth 1 client support initially started as a code migration from Jersey 1.x. During the migration however the API of was significantly revised. The high level difference compared to Jersey 1.x OAuth client API is that the authorization flow is no longer part of a client OAuth filter. Authorization flow is now a standalone utility and can be used without a support for subsequent authenticated requests. The support for authenticated requests stays in the ClientRequestFilter but is not part of a public API anymore and is registered by a Jersey OAuth Feature.

The most important parts of the Jersey client OAuth API and SPI are explained here:

An example of how Jersey OAuth 1 client API is used can be found in the OAuth 1 Twitter Client Example. The following code snippets are extracted from the example and explain how to use the Jersey OAuth client API.

Before we start with any interaction with Twitter, we need to register our application on Twitter. See the example README.TXT file for the instructions. As a result of the registration, we get the consumer credentials that identify our application. Consumer credentials consist of consumer key and consumer secret.

As a first step in our code, we need to perform the authorization flow, where the user grants us an access to his/her Twitter client.

ConsumerCredentials consumerCredentials = new ConsumerCredentials(
                "a846d84e68421b321a32d, "f13aed84190bc");
OAuth1AuthorizationFlow authFlow = OAuth1ClientSupport.builder(consumerCredentials)
    .authorizationFlow(
        "http://api.twitter.com/oauth/request_token",
        "http://api.twitter.com/oauth/access_token",
        "http://api.twitter.com/oauth/authorize")
    .build();

Here we have built a OAuth1AuthorizationFlow utility component representing the OAuth 1 authorization flow, using OAuth1ClientSupport and OAuth1Builder API. The static builder method accepts mandatory parameter with ConsumerCredentials. These are credentials earlier issued by Twitter for our application. We have specified the Twitter OAuth endpoints where Request Token, Access Token will be retrieved and Authorization URI to which we will redirect the user in order to grant user's consent. Twitter will present an HTML page on this URI and it will ask the user whether he/she would like us to access his/her account.

Now we can proceed with the OAuth authorization flow.

String authorizationUri = authFlow.start();
// here we must direct the user to authorization uri to approve
// our application. The result will be verifier code (String).
AccessToken accessToken = authFlow.finish(verifier);

In the first line, we start the authorization flow. The method internally makes a request to the http://api.twitter.com/oauth/request_token URL and retrieves a Request Token. Details of this request can be found in the OAuth 1 specification. It then constructs a URI to which we must redirect the user. The URI is based on Twitter's authorization URI (http://api.twitter.com/oauth/authorize) and contains a Request Token as a query parameter. In the Twitter example, we have a simple console application therefore we print the URL to the console and ask the user to open the URL in a browser to approve the authorization of our application. Then the user gets a verifier and enters it back to the console. However, if our application would be a web application, we would need to return a redirection response to the user in order to redirect the user automatically to the authorizationUri. For more information about server deployment, check our OAuth 2 Google Client Web Application Example, where the client is part of the web application (the client API for OAuth 2 is similar to OAuth 1).

Once we have a verifier, we invoke the method finish() on our OAuth1AuthorizationFlow instance, which internally sends a request to an access token service URI (http://api.twitter.com/oauth/access_token) and exchanges the supplied verifier for a new valid Access Token. At this point the authorization flow is finished and we can start using the retrieved AccessToken to make authenticated requests. We can now create an instance of an OAuth 1 client Feature using OAuth1ClientSupport and pass it our accessToken. Another way is to use authFlow that already contains the information about access token to create the feature instance for us:

Feature feature = authFlow.getOAuth1Feature();
Client client = ClientBuilder.newBuilder()
    .register(feature)
    .build();

Once the feature is configured in the JAX-RS Client (or WebTarget), all requests invoked from such Client (or WebTarget) instance will automatically include an OAuth Authorization HTTP header (that contains also the OAuth signature).

Note that if you already have a valid Access Token (for example stored in the database for each of your users), then you can skip the authorization flow steps and directly create the OAuth Feature configured to use your Access Token.

AccessToken storedToken = ...;
Feature filterFeature = OAuth1ClientSupport.builder(consumerCredentials)
    .feature()
    .accessToken(storedToken)
    .build();

Here, the storedToken represents an AccessToken that your client application keeps stored e.g. in a database.

Note that the OAuth feature builder API does not require the access token to be set. The reason for it is that you might want to build a feature which would register the internal Jersey OAuth ClientRequestFilter and other related providers but which would not initialize the OAuth providers with a single fixed AccessToken instance. In such case you would need to specify a token for every single request in the request properties. Key names and API documentation of these properties can be found in OAuth1ClientSupport. Using this approach, you can have a single, OAuth enabled instance of a JAX-RS Client (or WebTarget) and use it to make authenticated requests on behalf of multiple users. Note that you can use the aforementioned request properties even if the feature has been initialized with an AccessToken to override the default access token information for particular requests, even though it is probably not a common use case.

The following code shows how to set an access token on a single request using the Jersey OAuth properties.

Response resp =
    client.target("http://my-serviceprovider.org/rest/foo/bar")
        .request()
        .property(OAuth1ClientSupport.OAUTH_PROPERTY_ACCESS_TOKEN, storedToken)
        .get();

OAuth1AuthorizationFlow internally uses a Client instance to communicate with the OAuth server. For this a new client instance is automatically created by default. You can supply your instance of a Client to be used for the authorization flow requests (for performance and/or resource management reasons) using OAuth1Builder methods.

$ # Create the private key.
$ openssl genrsa -out private.key 2048
$ # Convert the key into PKCS8 format.
$ openssl pkcs8 -topk8 -in private.key -nocrypt
$ # Extract the public key.
$ openssl rsa -in private.key -pubout

To add support for Jersey OAuth 2 Client API into your application, add the following dependency to your pom.xml:

<dependency>
    <groupId>org.glassfish.jersey.security</groupId>
    <artifactId>oauth2-client</artifactId>
    <version>2.35</version>
</dependency>

OAuth 2, in contrast with OAuth 1, is not a strictly defined protocol, rather a framework. OAuth 2 specification defines many extension points and it is up to service providers to implement these details and document these implementations for the service consumers. Additionally, OAuth 2 defines more than one authorization flow. The authorization flow similar to the flow from OAuth 1 is called the Authorization Code Grant Flow. This is the flow currently supported by Jersey (Jersey currently does not support other flows). Please refer to the OAuth 2.0 specification for more details about authorization flows. Another significant change compared to OAuth 1 is that OAuth 2 is not based on signatures and secret keys and therefore for most of the communication SSL needs to be used (i.e. the requests must be made through HTTPS). This means that all OAuth 2 endpoint URIs must use the https scheme.

Due to the fact that OAuth 2 does not define a strict protocol, it is not possible to provide a single, universal pre-configured tool interoperable with all providers. Jersey OAuth 2 APIs allows a lot of extensibility via parameters sent in each requests. Jersey currently provides two pre-configured authorization flow providers - for Google and Facebook.

The most important entry points of Jersey client OAuth 2 API and SPI are explained below:

The principle of performing the authorization flow with Jersey is similar to OAuth 1. Check the OAuth 1 Twitter Client Example which utilizes Jersey client support for OAuth 2 to get Google Tasks of the user. The application is a web application that uses redirection to forward the user to the authorization URI.

The following code is an example of how to build and use OAuth 2 authorization flow.

OAuth2CodeGrantFlow.Builder builder =
    OAuth2ClientSupport.authorizationCodeGrantFlowBuilder(clientId,
                            "https://example.com/oauth/authorization",
                            "https://example.com/oauth/token");
OAuth2CodeGrantFlow flow = builder
    .property(OAuth2CodeGrantFlow.Phase.AUTHORIZATION, "readOnly", "true")
    .scope("contact")
    .build();
String authorizationUri = flow.start();

// Here we must redirect the user to the authorizationUri
// and let the user approve an access for our app.

...

// We must handle redirection back to our web resource
// and extract code and state from the request
final TokenResult result = flow.finish(code, state);
System.out.println("Access Token: " + result.get);

In the code above we create an OAuth2CodeGrantFlow from an authorization URI and an access token URI. We have additionally set a readOnly parameter to true and assigned the parameter to the authorization phase. This is the way, how you can extend the standard flow with additional service provider-specific parameters. In this case, the readOnly=true parameter will be added as a query parameter to the authorization uri returned from the method flow.start(). If we would specify ACCESS_TOKEN_REQUEST as a phase, then the parameter would have been added to the request when flow.finish() is invoked. See javadocs for more information. The parameter readOnly is not part of the OAuth 2 specification and is used in the example for demonstration of how to configure the flow for needs of specific service providers (in this case, the readOnly param would be described in the service provider's documentation).

Between the calls to flow.start() and flow.finish(), a user must be redirected to the authorization URI. This means that the code will not be executed in a single method and the finish part will be invoked as a handler of redirect request back to our web from authorization URI. Check the OAuth 2 Google Client Web Application Example for more details on this approach.