Build a Microsoft Teams tab with the Microsoft Graph Toolkit

This topic covers how to get started using the Microsoft Graph Toolkit in a Microsoft Teams solution. This guide is for a single page app without single sign-on (SSO) and does not require a backend. If you're implementing SSO with a custom backend, see Build a Microsoft Teams tab (SSO).

Building a tab involves the following steps:

  1. Add the Microsoft Graph Toolkit.
  2. Create the auth popup page.
  3. Creating an app/client ID
  4. Initialize the Teams MSAL2 Provider.
  5. Add components.
  6. Test your app.

Add the Microsoft Graph Toolkit

You can use the Microsoft Graph Toolkit in your application by referencing the loader directly (via unpkg) or by installing the npm packages. To use the Toolkit, you will also need the Microsoft Teams SDK.

To use the Toolkit and the Teams SDK via the loaders, add the reference in a script to your code:

<!-- Microsoft Teams sdk must be referenced before the toolkit -->
<script src="https://unpkg.com/@microsoft/teams-js/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>

Create the auth popup page

In order to allow users to sign in, you will need a page in your app that Teams will open in a popup to follow the authentication flow. The path to the page can be anything as long as it is in the same domain as your app (for example, https://yourdomain.com/tabauth). The only requirement for this page is to call the TeamsMsal2Provider.handleAuth() method, but you can add any content or loading progress you want.

The following is an example of basic page that handles the auth flow in the popup.

<!DOCTYPE html>
<html>
  <head>
    <script src="https://unpkg.com/@microsoft/teams-js/dist/MicrosoftTeams.min.js" crossorigin="anonymous"></script>
    <script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
  </head>

  <body>
    <script>
      mgt.TeamsMsal2Provider.handleAuth();
    </script>
  </body>
</html>

Creating an app/client ID

To get a client ID, you need to register an Azure Active Directory application. Follow the steps in the Create an Azure Active Directory app article.

Make sure to set the redirect URI in your app registration to point to the auth page you created in the previous step. For example, https://localhost:3000/tabauth.

Note: Make sure to set the redirect URI as a Single Page Application (SPA). Teams MSAL2 Provider makes use of MSAL2 Provider behind the scenes.

Initialize the Teams 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 Teams MSAL2 Provider handles all the logic and interactions that need to be implemented with the Teams SDK to authenticate the user.

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

Add the mgt-teams-msal2-provider component to your HTML page as shown.

<mgt-teams-msal2-provider 
  client-id="<YOUR_CLIENT_ID>"
  auth-popup-url="/tabauth"
  scopes="User.Read,Mail.ReadBasic"
  ></mgt-teams-msal2-provider>

Replace <YOUR_CLIENT_ID> with the client ID for your application, and replace the auth-popup-url with the full or relative path to your auth page.

Add components

Now, you're ready to add any of the Microsoft Graph Toolkit components. The first component you will likely need to add is the Login component.

<mgt-login></mgt-login>

The Login component renders a "Sign In" button that guides the user through the sign in process and integrates with any of the providers to handle the authentication. After the user has signed in, all other toolkit components will be able to call Microsoft Graph automatically. The providers also expose an authenticated Microsoft Graph client for making API calls or getting access tokens. For details, see Using the providers.

If you're using React, we recommend using the React components instead from the mgt-react library. To learn more, see Using Microsoft Graph Toolkit with React

Next Steps