vue-msal

#### Wrapper of MSAL.js (Microsoft Authentication Library) for usage in Vue.

The vue-msal library enables client-side vue applications, running in a web browser, to authenticate users using Azure AD work and school accounts (AAD), Microsoft personal accounts (MSA) and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through Azure AD B2C service. It also enables your app to access Microsoft Cloud services such as Microsoft Graph.

Installation

Add the vue-msal dependency to your project using yarn or npm.
``shell script
npm install vue-msal
or
yarn add vue-msal
`

#### Vue Usage
Use the plugin in your vue instance like this
`js
import msal from 'vue-msal'

Vue.use(msal, {
auth: {
clientId: ''
}
});

new Vue({
//... vue options
})
`

#### Nuxt Usage
Add a new javascript file like msal.js under /plugins/ directory with the following content
> :grey_exclamation: Note: you should add Vue as a second argument to the constructor if you want to add the global mixin automatically with the framework.globalMixin option. Check the mixin section below for more information
`js
import Vue from 'vue' //import Vue if you want to use the framework.globalMixin option
import MSAL from 'vue-msal'

export default ({ app, error, $axios }, inject) => {
inject('msal', new MSAL(
{
auth: {
clientId: ''
}
}, Vue / [optional] should be passed as an argument if you want to the framework.globalMixin option/
))
}

`
Then include it to the plugins array in nuxt.config.js like this
`js
export default {
plugins: [
//...
'@/plugins/msal'
//...
]
}
`
This will make the $msal object available in both the vue instances and the context. For example you can access it in the context of a middleware via the app object like this:
`js
export default function ({ app, route, error }) {
// If the user is not authenticated and he's not in the /login page throw Error
if (!app.$msal.isAuthenticated() && route.name !== 'login') {
error({ statusCode: 401, message: 'Unauthorized' });
}
}
`

Plugin usage


When the plugin is initialized it exposes its context to vm.$msal (where vm refers to the Vue's scope) so you can, for example, call the signIn method like this:
`js
new Vue({
//...
created() {
if (!this.$msal.isAuthenticated()) {
this.$msal.signIn();
}
}
});
`
#### List of functions
* signIn(): Start the sign-in process manually
> :grey_exclamation: Note: you can also start the process automatically in case the user needs to be authorized in all pages by setting the option auth.requireAuthOnInitialize to true. Check the Auth Configuration Options below for more details
* signOut(): Sign out an authorized user
* isAuthenticated(): Returns true if the user has been authenticated and false otherwise.
> :grey_exclamation: Note: This function should not be used for reactivity. In order to watch whether the user is authenticated or not you should use the mixin data properties below.
* acquireToken([request[,retries]]): Acquire an access token manually.
> :grey_exclamation: *Note: This will also run automatically after the user's successful authentication using the default permissions defined in the auth.scopes property of the configuration options. You should however run this manually in case you want to get an access token with more permissions than the default, by adding the new request options as an argument, like this

>acquireToken({scopes: ["user.read", "another.permission"]})

>Check the Request Configuration Options below for more details*.

>You can also pass in a second parameter, with a number of retries in case of an unexpected failure (i.e. network errors).
* msGraph(endpoints[,batchUrl]): Manually call the MS Graph API using the acquired access token.
> :grey_exclamation: Note: Read the Calling MS Graph section for more details
* saveCustomData(key, data): You can use this function to add custom data to the selected cache location (set with cache.cacheLocation in the configuration options), that will be automatically deleted when the user signs out or his access token expires. This should be used, for example, to store any user related data fetched from another API.
> :grey_exclamation: Note: You can read this data without reactivity from the data object or with reactivity by watching the msal.custom property of the mixin's data object

$3


You can access the data object that contains all of the user related data using the $msal.data object which is available in nuxt's context. However in case you want reactivity for this data, it is recomended that you use the mixin method below.

The properties provided in the data object are the following:
* isAuthenticated: Is true if the user has been successfully authenticated and false otherwise.
* accessToken: The authenticated user's access token. Read below for information on usage.
* idToken: The authenticated user's id token. Read below for information on usage.
* user: The user's data provided as a response by the authentication's API call
* graph: The data provided as a response by the MS Graph API call that runs on initialization when the graph.callAfterInit option is set to true. Check the Calling MS Graph section for more details
* custom: Whatever data you have saved using the saveCustomData(key, data) function call. (Check the relevant section in the plugin's function list above for more details)

#### Using accessToken vs idToken

accessToken: This token is not validatable outside of MS Graph API* and therefore can only be used for MS Graph calls.
* idToken: This token is validatable and can be used for authentication / authorization with exteral APIs.

#### Mixin
All user related data can be exposed via a mixin in the msal data property so that you can have access to it like you would normally access any of the component's data properties with reactivity.
> :exclamation: Notice that the dollar sign ($) is missing here. While this.$msal refers to the plugin's exposed object, this.msal refers to the mixin's data object. Be careful not to confuse these two.

So for example you can do this:

`html



`
> :exclamation: Note: In case you want to import the mixin globally instead of importing it to specific vue instances you can do so by simply setting the framework.globalMixin to true in the Framework Configuration Options. This will automatically add the mixin to all vue instances so that you have out-of-the-box access to the msal object. In nuxt you must also add the Vue object as an argument to the plugin's initialization for this to work. Check the nuxt usage section for details.

Calling MS Graph

You can directly call the MS Graph API for a logged-in user, with the following methods.

#### Manually calling the MS Graph
In order to manually call the MS Graph API you can use the $msal.msGraph(endpoints[,batchUrl]) function that will automatically use the access token set for the logged in user.

This function receives the following arguments:
* endpoints: [required] This can be either a single value for a single request to the API, or an array of values for a batch request to the API. Each value can be either:
* An object containing the following properties:
* url: [required] This can either be:
A Full URL (starting with 'http...'*) in case of a single request (this is invalid for batch requests)
The URI part (i.e. /me*), which must be used for batch requests but can also be used for single requests (in which case the full URL will be composed using the value of graph.baseUrl option from the Graph Configuration Options as the Base URL).
id: [optional] setting this to a string will result to returning a keyed object instead of an array containing the responses of a batch request. This property is ignored for single requests.*
* Any other optional property from the Axios Request Configuration
* A string containing only the url (following the same rules as the url property of the object type argument)
batchUrl: [optional] using this argument you can set a custom URL for this batch call. If this is not set the graph.baseUrl option from the Graph Configuration Options will be used as the Batch URL. This argument is ignored for single requests.*

The response of this call depends on the arguments passed to it.
* For a single request, it returns the response object (with properties: status, headers, body)
* For a batch request:
* with an array of URIs passed as strings in the endpoints argument, it will return an array of response objects that match the URI's index.
* with an array of objects containing an id, it will return an object keyed with those ids containing the response object.

Example usage:
`js
new Vue({
//...
async mounted() {
let result;
result = await app.$msal.msGraph('https://www.example.com/1.0/me');
// Single request at: https://www.example.com/1.0/me
// Returns: { status: , headers: