Authenticate users using SSO with Teams Toolkit

  • 5 minutes

Microsoft Teams provides single sign-on (SSO) capabilities for an app to obtain the signed-in Teams user's token to access Microsoft Graph and other APIs. In this unit, you learn how to add SSO capabilities to a Microsoft Teams app using Teams Toolkit.

Teams SSO

For apps that interact with the user in a chat, team, or channel, SSO manifests as an Adaptive Card, which the user can interact with to invoke the Microsoft Entra consent flow.

Apps implement different authentication flows to facilitate token retrieval based on the type of app and scenario. Teams Toolkit facilitates SSO implementation by abstracting the Microsoft Entra ID flows and integrations behind simple APIs. This enables you to add SSO features easily to your Teams app, without writing all of the code to implement the authentication flows yourself.

For example, the following code for a message extension with SSO uses the on-behalf-of authentication flow and creates an instance of the Microsoft Graph client to call the Graph API:

const credential = new OnBehalfOfUserCredential(token.ssoToken, oboAuthConfig);
        const attachments = [];
        if (query.parameters[0] && query.parameters[0].name === 'initialRun') {
          const graphClient = createMicrosoftGraphClientWithCredential(credential, 'User.Read');
          const profile = await graphClient.api('/me').get();

Use the How-to Guide to add SSO to your app

The specific details for adding SSO to your Teams app depend on the type of Teams app capability you are implementing for your app. This unit provides an overview of the tasks you'll want to be familiar with at a high-level.

Note

For the most detailed and up-to-date instructions for your scenario, follow the instructions in the SSO How-to Guide provided by Teams Toolkit for Visual Studio Code: Develop single sign on experience in Teams. There are separate instructions for tabs and bots/message extensions.

To access the How-to Guides from the Teams Toolkit for Visual Studio Code extension, select View How-to Guides in the DEVELOPMENT section and then select Develop Single Sign-On Experience in Teams.

Screenshot highlights the option to View How-to guides in the Teams Toolkit extension in Visual Studio Code.

Code samples are linked from the How-to Guide. Be sure to leverage the appropriate code sample for your scenario.

Overview: Adding SSO

To configure a Teams app that you've developed using Teams Toolkit for Visual Studio Code to authenticate users to access Microsoft Graph with SSO, you'll need to complete the following tasks:

  • Add Microsoft Entra app manifest template to your project
  • Update your app manifest
  • Update Teams Toolkit configurations
  • Update your app infrastructure
  • Implement key methods provided by TeamsFx
  • Modify Graph permissions in your app registration
  • Use the Graph client to call the Graph API

Add Microsoft Entra app manifest template to your project

The Microsoft Entra manifest allows you to customize various aspects of your application registration. You can update the manifest as needed. If you used a Teams Toolkit sample or template to create your project, the Entra app manifest may have been added to your project. Otherwise, to add the template to your project:

  1. Download the appropriate Microsoft Entra app manifest template from the templates folder in the TeamsFx repo. For bots or message extensions, download the file from the bot directory. For tabs, download the file from the tab directory.
  2. Save the file as ./aad.manifest.json in the root folder of your Teams app project.

Update your app manifest

To allow users to seamlessly sign into your app, you need to provide your Microsoft Entra App ID and Microsoft Graph information by adding the webApplicationInfo object to your app manifest.

  1. Locate the app manifest that was created by the Teams Toolkit in ./appPackages/manifest.json.
  2. Add the webApplicationInfo object with the following properties:
    • The id contains the Microsoft Entra application ID for your app (a GUID).
    • resource contains the resource URL of the app for acquiring an auth token for SSO.

Here's an example of what you'd provide for a message extension or bot app:

"webApplicationInfo": {
  "id": "${{AAD_APP_CLIENT_ID}}",
  "resource": "api://botid-${{BOT_ID}}"
}

The values in the ${{VARIABLE}} format reference variables in the env/.env.{TEAMSFX_ENV} files in your project's env folder used by Teams Toolkit.

For bots and message extensions, you also need to add/update the commandLists and validDomains objects.

Update teams toolkit configurations

Microsoft Entra related changes and configurations need to be added to your configuration files as follows:

  • Add aadApp/create under provision, as mentioned in the previous unit.
  • Add aadApp/update under provision, as mentioned in the previous unit.
  • Update file/createOrUpdateEnvironmentFile for adding environment variables when debugging locally, such as the following for bots/message extensions:
    • M365_CLIENT_ID: Microsoft Entra app client ID
    • M365_CLIENT_SECRET: Microsoft Entra app client secret
    • M365_TENANT_ID: Tenant ID of Microsoft Entra app
    • INITIATE_LOGIN_ENDPOINT: Login start page for authentication
    • M365_AUTHORITY_HOST: Microsoft Entra app oauth authority host
    • M365_APPLICATION_ID_URI: IdentifierUri for Microsoft Entra app

Update infra

For bots and message extensions, Microsoft Entra related configurations need to be configured in your remote service. The following example shows the configs on an Azure Webapp:

  • M365_CLIENT_ID: Microsoft Entra app client ID
  • M365_CLIENT_SECRET: Microsoft Entra app client secret
  • M365_TENANT_ID: Tenant ID of Microsoft Entra app
  • INITIATE_LOGIN_ENDPOINT: Login start page for authentication
  • M365_AUTHORITY_HOST: Microsoft Entra app oauth authority host
  • M365_APPLICATION_ID_URI: IdentifierUri for Microsoft Entra app

These can be configured in the infra/azure.parameters.json and infra/azure.bicep files. Review the How-To Guide for detailed guidance.

Implement key methods provided by TeamsFX

Finally, you need to update your source code. Teams Toolkit/Teams Fx provides methods you need to implement depending on the Teams app capability you are adding SSO to.

For example, for a message extension, you would need to implement the API method handleMessageExtensionQueryWithSSO in TeamsActivityHandler.handleTeamsMessagingExtensionQuery.

The How-To Guide provides specific implementation guidance for each scenario.