Auth

Authentication Plugin for Vue 3 with Pinia management

• Auth
  • Demo
  • Dependencies
  • Installation
  • Usage
    • Use as Vue Plugin
    • Use with Composition API
      • login(payload: Object): Promise<AxiosResponse>
      • fetchUser(): Promise<AxiosResponse>
      • setToken(tokenData: string): void
      • setUser(userData: Object): void
      • logout(): boolean
      • forceLogout(): boolean
      • user: Object
      • loggedIn: boolean
    • Manually Creating The Auth Function
  • Default Options
  • Options
    • endpoints
    • token
    • user
    • moduleName
    • expiredStorage
    • redirect
    • registerAxiosInterceptors
    • storage
  • Implementing Refresh Token
    • Refresh Token Options
      • enabled
      • property
      • maxAge
      • storageName
      • name
      • autoLogout
  • License

Demo

• View example project here

Dependencies

• axios: Used as the default http client.
• Vuex: Used to store auth state.
• Vou Router: Used to redirect between pages.
• TypeScript: Written in TypeScript, optimize for Vue + TypeScript. But, also ship ESM and Common JS version on dist.

Installation

Install the package just like regular npm package.

npm i @halv/vue-auth
# OR
yarn add @halv/vue-auth

Usage

Use as Vue Plugin

Install the plugin to your Vue app.

// main.js
import { createApp } from 'vue';
import Auth from '@halv/vue-auth'; // 👈 import the plugin
import store from '~/store';
import router from '~/router';
import axios from 'axios';

const app = createApp(App);

app.use(Auth); // 👈 use the plugin

// or with custom options
// 👇
app.use(Auth, {
  options, // auth options
  axios, // axios instance
  router, // vue router instance
}); // 👈 use the plugin

app.mount('#app');

After that, you can access the plugin via $auth global property.

<template>
  <div v-if="$auth.loggedIn">Logged In as : {{ $auth.user.name }}</div>
</template>

If you are using composition API, you can also access the auth object by using inject method.

import { injectAuth } from '@halv/vue-auth';

// user is Ref
const { user } = injectAuth();

// access the user
console.log(user);

Use with Composition API

To use the auth in composition API, just import and use the useAuth function.

import { useAuth } from '@halv/vue-auth';

const auth = useAuth();

// OR with object destruction
const { user } = useAuth();

login(payload: Object): Promise<AxiosResponse>

Login the user and save token to the auth storage.

auth.login({
  email: '[email protected]',
  password: 'admin',
});

fetchUser(): Promise<AxiosResponse>

Fetch user data from API.

const user = await auth.fetchUser();
console.log(user);

setToken(tokenData: string): void

Manually Set User Token.

auth.setToken(token);

setUser(userData: Object): void

Manually set the user data.

const userData = {
  id: 1,
  name: 'Admin',
};

auth.setUser(userData);

logout(): boolean

Logout the current user.

auth.logout();

forceLogout(): boolean

Force logout the current user.

auth.forceLogout();

user: Object

Get the current user data.

console.log(auth.user);

loggedIn: boolean

Get the current logged in state.

console.log(auth.loggedIn);

Manually Creating The Auth Function

First, create auth.ts file under your src/plugins folder.

import { authOptions } from '~/config';
import store, { AppRootState } from '~/store';
import { createAuth } from '@halv/vue-auth';
import axios from 'axios';
import router from '~/router';

export const useAuth = () => createAuth<AppRootState>(authOptions, axios, store, router);

Then, in your component, just import and use it as regular composition function. For example:

<script setup lang="ts">
import { useAuth } from '~/plugins/auth';

// destruct user object from `useAuth` function
const { user } = useAuth();

console.log(user); // <-- user data
</script>

Default Options

This is the default options object:

import { AuthOptions } from '@halv/vue-auth';

export const defaultOptions: AuthOptions = {
  endpoints: {
    login: {
      url: '/auth/login',
      method: 'post',
    },
    logout: {
      url: '/auth/logout',
      method: 'delete',
    },
    user: {
      url: '/auth/me',
      method: 'get',
    },
  },
  token: {
    property: 'data.token',
    type: 'Bearer',
    storageName: 'auth.token',
    autoDecode: false,
    name: 'Authorization',
  },
  user: {
    autoFetch: true,
    property: 'data',
    storageName: 'auth.user',
  },
  moduleName: 'auth',
  expiredStorage: 'auth.expired',
  redirect: {
    home: '/',
    login: '/auth/login',
  },
  registerAxiosInterceptors: true,
  storage: {
    driver: 'secureLs', // supported: cookie, local, secureLs (secure local storage)
  },
};

Options

endpoints

• login

  • url: Login path. E.g. /user/login
  • method: HTTP Method. E.g. GET, POST, etc.

• logout

  • url: Logout path. E.g. /user/logout
  • method: HTTP Method. E.g. GET, POST, etc.

• user

  • url: Endpoint for getting user data. E.g. /my/profile
  • method: HTTP Method. E.g. GET, POST, etc.

token

• property

  Token property path using dot notation.
  • Type: string
  • Default: data.token

• type

  Token type.
  • Type: string
  • Default: Bearer

• storageName

  Token storage name.
  • Type: string
  • Default: auth.token

• autoDecode

  Auto decodes token when possible. Usually used when using JWT Token.
  • Type: boolean
  • Default: true

• name

  Token header name.
  • Type: string
  • Default:Authorization

user

• autoFetch

  Fetch user data automatically when user successfully logged in.
  • Type: boolean
  • Default: true

• property

  Property path of user data.
  • Type: string
  • Default: data

• storageName

  Storage name for storing user data.
  • Type: string
  • Default: auth.user

moduleName

Vuex's module name.

• Default: auth
• Type: string

expiredStorage

Storage name for storing token expiratin time.

• Type: string
• Default: auth.expired

redirect

• home

  Homepage path.
  • Type: string
  • Default: /

• login

  Login path.
  • Type: string
  • Default: /

registerAxiosInterceptors

Register custom axios interceptors when true. Set the value to false if you want to use your own interceptors.

• Type: boolean
• Default: true

storage

• driver

  • Type: string
  • Default: secureLs
  • Available Options: local | secureLs | cookie

Implementing Refresh Token

To implement refresh token, update your auth options like so:

import { AuthOptions } from '@halv/vue-auth'

export const defaultOptions: AuthOptions = {
  endpoints: {
    login: {
      url: '/auth/login',
      method: 'post',
    },
    logout: {
      url: '/auth/logout',
      method: 'delete',
    },
    user: {
      url: '/auth/me',
      method: 'get',
    },
+    refresh: {
+      url: '/auth/refresh_token',
+      method: 'get',
+    },
  },
  token: {
    property: 'data.token',
    type: 'Bearer',
    storageName: 'auth.token',
    autoDecode: false,
    name: 'Authorization',
  },
  user: {
    autoFetch: true,
    property: 'data',
    storageName: 'auth.user',
  },
  moduleName: 'auth',
  expiredStorage: 'auth.expired',
  redirect: {
    home: '/',
    login: '/auth/login',
  },
  registerAxiosInterceptors: true,
  storage: {
    driver: 'secureLs', // supported: cookie, local, secureLs (secure local storage)
  },
+  refreshToken: {
+    enabled: true, // <-- make sure the value is set to true
+    property: 'data',
+    maxAge: 60 * 60 * 24 * 30, // default 30 days
+    storageName: 'auth.refresh_token',
+    name: 'refresh_token',
+    autoLogout: true,
+  },
};

Refresh Token Options

enabled

Indicates the refresh token is enabled or not.

• Type: string
• Default: false

property

Path of refresh token property from the response.

• Type: string
• Default: data.refresh_token

maxAge

Maximum age of new token.

• Type: number
• Default: 60 * 60 * 24 * 30 (30 Days)

storageName

Storage name for storing refresh token data.

• Type: string
• Default: auth.refresh_token

name

Payload name to sent when refreshing token.

• Type: string
• Default: refresh_token

autoLogout

When true, user will forced to logout and login again when refresh token failed.

• Type: boolean
• Default: true