Authentication made easy in Vue.js with Keycloak

A user-centered implementation

Your team has decided to use “Keycloak” as the new secure tool and you, as a frontend developer, have to set up it in your Vue App(s) ? Congratulations ! You’ve just found a way to implement in a simple, smart and user-centered approach.

No setInterval function, no useless tokens stored

Like you, when I had to implement Keycloak in my Vue App I found several tutorials but most of them were treated as POC (Proof of concept) since they use setIntervalfunction to update the token or store useless token and token refresh. The fact is when i want to implement something, i want to be sure to master and understand how it works.

Discovering the Keycloak JS Adapter

After digging the Keycloak JS Adapter official documentation, I noticed that a Keycloak instance comes with a configuration, init options and two master functions :

Configuration

const keycloak = new Keycloak({
    url: 'http://keycloak-server/auth',
    realm: 'myrealm',
    clientId: 'myapp'
});

In the constructor, you pass the configuration of the Keycloak project.

init

keycloak.init(initOptions)
keycloak.init({
   onLoad: 'login-required'
})

The init function should be invoked once in your app. Init options can be set. For my case, I’ve decided to use the option onLoadwith the value login-requiredwhich checks if the user is already logged. If not, the Keycloak login page will be displayed.

updateToken

keycloak.updateToken(minvalidity: number)

The updateTokenfunction is used to refresh the access token and renew the session of the user. For instance, if the Access Token Lifespan in your realm settings is set to 5 minutes and you set 70 (seconds) as the minvalidity value, the updateToken function will check if the token will expire within those 70 seconds. If it doesn’t, nothing will be done. If it does, Keycloak will try to renew the session of the user. If the token has already expired, Keycloak will disconnect the user and will redirect to the login page.

The user-centered approach

After knowing how the Keycloak JS Adapter works, i’ve decided to set up Keycloak in a smart and user-centered approach. What does it mean ? It means that i focused on the updateToken function and thought about where and when to use it. According to me, the updateToken must be invoked when the user makes actions on the app. I’ve identified 3 of those :

• API Interactions: creation, edition, deletion…
• Navigation
• Focus on the app tab

It means that every time the user will make one of these events, the updateToken function must be invoked. So that if the user makes an action with an expired session, he will be disconnected instantly. This is important for the user to trust the app.

How many times I can see users that refresh themselves the page to make sure they are still connected.

Let’s see in the next section how i did it.

The implementation using Vue CLI

I assume that you already have a Vue App built with Vue CLI or that you are about to create one.

Create an env file with the configuration variables

The variables must be provided by your team. Don’t forget that each one must be prefixed by VUE_APP since it is handled that way with Vue CLI.

The env file

Install the Keycloak plugin with vue cli

npm i keycloak-js —S

Create the Keycloak plugin file

The plugin file will create a singleton instance of Keycloak which be available with the Vue global.

import Vue from 'vue';
Vue.$keycloak

It‘’s also easier to the other developers to find where the Keycloak instance is configured. The file must be placed in the plugins directory. You notice that the configuration values are set from the environment variables. If you use Netlify, it comes easy to customize them.

Keycloak plugin

Init Keycloak

In your main file (main.js or main.ts), init Keycloak using the login-requiredoption so if the user is already logged in, the Vue App will be bootstrapped. Otherwise, the login page will be displayed. Notice that Keycloak redirects to the page where it has been initiated. So if you load your app from a URL different that the homepage (product page for example), Keycloak will redirect to that product page.

Since the Vue App is lazy loaded, think to display a nice loading message to your users by editing the index html file in the public directory.

Update the user token

Since the updateTokenfunction takes a parameter and it must be used in several files, I decided to create a middleware function to make it easier to manage. I placed the file in a directory called ‘middleware’ similarly as Nuxt scaffolding. The middleware function returns the new token if updated.

Invoke the middleware in the user actions

Remember the actions I target : API Interactions, Navigation, Focus on the app tab.

API Interactions

I assume that you use Axios and even better the Axios Plugin for Vue CLI. You just have to add a request interceptor. It has 2 advantages.

• The first is to check before making the request if the user session is still valid
• The second is that the token is always updated in the Authorization headers of the API requests.

Axios interceptor request

Navigation

Just invoke the middleware in the $routecallback in the App.vue. So for each router navigation, the middleware will be invoked and will disconnect the user with an expired session.

Focus on the tab

The users of you app also have others opened tabs in their browser. So if they come back after a long time to your app tab, the middleware will be called. The following code can be placed in the main file.

Well, it’s all done. I hope you appreciated this guide to add Keycloak to you Vue App. I would be pleased to receive any clap or/and comment from you.

Resources

Vue CLI

Keycloak