Vue Auth / Guides / Startup

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.

Resources

If you are new to single page app development it's a good idea to take a look at the Primer Guide first.

Install

Install the package via npm.

> npm install @websanova/vue-auth

Dependencies

The vue-auth plugin has some dependencies that must be set before the plugin is installed or it may lead to some errors.

Router

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.

HTTP

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.

Setup

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');

Vue 2

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,
    ...
});

Drivers

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.

Auth Meta

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.

Requests

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.

Ready / Loaded

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>

Conclusion

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.