npm package: @oniti/quasar-app-extension-vlank-auth
Description: Authentification
Author: François BOUYER
Latest version: 3.2.26

Vlank Auth
===

> Manage authentication

Provides :
- login page
- helpers (get user, rights, disconnect, …)


### Install
```bash
quasar ext add @oniti/vlank-auth
```

### Uninstall
```bash
quasar ext remove @oniti/vlank-auth
```

### Update
```bash
yarn upgrade @oniti/vlank-auth
```

### Live extension development
```bash
# in this extension root directory (once for all):
yarn link

# in host project (laravel-vlank, probably) frontend directory:
# (delete node_modules + yarn install to get to the original state)
yarn link "@oniti/quasar-app-extension-vlank-auth"
```
In quasar.conf.js of host project:
```javascript
devServer: {
  …
  watchFiles: [
    '/node_modules/@oniti/quasar-app-extension-vlank-auth/src/**/*',
  ],
}
```

### Live extension development (alternative)
I (Julien) was unable to make the above work ("missing index script") so I use this instead:
```bash
# delete the src subdirectory of the extension in the host project (in front-end directory):
rm -rf node_modules/@oniti/quasar-app-extension-vlank-auth/src
# link directly the src directory of the extension:
ln -s /home/xfennec/git/vlank-auth/src/ node_modules/@oniti/quasar-app-extension-vlank-auth/src
```

That's it. The extension is already in devServer's watchFiles of laravel-vlank,
so it will be reloaded automatically when you change something in the extension.

edit: I was also able to make it work by modifying files in node_modules and
running `quasar clean` in the host project + restarting `./serve.sh` for quick tests.

### Publish
```bash
# only necessary step (asks for new version):
yarn publish
```

### Settings
See also settings in `quasar.extensions.json` (created on install).

**You can override default login page** by creating your own `/auth/login` / loginRoute / defaultAuthRoute route.
You can copy Login.vue as a template for your page.

The default page use `email` and `password` as credentials.

### Configuration

```
chainWebpack(chain) {
    chain.resolve.alias.merge({
         "vlank-auth-logo": path.resolve(
            __dirname,
            "src/assets/logo-app.png"
          ),
          "vlank-auth-logo-text": path.resolve(
            __dirname,
            "src/assets/logo-app-text.png"
          ),
          "vlank-auth-layout": path.resolve(
            __dirname,
            "src/layouts/EmptyLayout.vue"
          )
    });
}
```
### Custom route validation
You can define a custom function to check route access.

in `quasar.conf.js`
```javascript
boot: [...,'override-check-route-access'],
...,
framework:{
  ...,
  config:{
    onitiVlankAuth: {
      check_route_access_overide_name: "$vlankAuthCheckAccessRoute"
    },
    ...
  }
}
```
`override-check-route-access.js`
```javascript
import { boot } from 'quasar/wrappers'


export default boot(({ app }) => {
  app.config.globalProperties.$vlankAuthCheckAccessRoute = (user, to) => {
    return true
  }
})
```

### Usage
Just add requieresAuth as meta on route to require an auth.

Route example:
```javascript
{
    path: '/',
    meta: {
      requiresAuth: true,
      // loginRoute: '/auth/login', // optional, defaultAuthRoute otherwise
      // redirectRoute : '/', // optional, defaultRedirectRoute otherwise
      // passwordLostRoute : '/', // optional, defaultPasswordLostRoute otherwise
      // passwordCreateRoute : '/', // optional, defaultpasswordCreateRoute otherwise
      rights : ['admin-panel'] // optional
      logoutOnUnsufisantRights: true, // optional
      // ignoreAuthRedirect: true // optional
    },
    component: () => import('layouts/MainLayout.vue'),
    children: [
      { path: '', component: () => import('pages/Index.vue') }
    ]
}
```

## Meta settings

| Name | Purpose |
| ---- | ------- |
| requiresAuth | Auth is required for this route **and its children** |
| loginRoute | Override default login route |
| redirectRoute | Override default "home" route |
| passwordLostRoute | Override default "passwordLostRoute" route |
| passwordCreateRoute | Override default "passwordCreateRoute" route |
| rights | array of required rights, a message will pop if **any** right is missing! |
| typeRightCheck | string, "any" or "all" define if all rights are requiered or only one |
| logoutOnUnsufisantRights | self explaining :) |
| ignoreAuthRedirect | if true, no redirection will be done on this **public** route (useful for pages where you want to preserve query params) |

## Helpers

The authentication logic is performed inside a Vuex store. you can provide an helper to access the functionality in the store.
Les helpers sont accessibles depuis le composant après avoir fait un inject :
```javascript
    import { inject } from 'vue'

    const $auth = inject('vlank-auth')
```

| Function               | General purpose |
| ---------              | ------------- |
| $auth.logout()         | Logs out the current user |
| $auth.check(right)     | Checks if the user belongs to `right` (string) |
| $auth.checkAll(rights) | Checks if the user belongs to every `rights` (array of string) |
| $auth.checkAny(rights) | Checks if the user belongs to any `rights` (array of string) |
| $auth.user()           | Returns the current user (no request is sent to the back) |

| Function                   | Specific purpose |
| ---------                  | ------- |
| $auth.login(data)          | POST `data` (ex: login+password) to the login route, saves the returned `token` in a cookie |
| $auth.fetch()              | Request the backend to check if we're still authentified |
| $auth.updatePassword(data) | Update current User password |
| $auth.resetPassword(data)  | Reset User password |
| $auth.passwordLost(data)   | Send mail to current User to reset his password |
| $auth.updateUser(data)     | Update current User informations |
| $auth.getRedirectRoute()   | Return last visited route (or redirectRoute if none) |
| $auth.getLoginRoute()      | return current Login Route (loginRoute / defaultAuthRoute) |
| $auth.getWantedRoute()     | return previously "forbidden" route |
| $auth.isFunctionalRoute(routePath)  | Check the route is a functionnal route (Login Route, PasswordCreate Route or PasswordLost Route) |

## Optionnal extension configuration

The following keys are not prompted during the installation process, but can be added to `quasar.extensions.json` :

| Key | Purpose |
| --- | ------- |
| `disableLostPassword` | Disable the "lost password" button |
| `hideBottomTextLogo` | Hide the "text logo" at the bottom of pages |

### TODO
- add "rightOperator" (AND/OR)?
- messages customisation
- allow to configure backend routes
- component : logout button
- component : my account