@josempgon/vue-keycloak NPM

vue-keycloak

A small Vue wrapper library for the Keycloak JavaScript adapter.

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

Instalation

Install the library with npm.

npm install @josempgon/vue-keycloak

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/auth',
    realm: 'myrealm',
    clientId: 'myapp',
  }
})

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 dynamic Keycloak configuration.

app.use(vueKeycloak, async () => {
  return {
    config: {
      url: (await getAuthBaseUrl()) + '/auth',
      realm: 'myrealm',
      clientId: 'myapp',
    },
    initOptions: {
      onLoad: 'check-sso',
      silentCheckSsoRedirectUri: window.location.origin + '/assets/silent-check-sso.html',
    },
  }
})

Use Token

A helper function is exported to manage the authentication token.

getToken

Function	Type	Description
getToken	(minValidity?: number) => Promise\<string>	Returns a promise that resolves with the current authentication 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 { computed } from 'vue'
import { useKeycloak } from '@josempgon/vue-keycloak'

const { hasRoles } = useKeycloak()

const hasAccess = computed(() => hasRoles(['RoleName']))
</script>

useKeycloak

The useKeycloak function exposes the following data.

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

const {
  // Reactive State
  isAuthenticated,
  isPending,
  hasFailed,
  token,
  decodedToken,
  username,
  userId,
  roles,
  resourceRoles,

  // Object Instances
  keycloak,

  // Functions
  hasRoles,
  hasResourceRoles,
} = useKeycloak()

Reactive State

State	Type	Description
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` authentication request has failed.
token	`Ref<string>`	Raw value of the JWT token.
decodedToken	`Ref<KeycloakTokenParsed>`	Decoded value of the JWT 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.

Object Instances

Instance	Type	Description
keycloak	`Keycloak`	Instance of the keycloak-js adapter.

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.