@rtidatascience/harness-authentication v0.1.4
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 endpointcookiePath: 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 usersignoreIfAuthenticated: boolean (default=false)
Whether the route is available to authenticated userslogout: 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 toisGuest: 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.