REST API Security Guide

Knowledge of how to secure REST APIs is as much important as to write the APIs itself. Mostly REST APIs are HTTP protocol based, and any user having internet connection can access them, and so can bad users as well. It is very important to write secure APIs to protect the business.

Before starting to secure RESTful APIs, let’s understand what all are our options as developers? What will be good fit for our usecase?

Table of Contents

1. Authentication vs. Authorization
2. Four Ways to Secure RESTful Web Services
	- BASIC Authentication
	- DIGEST Authentication
	- Client CERT Authentication
	- OAUTH2 API Keys
3. RESTful Web Services Security Implementations
	- Using SecurityContext
	- Using Annotations
4. Best Practices

1. Difference between authentication vs. authorization

Before jumping into main discussion, let’s make our facts straight about what is authentication and what is authorization.

In plain simple English, authentication is the process of ascertaining that “is user really someone who he claims to be“. In technical terms, it’s process of login to system through username/password or any similar mechanisms e.g. finger print scanning, security token, security questions or SAML token received from SSO login. There must be something which can identify the user from others.

Once user is inside system, authorization refers to rules that determine “what user is allowed to do” and what he is not e.g. a normal user can post a message in any public group, but users only with editor role will be able to delete something. Authorization is often seen as both the introductory setting up of permissions by a system administrator and the checking of the permission values that have already been set up when a user is getting access to the system.

When we secure RESTful web services, we need to take care of both the factors. The two concepts are completely orthogonal and independent, but both are central to security design, and the failure to get either one correct increase the chances of compromised system..

2. Four Ways to Secure RESTful Web Services

There are multiple ways to secure a RESTful API in Java. Let’s go through 4 most popular choices:

2.1. BASIC Authentication

It’s simplest of all techniques and probably most used as well. You use login/password forms – it’s basic authentication only. You input your username and password and submit the form to server, and application identify you as a user – you are allowed to use the system – else you get error.

The main problem with this security implementation is that credentials are propagated in a plain way from the client to the server. Credentials are merely encoded with Base64 in transit, but not encrypted or hashed in any way. This way, any sniffer could read the sent packages over the network.

HTTPS is, therefore, typically preferred over or used in conjunction with Basic Authentication which makes the conversation with the web server entirely encrypted. The best part is that nobody can even guess from the outside that Basic Auth is taking place.

2.2. DIGEST Authentication

This authentication method makes use of a hashing algorithms to encrypt the password (called password hash) entered by the user before sending it to the server. This, obviously, makes it much safer than the basic authentication method, in which the user’s password travels in plain text that can be easily read by whoever intercepts it.

Read More: Generate Encrypted Passwords

There are many such hashing algorithms in java also, which can prove really effective for password security such as MD5, SHA, BCrypt, SCrypt and PBKDF2WithHmacSHA1 algorithms.

Please remember that once this password hash is generated and stored in database, you can not convert it back to original password. Each time user login into application, you have to regenerate password hash again, and match with hash stored in database. So, if user forgot his/her password, you will have to send him a temporary password and ask him to change it with his new password. Well, it’s common trend now-a-days.

2.3. Client CERT Authentication

This is a mechanism in which a trust agreement is established between the server and the client through certificates. They must be signed by an agency established to ensure that the certificate presented for authentication is legitimate, which is known as CA.

Using this technique, when the client attempts to access a protected resource, instead of providing a username or password, it presents the certificate to the server. The certificate contains the user information for authentication including security credentials, besides a unique private-public key pair. The server then determines if the user is legitimate through the CA. Additionally, it must verify whether the user has access to the resource. This mechanism must use HTTPS as the communication protocol as we don’t have a secure channel to prevent anyone from stealing the client’s identity.

You can find a complete tutorial for generating security certificate in official oracle docs.

2.4. OAUTH2 API Keys

If you have ever developed applications which interact other with other applications over cloud e.g. facebook integration or twitter authentication etc. then you have already used this. They require you to provide API key and API secret to rightly identify you. These API key and secret are some random encoded string which is impossible to guess.

To understand how it works, let’s assume you are using a Flickr (photo sharing application) and want to post some of your photos using it’s REST API. You build the request as documented in Flickr docs, then send it.

Then, when receiving the request, Flickr authenticates the user by reading the information from the API key with the secret key that belongs to the user. Once these validations are successful, the server delivers the response to the client. Thus, we obtain a response with all the photos that have been recently posted within Flickr.

As you’ll notice, this way, you can easily create applications using the provider’s API. Also, the provider will allow you to authenticate, access public information.

If someone starts disrespecting agreements e.g. sending junk traffic or any policy violation, the provider withdraws the API key and prevent the abusive use of its APIs.

3. REST API Security Implementations

Apart from above concepts, you will usually need to secure your RESTful APIs in your company using below methods.

3.1. JAX-RS SecurityContext instance

The interface provides access to security-related information for a request and is very similar to javax.servlet.http.HttpServletRequest.

You access the SecurityContext by injecting an instance into a class field, setter method, or method parameter using the annotation e.g. in below code sc.isUserInRole() is used to check authorization for user.

public String sayHello(@Context SecurityContext sc) {
        if (sc.isUserInRole("admin"))  
        	return "Hello World!";
        throw new SecurityException("User is unauthorized.");

3.2. JAR-RS annotations for method level authorization

This technique is widely used in enterprise application and used to verify roles and responsibities of an authenticated used – for any certain operation. JAX-RS provides below annotations for this purpose.

An example use of annotation can be:

public Response updateUserById(@PathParam("id") int id)
    //Update the User resource
    return Response.status(200).build();

Read More : JAX-RS authentication and authorization example

4. REST API Security Best Practices

Let’s note down some important points while designing security for your RESTful web services.

  1. Use only HTTPS protocol so that your whole communication is always encrypted.
  2. Never send auth credentials or API keys as query param. They appear in URL and can be logged or tracked easily.
  3. Use hardest encryption level always. It will help in having more confidence.
  4. For resources exposed by RESTful web services, it’s important to make sure any PUT, POST, and DELETE request is protected from Cross Site Request Forgery.
  5. Always validate the input data asap it is received in server method. Use only primitive data as input parameter as much as possible.
  6. Rely on framework provided validation features as they are tested by large community already.

Let me know your thoughts and experiences on how to secure RESTful web services in your organization.

Happy Learning !!

Leave a Reply

Most Voted
Newest Oldest
Inline Feedbacks
View all comments

About Us

HowToDoInJava provides tutorials and how-to guides on Java and related technologies.

It also shares the best practices, algorithms & solutions, and frequently asked interview questions.