Skip to content

Latest commit

 

History

History
468 lines (359 loc) · 9.6 KB

README.md

File metadata and controls

468 lines (359 loc) · 9.6 KB
Raw

Auth

Authentication Plugin for Vue 3

Demo

  • Checkout online demo here
  • 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 @gravitano/vue-auth
# OR
yarn add @gravitano/vue-auth

Usage

Use as Vue Plugin

Install the plugin to your Vue app.

// main.js
import {createApp} from 'vue';
import Auth from '@gravitano/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
  store, // vuex store instance
  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 '@gravitano/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 '@gravitano/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: 'admin@example.com',
  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 '@gravitano/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 '@gravitano/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 '@gravitano/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

License

MIT