A simple light-weight authentication library for Vue 3


Keywords
vue, vuejs, vue3, auth, vue-auth, vue3-auth
License
MIT
Install
npm install vue3-auth@4.0.4

Documentation

🔑 Vue3 Auth

Zero-boilerplate authentication support for Vue 3!

Getting Started

$ yarn add vue3-auth

Demo

This is demo repo

Setup

import { createApp } from 'vue'
import router from './router'
import App from './App.vue'
import { authPlugin } from 'vue3-auth'

const app = createApp(App)

app.use(router).use(authPlugin, {
  router,
  fetch: axios,
  baseUrl: import.meta.env.VITE_BASE_URL,
  fullPathRedirect: true,
  watchLoggedIn: true,
  redirect: {
    login: '/login',
    logout: '/login',
    home: '/',
  },
  local: {
    endpoints: {
      login: { url: '/api/auth/login', method: 'post' },
      logout: { url: '/api/auth/logout', method: 'post' },
      user: { url: '/api/auth/user', method: 'get' },
    },
    token: {
      property: 'token',
      type: 'Bearer',
      name: 'Authorization',
    },
    user: {
      propertyInLogin: 'user',
      propertyInFetch: '',
      propertyRole: 'role',
      propertyPermission: 'permissions',
      autoFetch: true,
    },
  },
})

app.mount('#app')

Options

General options shared with all strategies. See AuthOption in types.ts for defaults.

fetch

  • Required

Plugin used axios instance to call api. see more

redirect

  • Default
redirect: {
  login: '/login',
  logout: '/login',
  home: '/'
}
  • login: User will be redirected to this path if login is required.
  • logout: User will be redirected to this path if after logout, current route is protected.
  • home: User will be redirected to this path after login if cannot redirect query.

watchLoggedIn

  • Default: true

When enabled (default) user will be redirected on login/logouts.

fullPathRedirect

  • Default: true

If true, use the full route path with query parameters for redirect

Local provider

Usage

To do a password based login by sending credentials in request body as a JSON object:

<template>
  <div>
    <form @submit.prevent="onLogin">
      <div>
        <label>Username</label>
        <input type="text" v-model="state.username" />
      </div>
      <div>
        <label>Password</label>
        <input type="text" v-model="state.password" />
      </div>
      <div>
        <button type="submit">Submit</button>
      </div>
    </form>
  </div>
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { useAuth } from "vue3-auth";

const { login } = useAuth()

const state = reactive({
  username: '',
  password: ''
})

const onLogin = async () => {
  try {
    let response = await login(state)
    console.log(response)
  } catch (e) {
    console.log(e)
  }
}
</script>
  • After login
<!-- admin page -->
<template>
  <div>
    Username: {{ user.username }}
    Email: {{ user.email }}
    loggedIn: {{ loggedIn }}
  </div>
</template>

<script lang="ts" setup>
import { useAuth } from "vue3-auth";

const { user, loggedIn } = useAuth()
</script>

Options

endpoints

  • Default
endpoints: {
  login: { url: '/api/auth/login', method: 'post' },
  logout: { url: '/api/auth/logout', method: 'post' },
  user: { url: '/api/auth/user', method: 'get' },
}

token

  • Default
token: {
  property: 'token',
  type: 'Bearer',
  name: 'Authorization',
}
  • property can be used to specify which field of the response JSON to be used for value. It can be false to directly use API response or being more complicated like auth.token.
  • type Authorization header type to be used in $fetch requests.
  • name Authorization header name to be used in $fetch requests.

user

  • Default
user: {
  propertyInLogin: 'user',
  propertyInFetch: '',
  propertyRole: 'role',
  propertyPermission: 'permisison',
  autoFetch: true,
}
  • autoFetch: By default, auth will load the user's info using a second HTTP request after a successful login.
  • propertyInLogin can be used to specify which field of the response JSON to be used for value in login api.
  • propertyRole get role in user data and to use functions getRole, isRole in useAuth composable.
  • propertyPermission get permisison in user data and to use functions getPermissions, hasPermission in useAuth composable.
  • propertyInFetch can be used to specify which field of the response JSON to be used for value in fetch user api.

useAuth

<script lang="ts" setup>
import { useAuth } from 'vue3-auth'

const {
  login,
  logout,
  setToken,
  getToken,
  setUser,
  getRole,
  isRole,
  getPermissions,
  hasPermission,
  resetState,
  fetchUser,
  user,
  loggedIn
} = useAuth()
</script>

login

<script lang="ts" setup>
import { reactive } from "vue";
import { useAuth } from 'vue3-auth'

const { login } = useAuth()

const state = reactive({
  username: '',
  password: ''
})

const onLogin = async () => {
  try {
    const data = await login(state)
    
    console.log('login success >>> ', data)
  } catch (e) {
    console.log('login error >>> ', e)
  }
}
</script>

logout

<template>
  <div>
    <button @click="logout">logout</button>
  </div>
</template>

<script lang="ts" setup>
import { useAuth } from 'vue3-auth'

const { logout } = useAuth()
</script>

isRole and hasPermission

By default local.user.propertyRole = role and local.user.propertyPermission = permissions.

local: {
  user: {
    propertyRole: 'role',
    propertyPermission: 'permissions',
  },
}

API fetchUser has user data:

user: {
  username: 'MR. Seven',
  age: 29,
  email: 'vuthanhbayit@gmail.com',
  role: 'manager',
  permissions: ['view.blog', 'create.blog']
}
<script lang="ts" setup>
import { useAuth } from 'vue3-auth'

const { isRole, hasPermission } = useAuth()

isRole('manager') // true
isRole('admin') // false
hasPermission('view.blog') // true
hasPermission('edit.role') // false
</script>

Meta data auth

<!-- required page-->
<template>
  <div>
    This is required page
  </div>
</template>


<route>
{
  meta: {
    auth: true
  }
}
</route>
<!-- admin page-->
<template>
  <div>
    This is Admin page
  </div>
</template>


<route>
{
  meta: {
    auth: {
      role: "admin"
    }
  }
}
</route>
<!-- create blog -->
<template>
  <div>
    This is Create blog page
  </div>
</template>


<route>
{
  meta: {
    auth: {
      permission: "create.blog"
    }
  }
}
</route>