vue-keycloak

A small Vue wrapper library for the Keycloak JavaScript adapter.

This library is made for Vue 3 with the Composition API.

Installation

Using npm:

npm install @josempgon/vue-keycloak

Using yarn:

yarn add @josempgon/vue-keycloak keycloak-js

Using pnpm:

pnpm add @josempgon/vue-keycloak keycloak-js

Use Plugin

Import the library into your Vue app entry point.

import { vueKeycloak } from '@josempgon/vue-keycloak'

Apply the library to the Vue app instance.

const app = createApp(App)

app.use(vueKeycloak, {
  config: {
    url: 'http://keycloak-server',
    realm: 'my-realm',
    clientId: 'my-app',
  }
})

Configuration

| Object | Type | Required | Description | | ----------- | --------------------------------------------- | -------- | ---------------------------------------- | | config | KeycloakConfig | Yes | Keycloak configuration. | | initOptions | KeycloakInitOptions | No | Keycloak init options. |

initOptions Default Value

{
  flow: 'standard',
  checkLoginIframe: false,
  onLoad: 'login-required',
}

Dynamic Keycloak Configuration

Use the example below to generate a dynamic Keycloak configuration. In that example the Keycloak adapter is initialized in silent check-sso mode. Be aware that this mode could have limited functionality with recent browser versions (check Modern Browsers with Tracking Protection for additional info).

app.use(vueKeycloak, async () => {
  const url = await getAuthBaseUrl()
  const silentCheckSsoRedirectUri = `${location.origin}/silent-check-sso.html`
  return {
    config: {
      url,
      realm: 'my-realm',
      clientId: 'my-app',
    },
    initOptions: {
      onLoad: 'check-sso',
      silentCheckSsoRedirectUri,
    },
  }
})

Use with vue-router

If you need to wait for authentication to complete before proceeding with your Vue app setup, for instance, because you are using the vue-router package and need to initialize the router only after the authentication process is completed, you should initialize your app in the following way:

router/index.js

import { createRouter, createWebHistory } from 'vue-router'

const routes = [ /* Your routes */ ]

const initRouter = () => {
  const history = createWebHistory(import.meta.env.BASE_URL)
  return createRouter({ history, routes })
}

export { initRouter }

main.js

import { createApp } from 'vue'
import { vueKeycloak } from '@josempgon/vue-keycloak'
import vueKeycloakConfig from './config/vueKeycloak.js'
import App from './App.vue'
import { initRouter } from './router'

const app = createApp(App)

await vueKeycloak.install(app, vueKeycloakConfig)

app.use(initRouter())
app.mount('#app')

If you are building for a browser that does not support Top-level await, you should wrap the Vue plugin and router initialization in an async IIFE:

(async () => {
  await vueKeycloak.install(app, vueKeycloakConfig);

  app.use(initRouter());
  app.mount('#app');
})();

Use Token

A helper function is exported to manage the access token.

getToken

| Function | Type | Description | | ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------------- | | getToken | (minValidity?: number) => Promise<string> | Returns a promise that resolves with the current access token. |

The token will be refreshed if expires within minValidity seconds. The minValidity parameter is optional and defaults to 10. If -1 is passed as minValidity, the token will be forcibly refreshed.

A typical usage for this function is to be called before every API call, using a request interceptor in your HTTP client library.

import axios from 'axios'
import { getToken } from '@josempgon/vue-keycloak'

// Create an instance of axios with the base URL read from the environment
const baseURL = import.meta.env.VITE_API_URL
const instance = axios.create({ baseURL })

// Request interceptor for API calls
instance.interceptors.request.use(
  async config => {
    const token = await getToken()
    config.headers['Authorization'] = `Bearer ${token}`
    return config
  },
  error => {
    Promise.reject(error)
  },
)

Composition API

<script setup>
import { useKeycloak } from '@josempgon/vue-keycloak';

const { isPending, isAuthenticated, error, username, userId, keycloak } = useKeycloak();
</script>

<template>
  <div v-if="isPending">
    <h2>Loading...</h2>
  </div>
  <div v-if="isAuthenticated">
    <h1>Welcome to Your Keycloak Secured Vue.js App</h1>
    <h2>User: {{ username }}</h2>
    <h2>User ID: {{ userId }}</h2>
    <div>
      <button @click="keycloak.logout">Logout</button>
    </div>
  </div>
  <div v-if="error">
    <h2>Authentication Error</h2>
    <h3>{{ error }}</h3>
  </div>
</template>

<style>
#app {
  text-align: center;
}
button {
  cursor: pointer;
}
</style>

useKeycloak

The useKeycloak function exposes the following data.

Reactive State

| State | Type | Description | | --------------- | ------------------------------------------------------ | ------------------------------------------------------------------- | | keycloak | ShallowRef<Keycloak> | Instance of the keycloak-js adapter. | | isAuthenticated | Ref<boolean> | If true the user is authenticated. | | isPending | Ref<boolean> | If true the authentication request is still pending. | | hasFailed | Ref<boolean> | If true an error ocurred on initialization or Keycloak request. | | error | Ref<Error> | Info on error that ocurred (null if no error) | | token | Ref<string> | Raw value of the access token. | | decodedToken | Ref<KeycloakTokenParsed> | Decoded value of the access token. | | username | Ref<string> | Username. Extracted from decodedToken['preferred_username']. | | userId | Ref<string> | User identifier. Extracted from decodedToken['sub']. | | roles | Ref<string[]> | List of the user's roles. | | resourceRoles | Ref<Record<string, string[]> | List of the user's roles in specific resources. |

Functions

| Function | Type | Description | | ---------------- | --------------------------------------------------------- | ----------------------------------------------------------------- | | hasRoles | (roles: string[]) => boolean | Returns true if the user has all the given roles. | | hasResourceRoles | (roles: string[], resource: string) => boolean | Returns true if the user has all the given roles in a resource. |

License

This project is licensed under the Apache License 2.0.

Originally developed by Gery Hirschfeld (2021).

Maintained and extended by José Miguel Gonçalves (2021-present).