Microsoft Teams MSAL2 provider

Use the Microsoft Teams MSAL2 provider inside your Microsoft Teams tab to facilitate authentication and Microsoft Graph access to all components. The provider can be used for single sign-on (SSO) or interactive sign in.

To learn more, see providers.

Tip: For details about how to create a Microsoft Teams application with the Teams MSAL2 provider, see Build a Microsoft Teams tab and Build a Microsoft Teams tab with SSO.

Difference between Teams Provider and Teams MSAL2 Provider

Unlike the Teams provider, the Teams MSAL2 provider supports single sign-on (SSO) and is built on msal-browser for client-side authentication. msal-browser implements the OAuth 2.0 Authorization Code Flow with PKCE. Because Authorization Code Flow is deemed more secure than Implicit Grant Flow for web applications, we recommend using Teams MSAL2 Provider over the Teams Provider. For details about security issues related to implicit grant flow, see Disadvantages of the implicit flow.

All new applications should use Teams MSAL2 provider whenever possible.

Get started

The provider can be used in interactive client side auth mode or SSO mode.

Client-side authentication

In client-side authentication (or interactive authentication), the user will be asked to authenticate when they first launch the app. The user will need to use a sign in button to initiate the authentication flow. This can be done on the client and does not require a backend service.

SSO authentication

To avoid asking the user to authenticate to the app, Microsoft Teams tabs can also use SSO to automatically authenticate users. However, this process requires a backend service that is used to exchange the Microsoft Teams-provided token with an access token that can be used to access Microsoft Graph.

Teams MSAL2 provider supports SSO mode, which is enabled when ssoUrl \ sso-url are set to a backend service that is capable of exchanging the tokens. The backend service is required to expose an API (such as api/token) that will receive an authentication token from Microsoft Teams and use the on-behalf-of flow to exchange the token for an access token that can access Microsoft Graph. For a reference implementation of a node backend service, see the Microsoft Teams Node SSO sample.

Initialize the provider

Before using the Teams MSAL2 provider, make sure to reference the Microsoft Teams SDK in your page.

Initialize the Teams MSAL2 provider in your main code.

When initializing the Teams MSAL2 provider in JavaScript, make sure to install both the toolkit and the Microsoft Teams SDK.

npm install @microsoft/teams-js @microsoft/mgt-element @microsoft/mgt-teams-msal2-provider

Next, import and use the provider.

import {Providers} from '@microsoft/mgt-element';
import {TeamsMsal2Provider} from '@microsoft/mgt-teams-msal2-provider';
import * as MicrosoftTeams from "@microsoft/teams-js";

TeamsMsal2Provider.microsoftTeamsLib = MicrosoftTeams;

Providers.globalProvider = new TeamsMsal2Provider(config);

where config is

export interface TeamsMsal2Config {
  clientId: string;
  authPopupUrl: string; // see below for creating the popup page
  scopes?: string[];
  msalOptions?: Configuration;
  ssoUrl?: string; // ex: '/api/token',
  autoConsent?: boolean,
  httpMethod: HttpMethod; //ex HttpMethod.POST
}

Create the popup page

To sign in with your Teams credentials and handle consent, you need provide a URL that the Teams app will open in a popup, which will follow the authentication flow. Create a new page in your application (for example, https://mydomain.com/auth) that will handle the auth redirect and call the TeamsMsal2Provider.handleAuth method. That's the only thing that this page needs to do. For example:

import * as MicrosoftTeams from "@microsoft/teams-js/dist/MicrosoftTeams";
import {TeamsMsal2Provider} from '@microsoft/mgt-teams-msal2-provider';

TeamsMsal2Provider.microsoftTeamsLib = MicrosoftTeams;
TeamsMsal2Provider.handleAuth();

Configure your Teams app

If you're just getting started with Teams apps, see Add tabs to Microsoft Teams apps. You can use the Developer Portal for Teams to configure, distribute, and manage your application. You can access the Developer Portal for Teams in a web browser or as a Teams App.

You can also use the Teams Toolkit in Visual Studio Code to quickly create and deploy your Teams app.

Creating an app/client ID

For details about how to register an app and get a client ID for interactive authentication, see Create an Azure Active Directory app.

For details about how to register an app and get a client ID and secret for SSO, see Build a Microsoft Teams tab with Single Sign-On.

Migrating from Teams Provider to Teams MSAL2 Provider

To migrate an application that's using Teams Provider to the Teams MSAL2 Provider:

  1. Go to the Azure portal at https://portal.azure.com.

  2. From the menu, select Azure Active Directory.

  3. From the Azure Active Directory menu, select App registrations.

  4. Select the app registration of the app that you're currently using.

  5. On the left menu, go to Authentication.

  6. Under Platform configurations, choose Add a platform and select Single-page Application.

  7. Remove all the redirect URIs that you have currently registered under Web, and instead add them under Single-page application.

  8. In your code, replace TeamsProvider with Teams MSAL2 Provider.

    If you are initializing your provider in the JS/TS code, follow these steps:

    Replace the import statement for mgt-teams-provider with

    import {TeamsMsal2Provider} from '@microsoft/mgt-teams-msal2-provider';
    

    Replace the initialization of MsalProvider with

    Providers.globalProvider = new TeamsMsal2Provider(config);
    

    If you are initializing the provider in HTML, replace

    <mgt-teams-provider client-id="<YOUR_CLIENT_ID>" auth-popup-url="/AUTH-PATH" ... ></mgt-teams-provider>
    

    with

    <mgt-teams-msal2-provider client-id="<YOUR_CLIENT_ID>" auth-popup-url="/AUTH-PATH" ... ></mgt-teams-msal2-provider>
    

See also