Vlank Auth

Manage authentication

Provides :

• login page
• helpers (get user, rights, disconnect, …)

Prérequis

• Node.js >= 18.0.0
• Quasar 2 avec @quasar/app-vite ^2.0.0
• Pinia installé et enregistré dans l'app consommatrice (via un boot file chargé avant celui de vlank-auth)
• L'extension @oniti/vlank-starter installée au préalable

Install

quasar ext add @oniti/vlank-auth

Uninstall

quasar ext remove @oniti/vlank-auth

Update

yarn upgrade @oniti/vlank-auth

Migration v3 → v4

Breaking changes :

• Pinia obligatoire : le composant utilise Pinia au lieu de Vuex. Votre application doit avoir Pinia installé et enregistré via un boot file précédant celui de vlank-auth dans quasar.config.js > boot.
• @quasar/app-vite ^2.0.0 requis : les projets encore sur @quasar/app-webpack doivent rester sur vlank-auth 3.2.x.
• Alias webpack → alias Vite : remplacer chainWebpack par build.extendViteConf (voir Configuration ci-dessous).
• Node 18+ requis.
• État accédé via Pinia : si votre app accédait directement à l'état (déconseillé), utiliser useAuthStore à la place de store.state.auth. Le champ has_check est renommé hasCheck.

Live extension development

# 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"

Pendant la phase de migration v4, il faut également linker @oniti/quasar-app-extension-vlank-input en v4 en local dans le projet consommateur.

In quasar.config.js of host project:

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:

# 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.

Publish

# only necessary step (asks for new version):
yarn publish
# … ou si vous avez un yarn trop vieux (vu les changements récents chez npm):
npm 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

Les alias (logos, layout de login) sont définis côté consommateur dans quasar.config.js :

import { fileURLToPath } from 'node:url'

build: {
  extendViteConf (viteConf) {
    viteConf.resolve ??= {}
    viteConf.resolve.alias ??= {}
    Object.assign(viteConf.resolve.alias, {
      'vlank-auth-logo': fileURLToPath(new URL('./src/assets/logo-app.png', import.meta.url)),
      'vlank-auth-logo-text': fileURLToPath(new URL('./src/assets/logo-app-text.png', import.meta.url)),
      'vlank-auth-layout': fileURLToPath(new URL('./src/layouts/EmptyLayout.vue', import.meta.url)),
    })
  }
}

Custom route validation

You can define a custom function to check route access.

in quasar.config.js

boot: [...,'override-check-route-access'],
...,
framework:{
  ...,
  config:{
    onitiVlankAuth: {
      check_route_access_overide_name: "$vlankAuthCheckAccessRoute"
    },
    ...
  }
}

override-check-route-access.js

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:

{
    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 Pinia store (useAuthStore, exporté depuis @oniti/quasar-app-extension-vlank-auth/src/stores/auth). Les helpers sont accessibles depuis le composant après avoir fait un inject :

    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