harness-authentication

harness-authentication is a module for the Harness Vue library for handling user authentication.

Setup

Module Configuration

harness-authentication is a Vue module that uses Vuex and Vue Router. To add the module to your Vue app, add the following to your main.js

// main.js (or equivalent)

import Authentication from `harness-authentication`

const loginApiUrl = '/api/login'
const accessTokenCookiePath = '/app/path'
Vue.use(Authentication, { store, router, url: loginApiUrl, cookiePath: accessTokenCookiePath })

• url: string is the url to your authentication endpoint
• cookiePath: string is the path that the access token cookie is saved under, to restrict browser access

The module will initialize its state in Vuex automatically.

Router Configuration

You must configure your router to utilize the authentication functionality. A very simple setup might look something like this:

// router.js (or equivalent)

const router = new VueRouter({
  routes: [
    { 
      path: '/'.
      meta: {
        allowGuest: true,
        ignoreIfAuthenticated: false,
        logout: false
      }
    }
  ]
})

router.beforeEach(async (to, from, next) => {
  const { allow, isGuest } = await verifyRouterAuthentication(store, to)

  if (allow) {
    next()
  } else {
    next('/')
  }
})

First, each route has a set of variables within meta that describes to the module the access parameters for each route:

• allowGuest: boolean (default=false) Whether the route is available to unauthenticated users
• ignoreIfAuthenticated: boolean (default=false) Whether the route is available to authenticated users
• logout: boolean (default=false) Whether to automatically log the user out on navigating to this route

Next, you need to intercept each nagivation event to determine whether the requested navigation is allowed for the current user.

const { allow, isGuest } = await verifyRouterAuthentication(store, to)

verifyRouterAuthentication returns two pieces of information about the user:

• allow: boolean Whether the user is allowed to access the route they are navigating to
• isGuest: boolean Whether the user is and authenticated user (false), or is an unauthenticated guest (true)

You must handle the navigation yourself by calling the next function provided by the router.

Authenticating

The module injects into your components the authenticateUser({ username: string, password: string}) action that you can use to send the authentication request.

async onSubmit () {
  try {
    await this.authenticateUser(this.form)
    this.$router.push('/')
  } catch (e) {
    this.formError = e.message
  }
}

By calling authenticateUser, the module will make an authentication request, and if successful, will store the credentials in Vuex. On failure, it will throw an Error.

API

The module exports a number of methods to help you access its functionality

getIsAuthenticatedFromStore(store): boolean

Given the Vuex store, will return whether the user has been authenticated.

getAuthHeaderFromStore(store): { Authorization: string }

Returns the Authorization header for the current authorized user, to be added to any requests requiring the authorization credentials.

Throws an error if the user is not authenticated.

isResponseAuthorized(response): boolean

Given a request response, returns whether the response was authorized.

verifyLogin(store)

Used to retrieve a saved authorization from the user's cookies. If there is a saved authentication, it will be saved to the store.

dispatchLogoutUser(store)

Clears the local user authentication. A logoutUser event will be dispatched to the root store that you can listen for and respond to.

expireUserAuthentication(store)

Clears the local user authentication. A `loginExpired' event will be dispatched to the root store that you can listen for and respond to. Useful for distinguishing between a willful logout of the user, versus removing authorization because the token has expired.