volverjs-auth-vue

Install

# pnpm
pnpm add @volverjs/auth-vue

# yarn
yarn add @volverjs/auth-vue

# npm
npm install @volverjs/auth-vue --save

Usage

This library exports three main classes: OAuthClient, LocalStorage and SessionStorage (plus the abstract Storage base class).

import { LocalStorage, OAuthClient, SessionStorage } from '@volverjs/auth-vue'

Storage

LocalStorage and SessionStorage provide a way to interact with the browser localStorage and sessionStorage APIs. All the keys are scoped by the instance name, so you can use the same key name in different storages.

import { LocalStorage } from '@volverjs/auth-vue'

if (LocalStorage.supported()) {
    const myLocalStorage = new LocalStorage('my-local-storage')
    // set a specific key
    myLocalStorage.set('my-key', 'my-value')
    // get a specific key
    myLocalStorage.get('my-key', 'default-value')
    // delete a specific key
    myLocalStorage.delete('my-key')
    // clear all keys present in our storage
    myLocalStorage.clear()
}

OAuthClient

The OAuthClient class is a wrapper of oauth4webapi to simplify the authentication process of a Vue 3 application. By default it uses LocalStorage to store the refresh token, the code verifier and the PKCE/OIDC state and nonce values.

[!WARNING] By default the refresh token is persisted in localStorage, which survives tab closes and browser restarts and is readable by any JavaScript on the origin (a single XSS flaw exposes it). Set storageType: 'session' (or provide a custom storage) when you don't need persistent, cross-tab sessions.

import { ClientSecretBasic, OAuthClient, SessionStorage } from '@volverjs/auth-vue'

const authClient = new OAuthClient({
    // The URL of the OAuth issuer
    url: 'https://my-oauth-server.com',
    // The client id of the application
    clientId: 'my-client-id',
    // The client authentication method, default: None()
    // Are also supported: ClientSecretPost, ClientSecretBasic, PrivateKeyJwt, None, TlsClientAuth
    clientAuthentication: ClientSecretBasic('my-client-secret'),
    // The scopes requested to the OAuth server
    scopes: 'openid profile email',
    // Convenience setting to choose the storage, default: 'local'
    // Use 'session' to persist into sessionStorage instead of localStorage
    storageType: 'session',
    // The storage to use for persisting the refresh token, default: new LocalStorage('oauth')
    // Takes precedence over `storageType` when provided
    storage: new SessionStorage('my-session-storage'),
    // The redirect URI of the application, default: document.location.origin
    redirectUri: 'https://my-app.com/callback',
    // The URI to redirect the user after the logout, default: document.location.origin
    postLogoutRedirectUri: 'https://my-app.com',
})

The OAuthClient class provides a set of (async) methods to interact with the OAuth server:

// initialize the OAuth client (performs OAuth server discovery)
// when a code is present in the URL it completes the authorization code flow,
// otherwise it refreshes the access token if a refresh token is available
await authClient.initialize()
// redirect the user to the OAuth server to authorize the application
await authClient.authorize()
// handle the OAuth server authorization code response manually
// (usually not needed: initialize() does it for you)
await authClient.handleCodeResponse(new URLSearchParams(window.location.search))
// refresh the access token
await authClient.refreshToken()
// logout the user
authClient.logout()

The OAuthClient class also provides a set of getters to retrieve the OAuth status: