DEV Community: Jonas Funcke

Web Services in Java 3 - Authorization Annotation

Jonas Funcke — Sun, 17 May 2020 16:47:42 +0000

When providing APIs to the web, we sometimes (or most of the times) want to manage whos, whichs and wheres. Or in other words who can access which data where.

Some theory

That's where authorization comes into play. Some (especially me, until I googled it) think that authorization is the same thing as authentication, but behold: this is not the case.
When we talk about authentication, we mean the process where the client introduces itself to the provider.
For example: the part where we type in our username and password.
The result is most of the times some form of entry pass. For example a session, an API Key or something else.

Authorization on the other hand, handles which authenticated user can access what type of resource. A very common example for this process is a role system.

Let's get to work

Now that we know what we want to achieve, let's take a look at our Java code.

Java offers many ways to associate a so-called filter - a component, that gets executed around a request - with a route or a resource.
Many of these include a web.xml or similar complicated matters.
That's why we will focus on a annotation based approach:

What we want to achieve:

@Path("")
public class ExampleResource {
    @GET
    @Path("all")
    @Produces(MediaType.APPLICATION_JSON)
    @Authorization("example:read")
    public String getAll() throws Exception{
        return "{ \"message\": \"Hello World\"}";
    }
}

The good thing is that most javax.ws.rs implementations already implement most of these features.
The only thing we will need to implement is the @Authorization annotation.

1. The annotation interface

To create an annotation, we need an interface declaring it. This looks like this:

// Retention declares the time of evaluation.
// As we want to have it evaluated at runtime, we declare it runtime.
@Retention(RUNTIME)
@Target({TYPE, METHOD}) // This annotation specifies where this annotation can be used.
public @interface Authorization {
    /**
     * List of roles that are permitted access.
     */
    String[] value();
}

2. Annotation Handler Class

Okay, now we have an annotation. ...but it does nothing at all right now.
That's why we need to declare a filter to handle annotated resources:

/**
 * When deploying your application as .war or .jar into a web server,
 * this annotation declares the class as provider for a filter.
 */
@Provider
public class AuthorizationFilter implements ContainerRequestFilter
{
     @Override
     public void filter(ContainerRequestContext requestContext) {
         // TODO: Fill
     }
}

Our filter implements the ContainerRequestFilter interface from the Java REST Services extension. This interface requires a method called 'filter'.
This method will be called, when our filter is being applied to the request. It is being passed an instance of ContainerRequestContext, which provides metadata about the request.
For more information, check out the Official JavaDoc!

Our filter will handle authorization in its filter method.
But at first we need to check if the called resource is decorated with our annotation. To achieve this, we will provide our class with the ResourceInfo.
This is an object which holds information about the Java method, that is being evaluated in this request call.

public class AuthorizationFilter implements ContainerRequestFilter
{
    // Provides information about the called resource
    @Context
    private ResourceInfo resourceInfo;

    @Override
    public void filter(ContainerRequestContext requestContext) {
        // TODO: Fill
    }
}

The @Context annotation tells the server to provide this class with the corresponding instance of RequestContext automatically. So we don't have to worry about how this information gets here. Neat!

To keep the used identifiers consistent and to make future changes easier, we should also declare constant variables with our header and our scheme:

...
    // Provides information about the called resource
    @Context
    private ResourceInfo resourceInfo;
    private static final String AUTHORIZATION_HEADER = "Authorization";
    private static final String AUTHORIZATION_SCHEME = "Bearer";

    @Override
    public void filter(ContainerRequestContext requestContext) {
        // TODO: Fill
    }
...

Nice! Now let's get to work:

At first we need to check for the annotation:

    ...
    @Override
    public void filter(ContainerRequestContext requestContext) {
        Method calledMethod = resourceInfo.getResourceMethod();
        if(calledMethod.isAnnotationPresent(Authorization.class) {
           // Handle authorization
        }
    }
    ...

Now that we know that our annotation is present, we need to check if the authorization header in our request is present. If not, we can just stop processing the request and return a 403.

    ...
    if(calledMethod.isAnnotationPresent(Authorization.class) {
        String authorization = requestContext.getHeaderString(AUTHORIZATION_HEADER);
        //If no authorization information present; block access
        if(authorization == null || authorization.isEmpty())
        {
           throw new ForbiddenException("Resource Forbidden");
        }
    }
    ...

Annotation: Present
Header: Filled
Access Requirements: not yet fetched

We will do this by accessing the array of Strings we passed to the annotation.

    ...
    if(calledMethod.isAnnotationPresent(Authorization.class) {
        ...
        Authorization authAnnotation = calledMethod.getAnnotation(Authorization.class);
        Set<String> accessRequirements = new HashSet<>(Arrays.asList(authAnnotation.value()));
    }
    ...

Ok. In the incoming request, the authorization header is formatted in the following way:

Header Name	Header Value
Authorization	Bearer

This means, that our token is being preceded by the word Bearer. So we need to split the content of the authorization header to access the token:

    ...
    if(calledMethod.isAnnotationPresent(Authorization.class) {
        ...
        Authorization authAnnotation = calledMethod.getAnnotation(Authorization.class);
        Set<String> accessRequirements = new HashSet<>(Arrays.asList(authAnnotation.value()));
        final String key = authorization.replaceFirst(AUTHENTICATION_SCHEME + " ", "");
    }
    ...

Alrighty! Now that we have the token we need to check the access rights assigned to it. Normally we would call some form of data storage or something similar at this point. This really is out of the boundaries of this post though.

That's why we will implement a static map with our user data.

    // Provides information about the called resource
    @Context
    private ResourceInfo resourceInfo;
    private static final String AUTHORIZATION_HEADER = "Authorization";
    private static final String AUTHORIZATION_SCHEME = "Bearer";

    private static final Map<String, Set<String>> userData = new HashMap<String, Set<String>>() {{
        put("admin", new HashSet<String>(){{
            add("example:read");
        }});
        put("example_user", new HashSet<String>() {{
            add("example:write");
        }});
    }};

    @Override
    public void filter(ContainerRequestContext requestContext) {
        ...
    }
...

This will give us two tokens. One with the right to read in our example resource and one with the right to write the example resource.
For the endpoint we have at the beginning of this post, we specified example:read as access requirement. This means, that only the admin user can access the secured resource.

Token	Access Rights
admin	[example:read]
example_user	[example:write]

Now we should check, if the sent token has the correct access rights. To make our code more readable, we should really put this check in its own method:

...
    private boolean authorize(final String key, final Set<String> accessRights)
    {
        boolean isAllowed = false;
        Set<String> permittedActions = userData.get(key);

        if(permittedActions != null && permittedActions.stream().anyMatch(accessRights::contains))
            isAllowed = true;

        return isAllowed;
    }
}

And check for its result

...
    Set<String> accessRequirements = new HashSet<>(Arrays.asList(authAnnotation.value()));
    final String key = authorization.replaceFirst(AUTHENTICATION_SCHEME + " ", "");
    if(!authorized(key, acessRequirements))
        throw new ForbiddenException("Resource forbidden");
}

That's it! That's our authorization handling. If you want the complete code, check out this gist.

Now that we have our annotation and our annotation handling, we need to provide our solution to the server.
As this is part of a series, I will refer to the type of server we implemented in Part 1.
In this case, we just add it to the resources declared in our resource config:

// Main.java
...
ResourceConfig resourceConfig = new ResourceConfig(); 
resourceConfig.register(ExampleResource.class); // our rest resource
// the parser for JSON and XML request bodies
resourceConfig.register(JacksonFeature.class);
resourceConfig.register(AuthorizationFilter.class);

Now we have a way to secure our API.
Enjoy!

Image Credits:
Photo by Siarhei Horbach on Unsplash

Web Services in Java 2 - Provide REST Resources

Jonas Funcke — Mon, 30 Sep 2019 11:24:18 +0000

Hi, welcome back. Hopefully everything we did in part 1 worked out for you. If anything didn't please leave us a comment and we will look into it as soon as possible.

In this post we will learn how a REST handler looks in Java and what we can do to tell our server that is exists.

How are REST Resources structured and how will we access them?

In general, a common approach for structuring Java Applications, is to group actions into logical groups. E.g. all calls working with Users as their target will be grouped into a class named UsersController. In general, the most common HTTP Request Methods are being associated with a concrete action type:

GET - fetch data
POST - create data
PUT/PATCH - update data
DELETE - destroy data

There are of course lots of other request methods but we will mainly focus on those four as they provide nearly all capabilities we need for our small project.

Here we can look at a small example controller:

    @Path("")
    public class ExampleResource {
        @GET
            @Produces(MediaType.TEXT_HTML)
        public String hello() {
            return "<h1>Hello World</h1>";
        }

            @GET
            @Path("test")
            @Produces(MediaType.APPLICATION_JSON)
            public String test() {
                return "{ \"Hello\": \"World\"}";
            }
    }

The @Path Annotation tells the server the base path the controller is operating at. This annotation can also be put on top of the handler Method. The path this method is listening at will then be created by joining the strings from the annotation on the class and on the method using a/

Every Method, that should handle a Request, will also get an annotation with the name of the HTTP Method it supports. In this small example our two methods only support GET.

Tell the server what we want and what we give

With @Produces and @Consumes we tell the server what type of content our method wants and what type of content it will return back to the consumer. In the Javax.ws.rs specification, there is a Enum provided that's called MediaType. It contains all the media types supported by Java. To serve HTML, we will pass MediaType.TEXT_HTML to the @Produces annotation. If we want to get some JSON from the request, we just tell the server in the @Consumes annotation with MediaType.APPLICATION_JSON.

Pass input with the request

That's nice and all, but how the heck can we check if the input from our request is cool?

No biggie. We just gonna create a class for it:

    public class MyFancyInput 
        private String username;
        private Integer age;
        private Boolean acceptTOS;

        public String getUsername() {
            return this.username;
        }

        public void setUsername(String username) {
            this.username = username;
        }

        public Integer getAge() {
            return this.age;
        }

        public void setAge(Integer age) {
            this.age = age;
        }

        public Boolean getAcceptTOS() {
            return this.acceptTOS;
        }

        public void setAcceptTOS(Boolean acceptTOS) {
            this.acceptTOS = acceptTOS;
        }
    }

A request body object is just a plain Java POJO. All the properties must have a getter and a setter method as the deserialization will try to call them. To ensure that a null field will not break our service, we only use non-primitive datatypes. This is because boolean for example does not support null types but Boolean does.

When you input class is done, we will just tell our operation that we want that as parameter:


    @Path("")
    public class ExampleResource {
        @GET
            @Produces(MediaType.TEXT_HTML)
        public String hello() {
            return "<h1>Hello World</h1>";
        }

            @GET
            @Path("test")
            @Produces(MediaType.APPLICATION_JSON)
            public String test() {
                return "{ \"Hello\": \"World\"}";
            }

            @POST
            @Path("test")
            @Consumes(MediaType.APPLICATION_JSON)
            @Produces(MediaType.APPLICATION_JSON)
            public MyFancyInput getInput(@NotNull MyFancyInput input) {
                return input;
            }
    }

Here we just get the input and return it to the client again. With the @NotNull annotation we tell the server that the parameter for this method is required and cannot be null.

If the input comes from a special place in the request, we just annotate it with the right annotation. Available annotations are:

@BeanParam
@CookieParam
@FormParam
@PathParam
@QueryParam
@MatrixParam

Link it all together

We have the resource, we have the data structure, and if you did Part 1, you also have the server. Now we need to connect it all:

In our main class, we just add something to our ResourceConfig:

    // Holds all the resources we want to register (currently, there's nothing to do)
    ResourceConfig resourceConfig = new ResourceConfig();
    resourceConfig.register(ExampleResource.class); // our rest resource
    // the parser for JSON and XML request bodies
    resourceConfig.register(JacksonFeature.class);

Now when we run our server, we should be able to reach the resources we just create at localhost:8080/and on localhost:8080/test

After all of this, our project structure should look something like this:

src
- main
    - java
        - Main.java
        - ExampleResource.java
        - MyFancyInput.java
- test

I hope you had fun and everything worked out for your. Have an awesome day! :D

Web Services in Java 1 - Configure the server

Jonas Funcke — Sun, 29 Sep 2019 11:31:51 +0000

Java is a joy for backend work. It not only performs well, but also has simmered a long time in the industry, marking it as a battle-tested and solid platform.

What helps making Java so highly efficient and strong as a server-side language, is that it is fully customizable. You can build you application from nearly every combination of available libraries and select only the functionality you want.

This has its advantages. Though it also makes every project some sort of Lego building task. Unfortunately, it does not quite work like with off-the-shelf Lego sets. To use the feature you like or need, you need to pick a package. This gets quite into detail going so far that for a server to correctly running, you need to pick a XML/JSON parser.

To provide a step-by-step guide to your first app, we will, in this series, look at how we can

configure a server (embedded Jetty)
add some REST API to it (Jersey)
provide a database (Hibernate)
inject it with DI
Provide a small ui with Vue.js

Create Project

As a build and dependency tool for our project, we will use Gradle. This will allow us to specify dependencies we need for our project. A project using Gradle has the following structure:

src
- main
    - java
    - resources
- test
    - java
    - main
build.gradle
settings.gradle

In the src directory we will put all our source. Here we have a subdirectory for our tests - test - **and another one for our application - main. In each of the two is a directory for Java code called **java and for additional file resources resources.

In build.gradle we store all our project configuration and in settings.gradle we will configure our project.

Here is the build.gradle used for this series:

plugins {
    id 'java'
}

group 'JettyServer'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.glassfish.jersey.containers:jersey-container-servlet:2.28'
        compile 'org.eclipse.jetty:jetty-server:9.4.19.v20190610'
        compile 'org.eclipse.jetty:jetty-servlet:9.4.19.v20190610'
        compile 'org.glassfish.jersey.inject:jersey-hk2:2.28'
        compile 'jakarta.xml.bind:jakarta.xml.bind-api:2.3.2'
        runtime 'org.glassfish.jaxb:jaxb-runtime:2.3.2'
    compile 'org.eclipse.jetty:jetty-servlets:9.4.19.v20190610'
    compile 'org.glassfish.jersey.media:jersey-media-json-jackson:2.28'
    compile 'org.hibernate:hibernate-core:5.4.4.Final'
    compile 'org.xerial:sqlite-jdbc:3.20.1'
    compile 'com.zsoltfabok:sqlite-dialect:1.0'
}

Create a server in Java

Some of you may have already had experiences with other web technologies like Rails, Flask, Express.js, etc. In these languages the creation of the server is mostly hidden from you. You may create an object and initialize it or everything just runs out of the box. With our server, it is not like that. But let's see:

At first, we need our Main class with the main method, here we will put all our start code.

public class Main {
    public static void main(String[] args) throws Exception {

    }
}

First, we will need a Queue holding all the threads we will use to handle requests. Be careful, if you make it too large, it will use up all your system resources, if you make it too small, it will not handle all your load. In our case, we will give it a start capacity of 20, let it grow by 2 and limit the queue to 80. We will provide this queue to our Thread Pool, it will handle the distribution of jobs to our queue.

public static void main(String[] args) {
//Queue initialization
    BlockingQueue<Runnable> threadPoolQueue = new BlockingArrayQueue<>(20, 2, 80);
// Create ThreadPool for the server to use.
// default idle time as defined in the QueuedThreadPool.
    QueuedThreadPool threadPool = new QueuedThreadPool(20, 2, (int) TimeUnit.MINUTES.toMillis(1), threadPoolQueue);
  threadPool.setName("jetty-test-server");
  threadPool.setDaemon(true);
}

Now that we have our system resources set, we need to create a Server. We will do this by creating an instance of the Server class and a ServerConnector class. The connector will open the server to the network.

// Instance of server object - adds the threadPool to use
Server server = new Server(threadPool);
// instance of server connector with server instance to handle connections for
ServerConnector connector = new ServerConnector(server);
// set port to use
connector.setPort(8080);
// add connector to server
server.setConnectors(new Connector[]{connector});

Next we add a ServletContextHandler for our REST-Resources. This context handler is responsible to provide an environment for execution of the Request Handler methods. This includes Request, Response, Session and other important resources.

final ServletContextHandler servletContextHandler = new ServletContextHandler();
servletContextHandler.setContextPath("/");

The ContextHandler is set up. The next step is to provide a ServletHolder for the ContextHandler to operate on. A ServletHolder is used for state management and for correctly handling paths. It contains a ServletContainer that is itself just an instance of a Servlet (a resource callable by the server) that is being initialized with all Resources we want to use in our Application.

// Holds all the resources we want to register (currently, there's nothing to do)
ResourceConfig resourceConfig = new ResourceConfig();
// handles state for servlets
final ServletHolder servletHolder = new ServletHolder(new ServletContainer(resourceConfig));
servletContextHandler.addServlet(servletHolder, "/*");

When we have our ServletContextHandler initialized, it is time to provide it to our server, so that it can delegate requests to it. For this, we will use an instance of HandlerList and initialize it with our ServletContextHandler and pass it to our server.

HandlerList handlers = new HandlerList();
handlers.setHandlers(new Handler[] {servletContextHandler});
server.setHandler(handlers);

We got everything in place (Yaaaay :D). Let's start our server:

server.start();
server.join();

It now runs on port 8080.

Hi, I'm Jonas Funcke

Jonas Funcke — Fri, 30 Jun 2017 07:03:19 +0000

I have been coding for 2 years.

You can find me on GitHub as Funcke
(https://github.com/Funcke)

I live in [city].

I work for [company]

I mostly program in these languages: C/C++, C#.

I am currently learning more about Linux device drivers.

Nice to meet you.