vuestrap-client-auth-support v0.0.12

Vuestrap | Client Auth Support

Instant implementation of user authentication and authorization for Vuestack client apps (Vue + Vue-Router + Vuex).

WIP

Not ready for public use until version 0.1.0 - Syntax and logic are in frequent flux.

Table of Contents

• Introduction
• Prerequisites
• How to Use
• Namespace
• Options
• Models
• Store
• Router
• Components
• Authenticators
• For Developers
• License

Introduction

What is a Vuestrap?

A Vuestrap is a Vue plugin designed to bootstrap Vue apps with robust, fully-operational application layers.

The plugins strap themselves across the full horizontal stack of the Vue anatomy: adding router logic, state management handling, application logic, data models, and components, allowing you to rapidly compose powerful Vue application boilerplates.

Client Auth Support

The Client Auth Support Vuestrap provides persisent user authentication and authorization sessions within a Vue client application.

If you want to support user auth for your isomorphic (server-side & client-side) application, use vuestrap-iso-auth-support instead.

TBC - More Details

Prerequisites

The Client Auth Support plugin requires:

• Vue2 (github.com/vuejs/vue)
• Vuex (github.com/vuejs/vuex)
• A compatible Authenticator (see Authenticators)

To harness the instant implementation of auth support, vue-router is needed:

• Vue-Router (github.com/vuejs/vue-router)

If a vue-router instance is not provided when bootstrapping, or vue-router is not being utilized in your application stack, you can leverage the store API and data models to programmatically implement auth support.

How to Use

Install

$ npm install vuestrap-client-auth-support --save

Bootstrap Your Vue App

import Vue from 'vue';
import store from './store'; // your vuex store instance
import router from './router'; // your vue-router instance
import ClientAuthSupport from 'vuestrap-client-auth-support';

Vue.use(ClientAuthSupport, {
  store,
  router,
  authenticator: <my_authenticator>,
  persistType: 'local',
  tokenName: 'user-auth-token',
});

Namespace

The default namespace for the Client Auth Support store API is: auth.

However, you can set your preferred namespace when bootstrapping, using the namespace option.

Options

The following options are available when bootstrapping the app.

Models

User

The User data model encapsulates the state and values of the user that is actively using the app. The Vuestrap creates and manages this model internally, whenever authentication and authorization occurs.

Properties

Functions

User as Anonymous

The activeUser always returns a User model. When un-authenticated, the anonymized shape and state of the model instance will hold:

Store

Getters

Actions

All actions are Promises, but not all actions are asynchronous.

Internal Actions

The following actions are available in the store, but are primarily utilized internally by the Vuestrap logic. Unless you are performing customized logic with the Client Auth Support store, you will not likely use these actions.

Router

If a Vue router instance is provided to the Vuestrap when bootstrapping (i.e. with Vue.use), a beforeEach hook is registered that calls the authorize store action on every route transition. This enables the app to maintain its active auth session, so a refresh of the app will keep the active user logged-in and authorized.

If you want to enforce that a user must be authenticated (logged-in) in order to enter/view a particular route, you can use the requiresAuth meta property to enforce this policy.

For any routes with the requiresAuth guard attached, the authorize hook will check if the active user is logged-in before entering the route. If not, the router will forward the un-authenticated user to the route specified with the directUnAuthedTo option (by default the route is 'login').

Example

new Router({
  routes: [
    {
      path: '/',
      name: 'home',
      component: HomePage,
    },
    {
      path: '/',
      name: 'login',
      component: LoginPage,
    },
    {
      path: '/account',
      name: 'account',
      component: MyAccountPage,
      meta: { requiresAuth: true }, // the user must be logged-in to view
    },
  ],
});

Components

TBC

Events

Authenticators

TBC

For Developers

Dev Run

To provide a fully working Vue app environment to test and develop the plugin, a simple Vue application will build (the plugin & the app bundle) and serve when running:

$ npm run dev

By default, the development app environment will hot-reload changes and will run on localhost:3301.

You can change the configuration for the development environment via test/simulator/config.js.

Dev Lint

The plugin uses ESLint for source code linting. The linting will run automatically on git commit.

$ npm run lint

Dev Test

The plugin uses Mocha for the testing framework, and Chai and Chai-HTTP for its assertions.

$ npm run test

Dev Build

The plugin is automatically built on npm publish. But, you can manually build the plugin using:

$ npm run build-plugin

License

MIT

|M| manicprone