<commit_before># 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)
* [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 @websanova/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('@websanova/vue-auth'), {
    auth: require('@websanova/vue-auth/drivers/auth/bearer.js'),
    http: require('@websanova/vue-auth/drivers/http/resource.1.x.js'),
    router: require('@websanova/vue-auth/drivers/router/router.2.x.js'),
    ...
    rolesVar: 'type'
    ...
});
~~~



## Install 1.x

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

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

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

Vue.use(require('@websanova/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
~~~



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

~~~<commit_msg>Add some "auth flow" documentation.<commit_after># 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 @websanova/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('@websanova/vue-auth'), {
    auth: require('@websanova/vue-auth/drivers/auth/bearer.js'),
    http: require('@websanova/vue-auth/drivers/http/resource.1.x.js'),
    router: require('@websanova/vue-auth/drivers/router/router.2.x.js'),
    ...
    rolesVar: 'type'
    ...
});
~~~



## Install 1.x

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

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

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

Vue.use(require('@websanova/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.

~~~
{'fraction_non_alphanumeric': 0.12228342513770656, 'fraction_numerical': 0.007210816224336504, 'mean_word_length': 3.657649253731343, 'pattern_counts': {'":': 8, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 31, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7669818', 'n_tokens_mistral': 3284, 'n_tokens_neox': 3033, 'n_words': 1220}