Edit

Build a web application with the Microsoft Graph Toolkit

  • Article

This topic describes how to get started with 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 Toolkit involves the following steps:

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

Add Microsoft Graph Toolkit to your project

You can use Microsoft Graph Toolkit in your application by installing the npm packages or loading it from a Content Delivery Network(CDN).

To use the toolkit via a CDN, add the following script and markup to your HTML page:

<script type="module">
  import {
    registerMgtComponents,
    Providers,
    Msal2Provider,
  } from "https://unpkg.com/@microsoft/mgt@4";
  Providers.globalProvider = new Msal2Provider({ clientId: "[CLIENT-ID]" });
  registerMgtComponents();
</script>

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're currently using the MSAL Provider and would like to update to MSAL2 Provider, see Migrating from MSAL Provider to MSAL2 Provider. If you want 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 JavaScript code or HTML.

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

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";

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

The client ID is the only property required to initialize the provider, but you can set more 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 Microsoft Entra ID.

Add components

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

This example uses the ES6 modules, the MSAL2 Provider initialized in JavaScript, and the Login component:

import { Providers } from "@microsoft/mgt-element";
import { registerMgtLoginComponent } from "@microsoft/mgt-components";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";

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

registerMgtLoginComponent();

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

document.body.appendChild(component());

The following example uses the ES6 modules, the MSAL2 Provider initialized in HTML, and the Login component:

<script type="module">
  import { registerMgtMsal2Provider } from "node_modules/@microsoft/mgt-msal2-provider/dist/es6/index.js";
  import { registerMgtLoginComponent } from "node_modules/@microsoft/mgt-components/dist/es6/index.js";
  registerMgtMsal2Provider();
  registerMgtLoginComponent();
</script>

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

Test your app

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 Microsoft Entra admin center, click Authentication under manage, and add the correct redirect URI.

Track a user's sign in state

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

The package mgt-element provides the isSignedIn utility function that you can call to ascertain if a user is signed in.

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

import { Providers } from "@microsoft/mgt-element";
import {
  registerMgtLoginComponent,
  registerMgtAgendaComponent,
} from "@microsoft/mgt-components";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
import { isSignedIn } from "@microsoft/mgt-element";

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

registerMgtLoginComponent();
registerMgtAgendaComponent();

const loadAgenda = () => {
  if (isSignedIn()) {
    document.getElementById("main").innerHTML = "<mgt-agenda></mgt-agenda>";
  }
};

Providers.onProviderUpdated(loadAgenda);

Next Steps