Authentication is going be to be one of the first things an application requires.
The vue-auth plugin attempts to simplify the front end application part of the puzzle. However, it's important to understand that the plugin doesn't simply work on it's own. It is only one of the pieces in the puzzle and some prior knowledge and api setup will be required.
If you are new to single page app development it's a good idea to take a look at the Primer Guide first.
Install the package via npm.
> npm install @websanova/vue-auth
The vue-auth plugin has some dependencies that must be set before the plugin is installed or it may lead to some errors.
The Vue.router must be set which then corresponds to the router driver installed with the plugin.
The most commonly used router plugin is vue-router.
An http plugin must be set which then corresponds to the http driver installed with the plugin.
The most common http plugins are vue-resource and axios.
The default install is for the Vue 3 version with ES6 module syntax.
Check the Vue 3 demo for a fully working example.
import {createApp} from 'vue';
import {createRouter} from 'vue-router';
import axios from 'axios';
import App from 'App.vue';
import {createAuth} from '@websanova/vue-auth';
import driverAuthBearer from '@websanova/vue-auth/dist/drivers/auth/bearer.esm.js';
import driverHttpAxios from '@websanova/vue-auth/dist/drivers/http/axios.1.x.esm.js';
import driverRouterVueRouter from '@websanova/vue-auth/dist/drivers/router/vue-router.2.x.esm.js';
import driverOAuth2Google from '@websanova/vue-auth/dist/drivers/oauth2/google.esm.js';
import driverOAuth2Facebook from '@websanova/vue-auth/dist/drivers/oauth2/facebook.esm.js';
var router = createRouter({
...
})
var auth = createAuth({
plugins: {
http: axios,
router: router
},
drivers: {
http: driverHttpAxios,
auth: driverAuthBearer,
router: driverRouterVueRouter,
oauth2: {
google: driverOAuth2Google,
facebook: driverOAuth2Facebook,
}
},
options: {
rolesKey: 'type',
notFoundRedirect: {name: 'user-account'},
}
});
createApp(App)
.use(router)
.use(auth)
.mount('#app');
By default importing @websanova/vue-auth will use the Vue 3 version.
To use the Vue 2 version the path must be set. Check the Vue 2 demo for a fully working example.
import Vue from 'vue'
import auth from '@websanova/vue-auth/dist/v2/vue-auth.esm.js';
import driverAuthBearer from '@websanova/vue-auth/dist/drivers/auth/bearer.esm.js';
import driverHttpAxios from '@websanova/vue-auth/dist/drivers/http/axios.1.x.esm.js';
import driverRouterVueRouter from '@websanova/vue-auth/dist/drivers/router/vue-router.2.x.esm.js';
import driverOAuth2Google from '@websanova/vue-auth/dist/drivers/oauth2/google.esm.js';
import driverOAuth2Facebook from '@websanova/vue-auth/dist/drivers/oauth2/facebook.esm.js';
driverOAuth2Google.params.client_id = '547886745924-4vrbhl09fr3t771drtupacct6f788566.apps.googleusercontent.com';
driverOAuth2Facebook.params.client_id = '196729390739201';
Vue.use(auth, {
plugins: {
http: Vue.axios, // Axios
// http: Vue.http, // Vue Resource
router: Vue.router,
},
drivers: {
auth: driverAuthBearer,
http: driverHttpAxios,
router: driverRouterVueRouter,
oauth2: {
google: driverOAuth2Google,
facebook: driverOAuth2Facebook,
}
},
options: {
rolesKey: 'type',
notFoundRedirect: {name: 'user-account'},
}
});
Also supports ES5 require syntax.
var Vue = require('vue');
var auth = require('@websanova/vue-auth/dist/v2/vue-auth.common.js');
var authBasic = require('@websanova/vue-auth/dist/drivers/auth/basic.common.js');
var httpVueResource = require('@websanova/vue-auth/dist/drivers/http/vue-resource.1.x.common.js');
var routerVueRouter = require('@websanova/vue-auth/dist/drivers/router/vue-router.2.x.common.js');
var oauth2Google = require('@websanova/vue-auth/dist/drivers/oauth2/google.common.js');
var oauth2Facebook = require('@websanova/vue-auth/dist/drivers/oauth2/facebook.common.js');
Vue.use(auth, {
auth: authBasic,
http: httpVueResource,
router: routerVueRouter,
...
});
The drivers for the most part should work out of the box. Typically it's the "auth" driver that will require customization since each app sends it's token in a slightly different way.
It's best to check the Drivers Guide for more details on usage and customization.
The next step will be to start defining access on the router's routes. This is done using special meta.auth data in the route.
This also has it's own Meta Auth Guide which contains details and examples for usage.
With some basic understanding of drivers and auth meta out of the way we can now fire off a request.
For example, a basic login call below.
$auth.login({
body: this.form.body
});
From here it's best to refer to the reference guides for Methods and Options.
When a user is authenticated the app will likely need to do some initial preload and checks.
For instance if we refresh the app in authenticated mode, we'll need to first check tokens and fetch some data.
A special $auth.ready() Method has been created for this specific case.
<div
v-if="!$auth.ready()"
>
Loading...
</div>
<div
v-if="$auth.ready()"
>
<router-view />
</div>
That's pretty much it in a nutshell.
It may be a bit of a struggle to initially get setup but it requires very little maintenance. Each app will of course be different, but the vue-auth plugin aims to be simple and flexible enough to handle most situations.