vuestrap-client-auth-support
v0.0.12
Published
User authentication and authorization for Vuestack client apps
Downloads
26
Readme
Vuestrap | Client Auth Support
Instant implementation of user authentication and authorization for Vuestack client apps (Vue + Vue-Router + Vuex).
WIP
Not ready for public use until version 0.1.0 - Syntax and logic are in frequent flux.
Table of Contents
- Introduction
- Prerequisites
- How to Use
- Namespace
- Options
- Models
- Store
- Router
- Components
- Authenticators
- For Developers
- License
Introduction
What is a Vuestrap?
A Vuestrap is a Vue plugin designed to bootstrap Vue apps with robust, fully-operational application layers.
The plugins strap themselves across the full horizontal stack of the Vue anatomy: adding router logic, state management handling, application logic, data models, and components, allowing you to rapidly compose powerful Vue application boilerplates.
Client Auth Support
The Client Auth Support Vuestrap provides persisent user authentication and authorization sessions within a Vue client application.
If you want to support user auth for your isomorphic (server-side & client-side) application, use
vuestrap-iso-auth-support
instead.
[TBC - More Details]
Prerequisites
The Client Auth Support plugin requires:
- Vue2 (github.com/vuejs/vue)
- Vuex (github.com/vuejs/vuex)
- A compatible Authenticator (see Authenticators)
To harness the instant implementation of auth support, vue-router is needed:
- Vue-Router (github.com/vuejs/vue-router)
If a vue-router instance is not provided when bootstrapping, or vue-router is not being utilized in your application stack, you can leverage the store API and data models to programmatically implement auth support.
How to Use
Install
$ npm install vuestrap-client-auth-support --save
Bootstrap Your Vue App
import Vue from 'vue';
import store from './store'; // your vuex store instance
import router from './router'; // your vue-router instance
import ClientAuthSupport from 'vuestrap-client-auth-support';
Vue.use(ClientAuthSupport, {
store,
router,
authenticator: <my_authenticator>,
persistType: 'local',
tokenName: 'user-auth-token',
});
Namespace
The default namespace for the Client Auth Support store API is: auth
.
However, you can set your preferred namespace when bootstrapping, using the namespace
option.
Options
The following options are available when bootstrapping the app.
| Name | Required? | Description |
| ---------------- | --------- | ----------- |
| store | Yes | The Vuex instance. |
| router | No | The Vue-Router instance. If provided, full auth support logic will be automatically configured. If a router instance is not provided, the store actions must be leveraged to implement auth support in your app. |
| authenticator | Yes | Compatible authentication logic (see Authentictors). |
| persistType | No | A string identifier, specifying the method of persistence to use for the token. Available values: 'local'
(default), 'session'
, 'cookie'
. |
| tokenName | No | The name to use for the persisted auth token. If not specified, the default token name used is user-auth-token
. |
| directUnAuthedTo | No | The route name to direct un-authenticated traffic, when a route is guarded using the requiresAuth
meta property. Default value: 'login'
. |
| namespace | No | The namespace to use with the store API. By default, the namespace is auth
. |
| logInit | No | Set to true
to log messages on bootstrapping. Defaults to false
. |
| debug | No | Set to true
to log debug messages during utilization. Defaults to false
. |
Models
| Model | Description | | -------- | ----------- | | User | Represents the active user and auth status of the active web session. |
User
The User
data model encapsulates the state and values of the user that is
actively using the app. The Vuestrap creates and manages this model internally,
whenever authentication and authorization occurs.
Properties
| Name | Type | Description |
| ---------------- | ------- | ----------- |
| model | String | The name of the model type (i.e. User
). |
| is_anon | Boolean | Whether or not the user is acting as anonymous. |
| is_logged_in | Boolean | Whether or not the user is logged-in. |
| id | Number or String | The ID of the user. |
| external_id | Number or String | An external (third-party) associated ID of the user. |
| username | String | The username of the user. |
| email | String | The email of the user. |
| first_name | String | The first name of the user. |
| last_name | String | The last name of the user. |
| display_name | String | The display name of the user. |
| preferred_locale | String | The preferred locale of the user. |
| avatar_url | String | The avatar URL for the user. |
| avatar_thumb_url | String | A thumbnail version of the avatar URL for the user. |
| roles | Array | An array of role names granted to the user. |
Functions
| Name | Parameters | Returns | Description | | ------------ | ---------- | ------- | ----------- | | login | (none) | (void) | A convenience method for setting the model to a logged-in state. | | logout | (none) | (void) | A convenience method for setting the model to a logged-out state. | | hasRole | roleName | Boolean | A convenience method for checking if the user has a specified role. | | getInfo | (none) | Object | Generates a light-weight info object describing the user. | | toSession | (none) | String | Generates a stringified version of the info object describing the user. | | serialize | (none) | String | Serializes the full set of user properties into a String, that is safe for HTTP transport. |
User as Anonymous
The activeUser
always returns a User
model. When un-authenticated, the anonymized shape and state of the model instance will hold:
| Name | Type | Value |
| ---------------- | ------- | ----- |
| model | String | User
|
| is_anon | Boolean | true
|
| is_logged_in | Boolean | false
|
| id | Number | -1
|
| external_id | null | null
|
| username | String | null
|
| display_name | String | 'Anonymous'
|
| avatar_url | String | [TBD] |
| avatar_thumb_url | String | [TBD] |
Store
Getters
| Getter | Returns | Description | Example |
| ------ | --------| ----------- | ------- |
| pluginName | String | The plugin name/identifier. This value cannot be changed. | this.$store.getters['auth/pluginName']
|
| activeUser | User
| The active user that is using the app. The user returned is never null
. | this.$store.getters['auth/activeUser']
|
| activeUserToken | String | The active user auth token, obtained when a user has successfully authenticated. Returns null
if an auth session has not been successfully established (or the active user is not logged-in). | this.$store.getters['auth/activeUserToken']
|
| isAuthenticating | Boolean | Returns true
when the app is performing authentication. | this.$store.getters['auth/isAuthenticating']
|
| isAuthorizing | Boolean | Returns true
when the app is performing authorization. | this.$store.getters['auth/isAuthorizing']
|
| isFetchingUserInfo | Boolean | Returns true
when the app is fetching user information via the authenticator hook. | this.$store.getters['auth/isFetchingUserInfo']
|
Actions
All actions are Promises, but not all actions are asynchronous.
| Name | Parameters | Returns | Description | Example |
| ------------------ | ---------- | --------- | ----------- | ------- |
| authorize | (none) | { user: <the_user_model>, token: <the_auth_token> }
| TBC | this.$store.dispatch('auth/authorize')
|
| loginUser | creds = { username: <username>, password: <password> }
| { user: <the_user_model>, token: <the_auth_token> }
| TBC | this.$store.dispatch('auth/loginUser', creds)
|
| logoutUser | (none) | { user: <the_user_model>, token: null }
| TBC | this.$store.dispatch('auth/logoutUser')
|
Internal Actions
The following actions are available in the store, but are primarily utilized internally by the Vuestrap logic. Unless you are performing customized logic with the Client Auth Support store, you will not likely use these actions.
| Name | Parameters | Returns | Description | Example |
| ------------------ | ---------- | --------- | ----------- | ------- |
| setActiveUser | User
| (void) | TBC | this.$store.dispatch('auth/setActiveUser', user)
|
| clearActiveUser | (none) | (void) | TBC | this.$store.dispatch('auth/clearActiveUser')
|
| fetchUserInfo | (none) | { <the_user_info> }
| TBC | this.$store.dispatch('auth/fetchUserInfo')
|
Router
If a Vue router instance is provided to the Vuestrap when bootstrapping
(i.e. with Vue.use
), a beforeEach
hook is registered that calls the authorize
store action
on every route transition. This enables the app to maintain its active auth session, so a refresh of the app
will keep the active user logged-in and authorized.
If you want to enforce that a user must be authenticated (logged-in) in order to enter/view a particular route, you can use the requiresAuth
meta property to enforce this policy.
For any routes with the requiresAuth
guard attached, the authorize
hook will check if the active user is logged-in before entering the route. If not, the router will forward the un-authenticated user to the route specified with the directUnAuthedTo
option (by default the route is 'login'
).
Example
new Router({
routes: [
{
path: '/',
name: 'home',
component: HomePage,
},
{
path: '/',
name: 'login',
component: LoginPage,
},
{
path: '/account',
name: 'account',
component: MyAccountPage,
meta: { requiresAuth: true }, // the user must be logged-in to view
},
],
});
Components
[TBC]
| Name | Props | Description | Example |
| ------------------- | ----- | ----------- | ------- |
| local-account-login | [TBC] | Provides a simple username/password login box. | <local-account-login />
|
Events
| Name | Returns | Description | Example |
| ------------------- | ------- | ----------- | ------- |
| login | creds = { ...}
| Emitted when login submit is clicked. | <local-account-login v-on:login="doLogin" />
|
Authenticators
[TBC]
For Developers
Dev Run
To provide a fully working Vue app environment to test and develop the plugin, a simple Vue application will build (the plugin & the app bundle) and serve when running:
$ npm run dev
By default, the development app environment will hot-reload changes and will run on localhost:3301
.
You can change the configuration for the development environment via
test/simulator/config.js
.
Dev Lint
The plugin uses ESLint for source code linting. The linting will run automatically on git commit
.
$ npm run lint
Dev Test
The plugin uses Mocha for the testing framework, and Chai and Chai-HTTP for its assertions.
$ npm run test
Dev Build
The plugin is automatically built on npm publish
. But, you can manually build the plugin using:
$ npm run build-plugin
License
|M| manicprone