TeamsFx SDK

TeamsFx reduces your tasks by utilizing Microsoft Teams single sign-on (SSO) and accessing cloud resources with single-line statements and zero configuration. You can use TeamsFx SDK in both browser and Node.js environments. TeamsFx core functionalities are accessible in client and server environments. You can write user authentication code for:

• Teams tab
• Teams bot
• Azure Function

Prerequisites

Install the following tools and set up your development environment:

For more information on Node.js version compatibility, see Prerequisites for creating your Teams app using Visual Studio Code.

You must have working knowledge of:

• Source code
• Package (NPM)
• API reference documentation
• Samples

Get started

TeamsFx SDK is pre-configured in the scaffolded project using Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx Toolkit or CLI). For more information, see Teams app project.

Install the package

Install @microsoft/m365agentstoolkit-cli from npm and run atk -h to check all available commands:

npm install -g @microsoft/m365agentstoolkit-cli
atk -h

TeamsFx core functionalities

TeamsFx class

TeamsFx class instance accesses all TeamsFx settings from the environment variables by default. You can set customized configuration values to override the default values. For more information, see override configuration for details. When creating a TeamsFx instance, you need to specify the identity type.

The following list provides the two different types of identities:

• User Identity: Represents the current user of Teams.
• Application Identity: Represents the application itself.

You can learn more about user identity and application identity in the following section:

Credential

Credential classes implement the TokenCredential interface that is broadly used in Azure library APIs designed to provide access tokens for specific scopes. For more information on credential and auth flow related classes, see credential folder.

There are three credential classes to simplify authentication. Here's the corresponding scenarios for each credential class target:

Bot SSO

Bot related classes are stored under bot folder.

TeamsBotSsoPrompt integrates with the bot framework. It simplifies the authentication process when you develop bot application and want to use the bot SSO.

The following code is an example to create TeamsBotSsoPrompt:

const TeamsBotSsoPromptId = "TEAMS_BOT_SSO_PROMPT";

const settings: TeamsBotSsoPromptSettings = {
 scopes: ["User.Read"],
 timeout: 900000,
 endOnInvalidMessage: true,
};

const authConfig: OnBehalfOfCredentialAuthConfig = {
 authorityHost: process.env.M365_AUTHORITY_HOST,
 clientId: process.env.M365_CLIENT_ID,
 tenantId: process.env.M365_TENANT_ID,
 clientSecret: process.env.M365_CLIENT_SECRET,
};
const loginUrl = process.env.INITIATE_LOGIN_ENDPOINT;
const ssoPrompt = new TeamsBotSsoPrompt(authConfig, loginUrl, TeamsBotSsoPromptId, settings);

Supported functions

TeamsFx SDK provides several functions to ease the configuration for third-party libraries. They're located under core folder.

• Microsoft Graph Service: createMicrosoftGraphClient, createMicrosoftGraphClientWithCredential, and MsGraphAuthProvider help to create authenticated Graph instance.

• SQL: The getTediousConnectionConfig returns a tedious connection config.

  Required configuration:

  • If you want to use the user identity, then sqlServerEndpoint, sqlUsername, and sqlPassword are required.
  • If you want to use the MSI identity, then sqlServerEndpoint and sqlIdentityId are required.

Override configuration for TeamsFx class

You can pass custom config when creating a new TeamsFx instance to override default configuration or set required fields when environment variables are missing.

Error handling

Basic type of API error response is ErrorWithCode, which contains error code and error message. For example, to filter out specific error, you can use the following snippet:

try {
 const atk = new TeamsFx();
 await teamsfx.login("User.Read");
} catch (err: unknown) {
 if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
 throw err;
 } else {
 // Silently fail because user cancels the consent dialog
 return;
 }
}

try {
 const authConfig: TeamsUserCredentialAuthConfig = {
 clientId: process.env.REACT_APP_CLIENT_ID,
 initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
 };

 const credential = new TeamsUserCredential(authConfig); 
 await credential.login("User.Read");
} catch (err: unknown) {
 if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
 throw err;
 } else {
 // Silently fail because user cancels the consent dialog
 return;
 }
}

If a credential instance is used in other library, such as Microsoft Graph, it's possible that an error is caught and transformed.

Microsoft Graph Scenarios

This section provides several code snippets for common scenarios that are related to the Microsoft Graph. In such scenarios, user can call APIs using different permissions in frontend or backend.

• User delegate permission in frontend (Use TeamsUserCredential)

• User delegate permission in backend (Use OnBehalfOfUserCredential)

• Application permission in backend

Other scenarios

This section provides several code snippets for other scenarios related to Microsoft Graph. You can create an API client in a Bot or Azure Function and access an SQL database in an Azure Function.

Advanced Customization

Configure log

You can set customer log level and redirect outputs when using this library.

Enable log by setting log level

When you set the log level, logging gets enabled. It prints log information to the console by default.

Set the log level using the following snippet:

// Only need the warning and error messages.
setLogLevel(LogLevel.Warn);

Redirect by setting custom logger

setLogLevel(LogLevel.Info);
// Set another logger if you want to redirect to Application Insights in Azure Function
setLogger(context.log);

Redirect by setting custom log function

setLogLevel(LogLevel.Info);
// Only log error messages to Application Insights in bot application.
setLogFunction((level: LogLevel, message: string) => {
 if (level === LogLevel.Error) {
 this.telemetryClient.trackTrace({
 message: message,
 severityLevel: Severity.Error,
 });
 }
});

Upgrade to latest SDK version

If you're using the version of the SDK that has loadConfiguration(), you can perform the following steps to upgrade to the latest SDK version:

1. Instead of calling loadConfiguration(), use the specific auth config classes to customize the settings for each credential type. For example, use AppCredentialAuthConfig for AppCredential, OnBehalfOfUserCredentialAuthConfig for OnBehalfOfUserCredential, and TeamsUserCredentialAuthConfig for TeamsUserCredential.
2. Replace new TeamsUserCredential() with new TeamsUserCredential(authConfig).
3. Replace new M365TenantCredential() with new AppCredential(authConfig).
4. Replace new OnBehalfOfUserCredential(ssoToken) with new OnBehalfOfUserCredential(authConfig).

See also

• Microsoft 365 Agents Toolkit Overview
• Microsoft 365 Agents Toolkit CLI
• Microsoft TeamsFx sample gallery.
• Add single sign-on to Teams app