Understanding OAuth 2.0 as so to manage authorization and control user access on your REST resources is essential part of enterprise Java applications. Fortunately, Spring Security and Spring Security OAuth provide a solid framework which you can easily exert in your projects and grant access to the clients and their users on protected resources while still complying with the OAuth 2.0 specification. However, the Spring Security might be challenging to get started, since the effort requires some experience with the framework as well as OAuth 2.0 specification. Because, the Spring documentation covers the topic from the implementation perspective by explaining how to put the framework in use and the RFC 6749 is a specification explaining how things should work in that context, with these blog series my goal is to give an overview about OAuth 2.0 concepts with a real-life example of an OAuth-aware back-end incorporating with Spring Boot by melting the theory and the practice in a single pot.

OAuth 2.0 in a Nutshell

OAuth 2.0 is an authorization protocol standardized under RFC 6749 within the IETF as an open standard, of which purpose is to define the rules such that to realise user and client authorisation on protected resources without sharing their credentials with each other. The roles defined in OAuth are:

the resource owner, that is the end-user who owns resource, the resource hosted by a resource server, the third party application, which is the client, that needs access on resource owner’s protected resources and perform some operations on behalf of the end-user and the authorization server which manages user and client authentication and authorisation.

The authorization workflow is triggered by the the client, that is the application requesting access on resource owner’s resources on behalf of him, e.g a mobile app or a web service. The Resource Server is the server which hosts protected resources. It accepts the requests on these resources with access token and enforce the authorisation rules. The authorization server, the server issues access tokens to the clients after a successful authentication.

Access Token

Access tokens are credentials issued to the client allowing them access protected resources. They are valid until the expiration time and might be effective in a certain scope specified by the client. By issuing access tokens to the clients, we eleminate the need of sharing resource owner’s credentials, so the client applications like mobile apps do not need to know user’s credentials.

There is one more token type, that is refresh token. Refresh token is only used to obtain a new access token before the access token expires. If you think about it, it makes also sense. Once you authorize your mobile app, you don’t want to re-authenticate yourself everytime the access token expires. In this case, the client may use the refresh token to obtain a new access token from the authorization server.

Authorization Grants

In the OAuth 2.0 world, the mantra is not to share user credentials with 3rd party applications like a mobile app used by a user. The application, the client, might be a native application running as native application in the OS, or some JavaScript application run by a browser. Depending on the degree of the trust between client and user, a client might use the user credentials to obtain an access token. It requires, however, a high degree of trust. Even though the client is allow to see the user credentials in this authorisation grant “Resource Owner Password Credentials”, it is over a short period of time, till it acquires the access token from the authorisation server.

Auth code

On the other hand, the client might be another web service, and in this case the user will be redirected to the authorization server with the client id, optional scope parameter and redirection URI by the client so that the user can authenticate itself. A appropriate real-life example is Facebook integration on Twitter. Twitter, the client, needs access on protected resources to post your recent tweets on your Facebook timeline. After a successful authentication, the request will be redirected to the clients redirection URI with an authorization code, with which the client can request an access token from authorisation server. In this “authorization code” grant, the client access to the user credentials is not permitted.

There are two more authorization grants, the “implicit” one and the “client credentials”. In the implicit workflow, the user-agent will be redirected to the client, directly, with an access token, instead of with an auth code and without requiring the client to get authenticated with the auth code. This type of authorization we are familiar of from the JavaScript web applications. The authorization grand with “client credentials” requires the client to get authenticate itself with its own credentials. This type of authorisation grant is useful in case the client is the resource owner and defines the scope of access.


Scope defines the boundaries of the authorization. The authorisation server might allow the clients to specify the scope for the access requests with the scope parameter in which scope the access token should be effective. RFC 6749 3.3

Scopes are optional in workflows.

So far, I have covered some essential topics of the OAuth 2.0, that we need to understand to build our enterprise authorization backend. But, there is more. If you are interested in OAuth 2.0 I encourage you to read the RFC 6749. It is in my opinion the most concise document describing the workflows.

Next step, we are going to start building our backend components like Authorization Server, Resource Server, etc. to implement OAuth 2.0 spec and to grant access to our protected resources. The resources are sample REST resources just giving out some important information like “Hello World”, that we want to protect.

Building the Backend

I am going to set up a docker container environment to start the whole back-end on my local computer while developing the components. To work with docker container environment will accelerate our development and test cycle and later on once we decide to deploy our back-end much more easier to roll it out onto a container orchestration platform like Mesos or Kubernetes.

First things first and we need is a database to store the user data like username, password, etc. For this purpose, I will use a MySQL Database with the following schema:

CREATE TABLE `users` (
  `accountNonExpired` tinyint(4) NOT NULL,
  `accountNonLocked` tinyint(4) NOT NULL,
  `credentialsNonExpired` tinyint(4) NOT NULL,
  `enabled` tinyint(4) NOT NULL,
  `password` varchar(255) NOT NULL,
  `username` varchar(255) NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `UK_r43af9ap4edm43mmtq01oddj6` (`username`)

Just keep in mind this SQL schema. After starting the database, we will revisit and apply it with your favourite mySQL client to the database and create the table above.

version: '2'
    image: ryos-auth
    - auth-db
    -  "9000:8080"
    image: mysql/mysql-server
    - MYSQL_DATABASE=ryos_auth
    - MYSQL_USER=ryos
    - MYSQL_PASSWORD=123456
    - "3306:3306"

To build our backend, we will start off with a Maven project and inherit our Maven POM from Spring Boot parent, that is very convenient and ensures that the right versions of Spring dependencies will be added to the project. For the sake of ease, I will create a single project which include both the resource and the authorization server in the same application, but in production, you may want to split them into two separate services.

        <relativePath />

We will also need the following dependencies to enable the Spring Framework in the project:


As you may have noticed, the project defines some database dependencies, as well, in addition to those which are required for the OAuth. The idea is basically to keep the user data in a database table. Alternatively, we could store the user data in a in-memory database, this is provided by the Spring Framework.

The first component we create is the authorization server. I will create all components in a single Spring Boot project for the sake of ease. In a real-life application, you need probably consider to create separate applications for the authorization and resource server.


In this update, we now know how to create the foundation and start the components by spinning up the containers by using docker-compose. I am continuously updating the article and certainly will someday be complete. Just stay tuned!