npm package: @ganillagrace/vue-auth
Description: FORKED: @websanova/vue-auth Vue.js token based authentication plugin. Supports simple token based and Json Web Tokens (JWT) authentication.
Author: Websanova
Latest version: 2.2.3

# Vue Auth

Vue.js token based authentication plugin. Supports simple token based and JSON Web Tokens (JWT) authentication.

Note this is the new name for the formerly named `vue-jwt-auth`. Since it's likely this package will expand with potentially more authentication options.

* [Install](https://github.com/websanova/vue-auth#install)
* [Demo](https://github.com/websanova/vue-auth#demo)
* [Auth Flow](https://github.com/websanova/vue-auth#auth-flow)
* [User Data](https://github.com/websanova/vue-auth#user-data)
* [Authentication](https://github.com/websanova/vue-auth#authentication)
* [Privileges](https://github.com/websanova/vue-auth#privileges)
* [Routes](https://github.com/websanova/vue-auth#routes)
* [Methods](https://github.com/websanova/vue-auth#methods)
* [Options](https://github.com/websanova/vue-auth#options)
* [Driver Options](https://github.com/websanova/vue-auth#driver-options)
* [Change Log](https://github.com/websanova/vue-auth#change-log)



### Tested with

* vue 1.0.26, vue-resource 1.0.2, vue-router 0.7.13
* vue 2.0.1, vue-resource 1.0.2, vue-router 2.0.0

Early support for Vue 2.0 is now available also but may still be a bit unstable due to many changes in the api. Please let me know of any issues you may find.



## Notes

* The new 2.x branch features a driver centric model. This means the `router` and `http` options must **ALWAYS** set the driver to use. Please read the [Change Log](https://github.com/websanova/vue-auth#change-log) for more info.



## Install 2.x

~~~
> sudo npm install @ganillagrace/vue-auth
~~~    

The `router` and `http` drivers MUST be set. The drivers are quite small so can be replaced or overridden as necessary.

**Note that the version in the driver file should denote the version it is compatible with. So `router.2x.` means it's for router 2.x.**

~~~
Vue.http.options.root = 'https://api-demo.websanova.com/api/v1';

Vue.router = new VueRouter({
    ...
});

Vue.use(require('@ganillagrace/vue-auth'), {
    auth: require('@ganillagrace/vue-auth/drivers/auth/bearer.js'),
    http: require('@ganillagrace/vue-auth/drivers/http/vue-resource.1.x.js'),
    router: require('@ganillagrace/vue-auth/drivers/router/vue-router.2.x.js'),
    ...
    rolesVar: 'type'
    ...
});
~~~



## Install 1.x

~~~
> sudo npm install @ganillagrace/vue-auth
~~~    

~~~
Vue.http.options.root = 'https://api-demo.websanova.com/api/v1';

Vue.router = new VueRouter({
    ...
});

Vue.use(require('@ganillagrace/vue-auth'), {
    rolesVar: 'type'
});
~~~

**NOTE:** If you do not set your router as `Vue.router = new VueRouter()` then you will need to feed the `router` in directly through the options. Also true for `http`.

~~~
var router = new VueRouter();
Vue.use(Auth, {
    router: router,
    http: http
});
~~~



## Demo

To run the front end part of the demo just install and run. The demo runs on a publicly available server so just the front end needs run.

* Demo server available publicly at https://api-demo.websanova.com
* Demo server on GitHub https://github.com/websanova/laravel-api-demo
* Change the http options root in the `app.js` demo file to a different server for personal testing.

~~~
> sudo npm install
> sudo npm run 1.x.demo
> sudo npm run 2.x.demo
~~~

Note: For Vue 2 demo there is a separate package.json. Unfortunately there is no really great way to run both at the same time.


If a different path is required it must be set in the `demo/app.js` file.

To run the build:

~~~
> sudo webpack
~~~



## Auth Flow

The best way to see the code in action is to see the code samples in the `1.x.demo` and `2.x.demo` folders. However it still helps to understand what exactly the workflow is.

* The plugin has two sets of interceptors. One for routing and one for http requests.

### Routing

* From the front end we can't really do any "real" authentication. It's simply a check to see it users role and the routes roles match up. From there we can allow the route to process or we can redirect accordingly.
* This is done by intercepting each route and checking if the user is already logged in. This is done by simply checking if a token exists.
* If a token exists a few things can happen. But by default there will be two requests sent. One is to refresh the token (this is based on best practice). Second is to fetch the user.
* Typically a user will be fetched each time to make sure we have the latest user data.
* After the user is fetched the plugin will process into a "loaded" state. This should be checked via the "$auth.ready()" method. At this point we will know if we have a valid token and user.
* From here we can use the `$auth.check()` function to show hide various parts of our interface.

### HTTP

* The http part is much simpler. Essentially the plugin will automatically parse some authentication data (based on driver) into each request the app makes.
* This parsing will be done on each `request` and `response` of your http (ajax) calls.
* For the request it will simply append the auth data in the header or body (depending on your auth driver).
* For the response it will parse the auth data from the header or response data (depending on your auth driver).



## User Data

A common gotcha is getting the `$auth.user()` data properly. The plugin is designed to expect the user object to be in the `data` parameter of the response.

Depending on what version of the `vue-resource` plugin you are using the response data itself will come from either `res.json()` or `res.data`. Note that the data here is not the response data.

Sample response.

~~~
{
    "status": "success",
    "data": {
        "id": 1,
        "name": "Websanova",
        ...
    }    
}
~~~

The plugin has a function for parsing this user data when it receives it called `_parseUserData`. The `data` variable there is the `res.json()` or `res.data` object.

~~~
function _parseUserData(data) {
    return data.data;
}
~~~

If a different format is needed simply override this function in the options.

~~~
Vue.use(require('vue-auth'), {
    _parseUserData: function (data) {
        return data.whatever;
    }
});
~~~



## Authentication

Because there are so many different authentication schemes with tokens Vue Auth uses a simple model so that it can easily be extended for custom scenarios.

Each request and response that is made to the server is intercepted internally by the plugin.

* The internal request method will fetch the current token (internally) and pass it to the auth `request` driver method where it can be processed for delivery to the server.
* The internal response method will behave in a similar fashion however it should deliver a token to the internal response intercept where that token will get stored.

The current `bearer` driver is quite simple and looks like this:

~~~
bearerAuth: {
    request: function (req, token) {
        this.options._setHeaders.call(this, req, {Authorization: 'Bearer ' + token});
    },
    response: function (res) {
        var token = this.options._getHeaders.call(this, res).Authorization;

        if (token) {
            token = token.split('Bearer ');

            return token[token.length > 1 ? 1 : 0];
        }
    }
},
~~~

The driver `request` method receives the `req` and `token` arguments. From there we use an internal `_setHeaders` method. However with the `req` object pretty much anything can be assembled.

The driver `response` method receives the `res` argument and should parse out the token from the response and return a token which will get stored internally by the plugin.

To setup a custom driver we simply need to set the `authType` option and the naming convention will follow.

**Example 1: Token in sub object of body**

Maybe the token is returned in a non standard way such as `{data: {token: 'abcd1234'}}`.

~~~
authType: 'custom1',

custom1Auth: {
    request: function (req, token) {
        req.headers.set('SomeHeader', token);
    },
    response: function (res) {
        return (res.data.data || {}).token;
    }
}
~~~

**Example 2: Token with multiple parts**

Another common scenario may be a token with multiple data points that all need to be returned to the server.

~~~
authType: 'custom2',

custom2Auth: {
    request: function (req, token) {
        token = token.split(';');

        this.options._setHeaders.call(this, req {
            header1: token[0],
            header2: token[1],
            header3: token[2],
            header4: token[3]
        });
    },
    response: function (res) {
        var headers = this.options._getHeaders.call(this, res);

        if (headers.header1 && headers.header2 && headers.header3 && headers.header4) {
            return headers.header1 + ';' + headers.header2 + ';' + headers.header3 + ';' + headers.header4;
        }
    }
}
~~~



## Privileges

The `vue-auth` plugin works with the `vue-router` plugin. Setting an `auth` field in the router mapping section will set access to that route.

**Vue 1.x**

~~~
Vue.router.map({
    '/admin': {
        auth: 'admin',
        component: require('./Admin')
    },
    '/manage': {
        auth: ['admin', 'manager'],
        component: require('./Manage')
    },
    '/account': {
        auth: true,
        component: require('./Account')
    },
    '/private': {
        auth: [{"people": "administrator", "people": "superadmin"}],
        component: require('./Account')
    },
    '/login': {
        auth: false,
        component: require('./Login')
    },
    '/contact': {
        component: require('./Contact')
    }
});
~~~

**Vue 2.x**

~~~
Vue.router = new VueRouter({
    routes: [{
        path: '/admin',
        meta: {auth: 'admin'},
        component: require('./Admin')
    }, {
        path: '/manage',
        meta: {auth: ['admin', 'manager']},
        component: require('./Manage')
    }, {
        path: '/account',
        meta: {auth: true},
        component: require('./Account')
    }, {
        path: '/private',
        meta: {auth: [{"people": "administrator", "people": "superadmin"}]},
        component: require('./Account')
    }, {
        path: '/login',
        meta: {auth: false},
        component: require('./Login')
    }, {
        path: '/contact',
        component: require('./Contact')
    }]
});
~~~


## Routes

### auth: `true`

* User must be authenticated (no roles are checked).

### auth: `false`

* If the user is logged in then this route will be unavailable. Useful for login/register type pages to be unaccessible once the user is logged in.

### auth: `undefined`

* Public, no checks required.

### auth: `Array` `String`

* The user must be logged in. Additionally the string or array will be checked against the users roles.
* Note that the users `roles` variable can be set in the options.

### auth: `Object`

* The user must be logged in and the object will be checked against the users roles.
* Note for this to work both the auth and user roles must both be objects.
* An object must also be used when using `$auth.check({some: 'name'})` where the value can be a `String` or `Array`.




## Methods

These are all methods available in the vue app via `$auth`.

* All `success` and `error` functions will receive proper context from currently called component.

### ready

* Fires once on the initial app load to pre-load users (if set).

~~~
<div v-if="$auth.ready()">
    <vue-router></vue-router>
</div>
<div v-if="!$auth.ready()">
    Site loading...
</div>
~~~

### user

* Returns the currently stored users data.

~~~
<div>
    {{ $auth.user().email }}
</div>
~~~

### check

* Check to see if the user is logged in.
* It also accepts arguments to check for a specific role or set of roles.

~~~
<a v-if="!$auth.check()" v-link="'/login'">login</a>
<a v-if="$auth.check('admin')">admin</a>
<a v-if="$auth.check(['admin', 'manager')]">manage</a>
<a v-if="$auth.check()" v-on:click="$auth.logout()">logout</a>
~~~

### other

* Checks if secondary "other" user is logged in.

~~~
<a v-if="$auth.other()" v-on:click="logoutOther()">logout other</a>
~~~

### disableOther

* Disables other using the default token until it is re-enabled (or logged out).
* This allows you to login is as "another" user but still perform requests as an admin.

~~~
this.$auth.disableOther();

this.$http.get('users'); // Will run as admin.

this.$auth.enableOther();
~~~

### enableOther

* See disableOther.

### token

* Returns the currently activated token if none are specified.
* Can also specify a specific token, but only `other` and `default` will actually return anything.

~~~
var token = this.$auth.token();
var token = this.$auth.token('other');
var token = this.$auth.token('default');
~~~

### fetch

* Fetch the user (again) allowing the users data to be reset (from the api).
* Data object is passed directly to http method.

~~~
this.$auth.fetch({
    params: {},
    success: function () {},
    error: function () {},
    // etc...
});
~~~

### refresh

* Manually refresh the token.
* The refresh will always fire on boot, to disable this override the `expiredToken` option method.
* Can be used in conjunction with `expiredToken` and `token` to write custom refreshes.
* If any custom expiration custom logic needs to be done (for instance decoding and checking expiration date in jwt token) override the `expiredToken` method and return `boolean`.
* Data object is passed directly to http method.

~~~
this.$auth.refresh({
    params: {},
    success: function () {},
    error: function () {},
    // etc...
});
~~~

### register

* Convenience method for registration.
* Data object is passed directly to http method.
* Accepts `autoLogin` parameter to attempt login directly after register.
* Accepts `rememberMe` parameter when used in conjunction with `autoLogin` equal to `true`.
* Accepts `redirect` parameter which is passed directly to router.

~~~
this.$auth.register({
    params: {},
    success: function () {},
    error: function () {},
    autoLogin: true,
    rememberMe: true,
    redirect: {name: 'account'},
    // etc...
});
~~~

### login

* Data object is passed directly to http method.
* Accepts `rememberMe` parameter.
* Accepts `redirect` parameter which is passed directly to router.
* Accepts `fetchUser` param which allows disabling fetching user after login.

~~~
this.$auth.login({
    params: {},
    success: function () {},
    error: function () {},
    rememberMe: true,
    redirect: '/account',
    fetchUser: true
    // etc...
});
~~~

### logout

* Data object is passed directly to http method.
* Accepts `redirect` parameter which is passed directly to router.
* Accepts `makeRequest` parameter which must be set to `true` to send request to api. Otherwise the logout just happens locally by deleting tokens.

~~~
this.$auth.logout({
    makeRequest: true,
    params: {},
    success: function () {},
    error: function () {},
    redirect: '/login',
    // etc...
});
~~~

### loginOther

* Data object is passed directly to http method.
* Accepts `redirect` parameter which is passed directly to router.

~~~
this.$auth.loginOther({
    params: {},
    success: function () {},
    error: function () {},
    redirect: {name: 'account'},
    // etc...
});
~~~

### logoutOther

* Data object is passed directly to http method.
* Accepts `redirect` parameter which is passed directly to router.
* Also accepts `makeRequest` parameter same as `logout` method.

~~~
this.$auth.logoutOther({
    makeRequest: true,
    params: {},
    success: function () {},
    error: function () {},
    redirect: {path: '/admin'},
    // etc...
});
~~~

### oauth2

* Convenience method for OAuth2.
* Initial request is to third party.
* Second call is to api server.
* Accepts `code` parameter which should be set to `true` when the code is set.
* Accepts `provider` parameter which hooks into data for third party.
* Third party data should follow format such as `facebookData`, `facebookOath2Data`. Check options section for more info.
* Accepts `redirect` parameter which is passed directly to router.

~~~
if (this.$route.query.code) {
    this.$auth.oauth2({
        code: true,
        provider: 'facebook',
        params: {
            code: this.code
        },
        success: function(res) {},
        error: function (res) {}
        redirect: {path: '/account'},
        // etc
    });
}
else {
    this.$auth.oauth2({
        provider: 'facebook'
    });
}
~~~



## Options

Pretty much all methods are overrideable now in case there any specific issues with a particular version of Vue.

### token: `[{request: 'Authorization', response: 'Authorization', authType: 'bearer', foundIn: 'header'}, {request: 'token', response: 'token', authType: 'bearer', foundIn: 'response'}]`

* Set of method for fetching the token from the response. It will attempt each until a token is found and stop there.
* For sending requests it will by default use the method in the first position.

### tokenName: `'auth-token'`

* The name of the token stored in local storage.

### rolesVar: `'roles'`

* Name of roles var in user object.

### authRedirect: `{path: '/login'}`

* Redirect to use if authentication is required on a route.

### forbiddenRedirect: `{path: '/403'}`

* Redirect to use if route is forbidden.

### notFoundRedirect: `{path: '/404'}`

* Redirect to use if route is not found (set the `false`).

### registerData: `{url: 'auth/register', method: 'POST', redirect: '/login'}`

* Default register request data and redirect.

### loginData: `{url: 'auth/login', method: 'POST', redirect: '/', fetchUser: true}`

* Default login request data and redirect.
* To disable user fetching on login set the `fetchUser` to `false`.

### logoutData: `{url: 'auth/logout', method: 'POST', redirect: '/', makeRequest: false}`

* Default logout request data and redirect.
* This request is only made if `makeRequest` is set to true.

### oauth1Data: `{url: 'auth/login', method: 'POST'}`

* Default oauth1 request data and redirect.

### fetchData: `{url: 'auth/user', method: 'GET'}`

* Default user fetch request data and redirect.

### refreshData: `{url: 'auth/refresh', method: 'GET', atInit: true}`

* Default refresh request data and redirect.

### loginOtherData: `{url: 'auth/login-other', method: 'POST', redirect: '/'}`

* Default login as "other" request data and redirect.

### logoutOtherData: `{url: 'auth/logout-other', method: 'POST', redirect: '/admin', makeRequest: false}`

* Default logout as "other" request data and redirect.

### facebookData: `{url: 'auth/facebook', method: 'POST', redirect: '/'}`

* Default  request data and redirect.

### googleData: `{url: 'auth/google', method: 'POST', redirect: '/'}`

* Default  request data and redirect.

### facebookOauth2Data: `{url: 'https://www.facebook.com/v2.5/dialog/oauth', redirect: function () { return this.options.getUrl() + '/login/facebook'; }, clientId: '', scope: 'email'}`

* Default oauth2 data that ships with plugin.
* These can be overridden when calling `oauth2()` method or in the plugin options on init.

### googleOauth2Data: `{url: 'https://accounts.google.com/o/oauth2/auth', redirect: function () { return this.options.getUrl() + '/login/google'; }, clientId: '', scope: 'https://www.googleapis.com/auth/plus.me https://www.googleapis.com/auth/plus.login https://www.googleapis.com/auth/plus.profile.emails.read'}`

* Same as facebookOauth2Data.

### getUrl: `_getUrl`

* Returns the current sites url for use in oauth2 redirects back to the site.

### cookieDomain: `_cookieDomain`

* Set the cookie domain used for `rememberMe` option.

### parseUserData: `_parseUserData`

* Set what data is stored from the user from the response data.

### tokenExpired: `_tokenExpired`

* Hook for checking if a token refresh should occur or not. Set this to return `false` when creating a custom solution.

### check: `_check`

* Function used during `check` method.



## Driver Options

These are driver methods for `router`, `http` and `auth`. If creating a driver it's best to check some of the existing files for samples.

### Router

* `_bindData`
* `_beforeEach`
* `_routerReplace`
* `_routerGo`

### Http

* `_interceptor`
* `_invalidToken`
* `_httpData`
* `_http`
* `_getHeaders`
* `_setHeaders`

### Auth

* `request`
* `response`



## Change Log

### v2.2.x-beta

Vue has been in such a volatile state, especially between versions and 1 and 2. There have been many breaking changes as well as [removing vue-resource as the officially recommended package](https://medium.com/the-vue-point/retiring-vue-resource-871a82880af4) for Vue.

Because of all these changes and potential breaking changes the package has been changed to a much more driver centric model for "router", "resource" and "authentication" . Due to the nature of Vue and the current eco-system with Webpack, to avoid bloat **this means the drivers will need to be passed in manually**. Check the install section for more info.

We will see some ugly `require` code when including the plugin. But as a trade off it will reduce bloat and allow the plugin to much better support different versions of Vue as well as different "router", "resource" and "authentication" modules.

**To ease confusion for this driver centric model the plugin has been bumped to a 2.x version. This will also keep it in line with the current Vue 2.x version.**

* Stability for extend functionality.
* Driver centric model for "router", "resource" and "authentication".
* The options for `router`, `http` and `auth` must be set now and will not auto bind (this is because webpack would pre load all drivers with dynamic variable).
* Added `loginData.fetchUser` option to allow disabling of user fetch on login (which will also be disabled on refreshes).
* Make "authorization" header case insensitive for bearer and basic auth.
* Bearer auth "bearer" text is now case insensitive and will accept with and without colon after "bearer" text.


### v1.5.x-beta

* Added auth driver for "devise".
* Updated docs to include info about parsing user data from server.

### v1.4.x-beta

* Simplified support for auth drivers.


### v1.3.x-beta

* Add support for sub route `auth` matching via parent in Vue 2.


### v1.2.x-beta

* Token parameters now accept `request` and `response` params instead of `name`.
* Support for Vue 2 `auth` in `meta` of route.


### v1.0.x-dev

* Module renamed to `vue-auth` from `vue-jwt-auth`.
* Package name is scoped through `@ganillagrace/vue-auth` now.
* Added demo with lots of sample code.
* Added demo server (https://api-demo.websanova.com) available on GitHub (https://github.com/websanova/laravel-api-demo).
* Any default data for a request is an object now that goes directly into the `http` method. So it can be called with whatever parameters the method supports.
* All `success` and `error` functions will contain proper context from Vue component.
* Redirects can be objects now, so you can do a redirect as a `/path` or `{name: 'object'}` etc.
* There is now a new `register` call with the option to auto login on success.
* The `auth` parameter in routes and the `check()` method now support objects for checking more complicated roles.
* Better handling for invalid tokens.
* All functions are overrideable now.
* There is a driver file for vue which supports the binding between the plugin and framework. This allows multiple drivers and overrides for any issues between versions in the future and allows full backward compatability.
* Reverted from using Vue in the base code and just went back to regular JavaScript (was not really a good idea).
* Any functions, fields parameters that involve logging in a secondary user are called `other` now.
* Actions can now be performed as "admin" user when logged in as "other" user by using `disabledOther` and `enableOther`.
* The `login`, `oauth2`, etc all have their own default parameters now.
* Removed `google` and `facebook` functions just use `oauth2` method now.
* The `logout` method can now perform an api request if `makdeRequest` is set to true.
* Switch to Vanilla JavaScriipt (for development). Had some issues with using fancy es6 syntax.
* Support for drivers allowing more flexibility between different versions (this is still in development).
* Two auth drivers which are named `bearer` and `basic`.
* A fetch call has been added allowing the user to be reset.
* Now supports a "loose" driver based model for authentication allowing for some customization of request/response intercepts for requests.
* The token function will return current function or called with `other` or `default` will return the appropriate token.
* Checking token expiration (base64 decode) has been removed. Since a refresh will not occur often for SPA it was a bit too much extra code. Will need to do it custom if it's really necessary.
* Reduced file size.
* Simpler consistent code base.
* Properly packaged and minified distribution.
* General bug fixes and improvements.