Build a web application with the Microsoft Graph Toolkit

This topic describes how to get started with the Microsoft Graph Toolkit in a web application written in vanilla JavaScript. For a step-by-step tutorial, try the Get started with Microsoft Graph Toolkit module. If you would like to learn how to use the Toolkit with a web framework, see Build a web app (React) or Build a web app (Angular).

Getting started with the Microsoft Graph Toolkit involves the following steps:

1. Add Microsoft Graph Toolkit to your project.
2. Initialize the MSAL2 Provider.
3. Add components.
4. Test your application.

Add the Microsoft Graph Toolkit to your project

You can use the Microsoft Graph Toolkit in your application by referencing the loader directly (via unpkg) or by installing the npm package.

unpkg

To use the Toolkit via mgt-loader, add the reference in a script to your code:

<script src="https://unpkg.com/@microsoft/mgt@2/dist/bundle/mgt-loader.js"></script>

npm

Using the Toolkit via ES6 modules will give you full control of the bundling process and allow you to bundle only the code you need for your application. To use the ES6 modules, add the npm package to your project:

npm install @microsoft/mgt

Initialize the MSAL2 Provider

The Microsoft Graph Toolkit providers enable authentication and access to Microsoft Graph for the components. To learn more, see Using the providers. The MSAL2 Provider uses msal-browser to sign in users and acquire tokens. You can initialize this provider in your HTML or JavaScript.

Note: If you are currently using the MSAL Provider and would like to update to MSAL2 Provider, follow the steps listed here. If you would like to use your own backend authentication, use the Proxy Provider in place of the MSAL2 Provider.

You can choose to initialize the provider in either your HTML or your JavaScript code.

HTML

Add the mgt-msal2-provider component to your HTML page and set the client-id to your application client-id.

<mgt-msal2-provider client-id="<YOUR_CLIENT_ID>"></mgt-msal2-provider>

JavaScript

To initialize the MSAL provider in your JavaScript, add the following code to your application:

import { Providers, Msal2Provider } from '@microsoft/mgt';

Providers.globalProvider = new Msal2Provider({
  clientId: "<YOUR_CLIENT_ID>"
});

The client ID is the only property required to initialize the provider, but you can set additional options. For the full list, see MSAL2 Provider.

Creating an app/client ID

In order to get a client ID, you need to register your application in Azure AD.

Add components

After you initialize the MSAL2 provider, you can start using any of the Toolkit components.

HTML

The following is a full working example using mgt-loader, the MSAL2 Provider initialized in HTML, and the Login component:

<script src="https://unpkg.com/@microsoft/mgt@2/dist/bundle/mgt-loader.js"></script>
<mgt-msal2-provider client-id="<YOUR_CLIENT_ID>"></mgt-msal2-provider>
<mgt-login></mgt-login>

This is an example using the ES6 modules, the MSAL2 Provider initialized in HTML, and the Login component:

<script type="module" src="node_modules/@microsoft/mgt/dist/es6/index.js"></script>
<mgt-msal2-provider client-id="<YOUR_CLIENT_ID>"></mgt-msal2-provider>
<mgt-login></mgt-login>

JavaScript

This is an example using the ES6 modules, the MSAL2 Provider initialized in JavaScript, and the Login component:

import { Providers, Msal2Provider } from '@microsoft/mgt';

Providers.globalProvider = new Msal2Provider({
  clientId: "<YOUR_CLIENT_ID>"
});

function component() {
  const element = document.createElement('div');
  element.innerHTML = '<mgt-login></mgt-login>';
  return element;
}

document.body.appendChild(component());

Test your app

In order to test your app, MSAL requires the page to be hosted in a web server for the authentication redirects.

If you're just getting started and want to play around, you can use Live Server in Visual Studio Code or any similar lightweight development server. Download the extension and open your HTML file using live server.

Note: Make sure the redirect URI in your app registration is set to the localhost port your application is hosted on. Go to your app registration in the Azure portal, click Authentication under manage, and add the correct redirect URI.

Track a user's sign in state

You can detect when a user has successfully signed in and display specific components accordingly. For example, display the agenda component if the user has signed in. Otherwise, display the sign in interface.

To properly inspect the user's sign in state, add an event handler to the providerUpdated event using the Providers.onProviderUpdated function. In the handler, check the provider state stored on the Providers.globalProvider.state property.

HTML

If you're using the mgt-loader library, you can access the Provider and ProviderState from the global mgt property.

<!DOCTYPE html>
<html>
<head>
  <script src="https://unpkg.com/@microsoft/mgt@2/dist/bundle/mgt-loader.js"></script>
</head>
<body>
  <mgt-msal2-provider client-id="<YOUR_CLIENT_ID>"></mgt-msal2-provider>
  <div id="main">
    <mgt-login></mgt-login>
  </div>
  <script>
    const loadAgenda = () => {
      if (mgt.Providers.globalProvider.state === mgt.ProviderState.SignedIn) {
        document.getElementById('main').innerHTML = '<mgt-agenda></mgt-agenda>';
      }
    }
    mgt.Providers.onProviderUpdated(loadAgenda);
  </script>
</body>
</html>

JavaScript

If you're using the toolkit via the npm packages, you can import the Provider and ProviderState from @microsoft/mgt.

import { Providers, ProviderState, Msal2Provider } from '@microsoft/mgt';

Providers.globalProvider = new Msal2Provider({
  clientId: "<YOUR_CLIENT_ID>"
});

const loadAgenda = () => {
  if (Providers.globalProvider.state === ProviderState.SignedIn) {
    document.getElementById('main').innerHTML = '<mgt-agenda></mgt-agenda>';
  }
};

Providers.onProviderUpdated(loadAgenda);

Next Steps

• Check out the Get started with Microsoft Graph Toolkit step-by-step tutorial.
• Try out the components in the playground.
• Ask a question on Stack Overflow.
• Report bugs or leave a feature request on GitHub.