itarone-vue-keycloak-plugin v1.1.2

Introduction

This document's purpose is to explain how to effectively use the itarone-vue-keycloak plugin in order to secure your vuejs application with Keycloak.

Setup

To use the itarone-vue-keycloak plugin, you have first to install it. To do so, you have to add the repository entry in your package.json:

{
   
  "repository": "http://nexus.devops.os/repository/npm-internal/",
  ...
}

and install the component with the following command:

npm install --save @os/itarone-vue-keycloak

Then import it in your application :

import keycloak from '@os/itarone-vue-keycloak'

and use it in main.js as the following:

...
Vue.use(keycloak, "/static/keycloak.json");

keycloak.json is the file that contains the configuration to secure your your application with keycloak For example :

{
  "realm": "keycloak-demo",
  "auth-server-url": "http://localhost:8080/auth",
  "ssl-required": "external",
  "resource": "frontend",
  "public-client": true
}

Usage

The Library inject a variable named vKey. This object provide the following methods :

In addition to that, itarone-vue-keycloak plugin emits the following events to be intercepted in your application.

• onTokenRefreshed: "keycloak-Token-Refreshed",
• onNotAuthenticated: "keycloak-Not-Authenticated",
• onSessionExpired: "keycloak-Session-Exprired",
• onUnauthorizedPath: "keycloak-Unauthorized-Path"

In order to intercept an event, you can achieve that by :

created() {
    this.$vKey.keycloakevents.$on(this.$vKey.eventTypes.onTokenRefreshed, () => {
       //do your stuff
    });
    this.$vKey.keycloakevents.$on(this.$vKey.eventTypes.onNotAuthenticated, () => {
      //do your stuff
    });
    this.$vKey.keycloakevents.$on(this.$vKey.eventTypes.onSessionExpired, () => {
      //do your stuff
    });
    this.$vKey.keycloakevents.$on(this.$vKey.eventTypes.onUnauthorizedPath, () => {
      //do your stuff
    });
  }

Secure paths

to explain the process, you may follow this example.

Let's assume we have 4 routes ('/', 'request','admin', 'user')

• '/' is public
• 'request' and user needs the user to be authenticated
• 'admin ensure that you have admin role to access it

const routes = [
  { path: "/", name: "Hello", component: Hello},
  {
    path: "/request",
    name: "Request",
    component: Request,
    meta: { requiresAuth: true }
  },
  {
    path: "/admin",
    name: "Admin",
    component: Admin,
    meta: { requiresAuth: true, role: "admin" }
  },
  { path: "/user",
    name: "User",
    component: User,
    meta: { requiresAuth: true } 
   }
];
...

meta attribute specify whether this resource require authentication or not and which role is secured by.

So, to secure your paths (menu items), call the method secureRouter of vKey as the following in your router

    ...
    router.beforeEach(async (to, from, next) => {
    Vue.prototype.$vKey.secureRouter(store,to,next);
    });