npm package: @rtidatascience/harness-authentication
Description: Vue plugin for authentication in the Harness framework.
Author: RTI CDS
Latest version: 0.1.4

# harness-authentication

<div align="center">
    <img src="https://github.com/RTIInternational/harness/raw/main/logos/rti.png" alt="RTI Logo"/>
    <img src="https://github.com/RTIInternational/harness/raw/main/logos/cds.png" alt="CDS Logo"/>
</div>

### harness-authentication is a module for the [Harness](https://github.com/RTIInternational/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.