\n \n
Vue 3 plugin for integrating Microsoft Authentication Library (MSAL) into your app, offering easy-to-use composables.
\n\n## Requirements\n\n- Node.js 20 or newer\n- Vue 3.5 or newer\n- [`@azure/msal-browser`](https://www.npmjs.com/package/@azure/msal-browser) 4 or newer\n\n## Installation\n\nTo install the package, use the following npm command:\n\n```sh\nnpm i vue3-msal-plugin\n```\n\n## Quick Start\n\n```ts\n// main.ts\nimport { createApp } from 'vue';\nimport { msalPlugin, msalInstance } from 'vue3-msal-plugin';\nimport type { Configuration } from '@azure/msal-browser';\nimport App from './App.vue';\n\nconst config: Configuration = { auth: { clientId: '...', authority: '...', redirectUri: '...' } };\nconst app = createApp(App);\napp.use(msalPlugin, msalInstance(config));\napp.mount('#app');\n```\n\nThen use the `useMsal` composable inside any component:\n\n```ts\nimport { useMsal } from 'vue3-msal-plugin';\n\nconst { instance, accounts, inProgress } = useMsal();\n```\n\nSee the [Configuration](#configuration) and [Composables](#composables) sections below for the full API.\n\n## Sample Apps\n\nYou can check out the sample apps to see how to use this package.\n\n1. [Vue 3 App with Pinia](https://github.com/DulanDev/vue3-msal/tree/main/samples/sample-with-pinia)\n2. [Quasar App](https://github.com/DulanDev/vue3-msal/tree/main/samples/sample-with-quasar)\n3. [Nuxt App](https://github.com/DulanDev/vue3-msal/tree/main/samples/sample-with-nuxt)\n\n## Configuration\n\nIn your main.ts file, you need to initialize the plugin with your MSAL instance.\n\n```typescript\nimport { createApp } from 'vue';\n\nimport App from './App.vue';\nimport router from './router';\n\nimport { msalPlugin, msalInstance } from 'vue3-msal-plugin';\nimport type { Configuration, AuthenticationResult } from '@azure/msal-browser';\nimport { EventType } from '@azure/msal-browser';\n\nconst app = createApp(App);\n\n// Define the configuration for the MSAL instance\n// For more detailed usage and other available options, please refer to the official MSAL.js documentation - https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/configuration.md\n\nconst msalConfig: Configuration = {\n auth: {\n clientId: import.meta.env.VITE_CLIENT_ID,\n authority: import.meta.env.VITE_AUTHORITY,\n redirectUri: 'http://localhost:5173', // Must be registered as a SPA redirectURI on your app registration\n postLogoutRedirectUri: 'http://localhost:5173', // Must be registered as a SPA redirectURI on your app registration\n },\n cache: {\n cacheLocation: 'localStorage',\n },\n};\n\n// Create a new MSAL instance with the defined configuration\nconst newMsalInstance = msalInstance(msalConfig);\n\n// Get all accounts from the MSAL instance\nconst accounts = newMsalInstance.getAllAccounts();\nif (accounts.length > 0) {\n // If there are any accounts, set the first one as the active account\n newMsalInstance.setActiveAccount(accounts[0]);\n}\n\n// Add an event callback to the MSAL instance\nnewMsalInstance.addEventCallback((event) => {\n // If the event is a successful login and the event has a payload\n if (event.eventType === EventType.LOGIN_SUCCESS && event.payload) {\n // Cast the payload to an AuthenticationResult\n const payload = event.payload as AuthenticationResult;\n // Get the account from the payload\n const account = payload.account;\n // Set the account as the active account in the MSAL instance\n newMsalInstance.setActiveAccount(account);\n\n /* Optionally, You can update the user store with the account data here.\n 'account' refers to the account data obtained from the MSAL instance.\n updateUser(account)\n */\n }\n});\n\napp.use(router);\n\n// Use the vue3-msal-plugin with the MSAL instance\napp.use(msalPlugin, newMsalInstance);\n\n// Handle page refresh\n// Get the active account from the MSAL instance\nconst activeAccount = newMsalInstance.getActiveAccount();\nif (activeAccount) {\n /* Optionally, you can update the user store with the account data here.\n 'account' refers to the account data obtained from the MSAL instance.\n updateUser(activeAccount)\n */\n}\n\napp.mount('#app');\n```\n\n## Composables\n\nThe plugin provides a `useMsal` composable that you can use in your components to access the MSAL instance and its related properties and methods. Here's an example:\n\n```typescript\nimport { useMsal } from 'vue3-msal-plugin';\n\nconst { instance, accounts, inProgress } = useMsal();\n\nconsole.log('instance', instance); // MSAL instance\nconsole.log('accounts', accounts.value); // Array of account objects\nconsole.log('inProgress', inProgress.value); // Authentication status\n```\n\nThe `instance` is the MSAL instance, `accounts` is an array of account objects, and `inProgress` is a reactive property that indicates the authentication status.\n\nThe `useMsal` function also initializes the MSAL instance and handles redirect promises if the interaction status is `InteractionStatus.Startup`.\n\nFor login operations, a `loginRequest` object is used. It contains a `scopes` property which is an array of permission scopes. All parameters in the login requests are optional, so you can just send an empty object.\n\nRead more about scopes [here.](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/request-response-object.md#scopes)\n\nYou can use these methods to perform various authentication operations:\n\n```typescript\nconst { instance, accounts, inProgress, loginRequest } = useMsal();\n\nconst loginPopup = () => {\n instance.loginPopup(loginRequest);\n};\n\nconst loginRedirect = () => {\n instance.loginRedirect(loginRequest);\n};\n\nconst logoutPopup = () => {\n instance.logoutPopup({\n mainWindowRedirectUri: '/',\n });\n};\n\nconst logoutRedirect = () => {\n instance.logoutRedirect();\n};\n```\n\n### useIsAuthenticated\n\nThe `useIsAuthenticated` composable provides a reactive property that indicates whether the user is authenticated or not.\n\n```typescript\nimport { useIsAuthenticated } from 'vue3-msal-plugin';\n\nconst isAuthenticated = useIsAuthenticated(); // Reactive property\n```\n\nYou can use this property to conditionally render components or perform actions based on the authentication status of the user.\n\n### useMsalAuthentication\n\nThe `useMsalAuthentication` composable from vue3-msal-plugin provides a way to handle authentication and acquire tokens using MSAL.\n\n```typescript\nimport { useMsalAuthentication, InteractionType } from 'vue3-msal-plugin';\n\nconst { acquireToken, result, error, inProgress } = useMsalAuthentication(interactionType, request);\n```\n\n**`useMsalAuthentication` takes two parameters:**\n\n- `interactionType`: This is of type InteractionType and it specifies the type of interaction to be used for authentication. It can be Popup, Redirect, or Silent.\n\n- `request`: This is an object of type PopupRequest, RedirectRequest, or SilentRequest. It contains the parameters for the authentication request.\n\n**`useMsalAuthentication` returns an object with the following properties:**\n\n- `acquireToken`: This is a function that can be used to manually initiate the token acquisition process. It takes an optional requestOverride parameter which can be used to override the initial request parameters.\n\n- `result`: This is a reactive property that holds the result of the authentication process. It will be null if the process has not completed or if an error occurred.\n\n- `error`: This is a reactive property that holds any error that occurred during the authentication process. It will be null if no error occurred.\n\n- `inProgress`: This is a reactive property that indicates whether the authentication process is currently in progress.\n\nThe `useMsalAuthentication` function automatically initiates the token acquisition process when it is called. If the process is not completed and no error occurred, it will be re-initiated whenever the global inProgress status changes.\n\nPlease note that `useMsalAuthentication` should only be called within the setup() function of a Vue component. Also, the MSAL plugin must be installed in your application. If these conditions are not met, useMsalAuthentication will throw an error.\n\n### callMsGraph\n\n#### Makes a GET request to the Microsoft Graph API\n\nThe `callMsGraph` function takes an access token as a parameter and returns a promise that resolves with the response data from the Microsoft Graph API.\n\nYou can see an example of how to use this function in here [MyProfile.vue](https://github.com/DulanDev/vue3-msal/blob/main/samples/sample-with-pinia/src/components/MyProfile.vue).\n\n```typescript\nimport { ref, watch } from 'vue';\nimport type { Ref } from 'vue';\nimport { useMsal } from 'vue3-msal-plugin';\nimport type { AccountInfo } from '@azure/msal-browser';\n\nconst { callMsGraph } = useMsal();\ntype UserInfo = AccountInfo | null;\n\nconst msGraphData: Ref