@microsoft/teamsfx

TeamsFx SDK for TypeScript/JavaScript

TeamsFx aims to reduce the developer tasks of implementing identity and access to cloud resources down to single-line statements with "zero configuration".

Use the library to:

• Access core functionalities in client and server environment in a similar way.
• Write user authentication code in a simplified way.

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

Getting started

TeamsFx SDK is pre-configured in scaffolded project using TeamsFx toolkit or cli. Please check the README to see how to create a Teams App project.

Prerequisites

• Node.js version 10.x.x or higher
• A project created by TeamsFx toolkit VS Code extension or Cli tool.
• If your project has installed botbuilder related packages as dependencies, ensure they are of the same version and the version >= 4.9.3. (Issue - all of the BOTBUILDER packages should be the same version)

Install the @microsoft/teamsfx package

Install the TeamsFx SDK for TypeScript/JavaScript with npm:

npm install @microsoft/teamsfx

Create and authenticate a MicrosoftGraphClient

To create a graph client object to access the Microsoft Graph API, you will need the credential to do authentication. The SDK provides several credential classes to choose that meets various requirements.

Please note that you need to load configuration before using any credentials.

• In browser environment, you need to explicitly pass in the config parameters. The scaffolded React project has provided environment variables to use.

loadConfiguration({
  authentication: {
    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
    simpleAuthEndpoint: process.env.REACT_APP_TEAMSFX_ENDPOINT,
    clientId: process.env.REACT_APP_CLIENT_ID,
  },
});

• In NodeJS environment like Azure Function, you can just call loadConfiguration. It will load from environment variables by default.

loadConfiguration();

Using Teams App User Credential

Use the snippet below:

Note: You can only use this credential class in browser application like Teams Tab App.

loadConfiguration({
  authentication: {
    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
    simpleAuthEndpoint: process.env.REACT_APP_TEAMSFX_ENDPOINT,
    clientId: process.env.REACT_APP_CLIENT_ID,
  },
});
const credential = new TeamsUserCredential();
const graphClient = createMicrosoftGraphClient(credential, ["User.Read"]); // Initializes MS Graph SDK using our MsGraphAuthProvider
const profile = await graphClient.api("/me").get();

Using Microsoft 365 Tenant Credential

It doesn't require the interaction with Teams App user. You can call Microsoft Graph as application. Use the snippet below:

loadConfiguration();
const credential = new M365TenantCredential();
const graphClient = createMicrosoftGraphClient(credential);
const profile = await graphClient.api("/users/{object_id_of_another_people}").get();

Core Concepts & Code Structure

Credential

There are 3 credential classes that are used to help simplifying authentication. They are located under credential folder. Credential classes implements TokenCredential interface that is broadly used in Azure library APIs. They are designed to provide access token for specific scopes. The credential classes represents different identity under certain scenarios.

TeamsUserCredential represents Teams current user's identity. Using this credential will request user consent at the first time. M365TenantCredential represents Microsoft 365 tenant identity. It is usually used when user is not involved like time-triggered automation job. OnBehalfOfUserCredential uses on-behalf-of flow. It needs an access token and you can get a new token for different scope. It's designed to be used in Azure Function or Bot scenarios.

Bot

Bot related classes are stored under bot folder.

TeamsBotSsoPrompt has a good integration with Bot framework. It simplifies the authentication process when you develops bot application.

Helper Function

TeamsFx SDK provides helper functions to ease the configuration for third-party libraries. They are located under core folder.

Error Handling

API will throw ErrorWithCode if error happens. Each ErrorWithCode contains error code and error message.

For example, to filter out all errors, you could use the following check:

try {
  const credential = new TeamsUserCredential();
  const graphClient = createMicrosoftGraphClient(credential, ["User.Read"]); // Initializes MS Graph SDK using our MsGraphAuthProvider
  const profile = await graphClient.api("/me").get();
} catch (err) {
  // Show login button when specific ErrorWithCode is caught.
  if (err instanceof ErrorWithCode && err.code === ErrorCode.UiRequiredError) {
    this.setState({
      showLoginBtn: true,
    });
  }
}

Examples

The following sections provide several code snippets covering some of the most common scenarios, including:

• Use Graph API in tab app
• Call Azure Function in tab app
• Access SQL database in Azure Function
• Use Graph API in Bot application

Use Graph API in tab app

Use TeamsUserCredential and createMicrosoftGraphClient.

loadConfiguration({
  authentication: {
    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
    simpleAuthEndpoint: process.env.REACT_APP_TEAMSFX_ENDPOINT,
    clientId: process.env.REACT_APP_CLIENT_ID,
  },
});
const credential: any = new TeamsUserCredential();
const graphClient = createMicrosoftGraphClient(credential, ["User.Read"]);
const profile = await graphClient.api("/me").get();

Call Azure Function in tab app

Use axios library to make HTTP request to Azure Function.

loadConfiguration({
  authentication: {
    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
    simpleAuthEndpoint: process.env.REACT_APP_TEAMSFX_ENDPOINT,
    clientId: process.env.REACT_APP_CLIENT_ID,
  },
});
const credential: any = new TeamsUserCredential();
const token = credential.getToken(""); // Get SSO token for the user
// Call API hosted in Azure Functions on behalf of user
const apiConfig = getResourceConfiguration(ResourceType.API);
const response = await axios.default.get(apiConfig.endpoint + "api/httptrigger1", {
  headers: {
    authorization: "Bearer " + token,
  },
});

Access SQL database in Azure Function

Use tedious library to access SQL and leverage DefaultTediousConnectionConfiguration that manages authentication. Apart from tedious, you can also compose connection config of other SQL libraries based on the result of sqlConnectionConfig.getConfig().

loadConfiguration();
const sqlConnectConfig = new DefaultTediousConnectionConfiguration();
const config = await sqlConnectConfig.getConfig();
const connection = new Connection(config);
connection.on("connect", (error) => {
  if (error) {
    console.log(error);
  }
});

Use Graph API in Bot application

Add TeamsBotSsoPrompt to dialog set.

const { ConversationState, MemoryStorage } = require("botbuilder");
const { DialogSet, WaterfallDialog } = require("botbuilder-dialogs");
const { TeamsBotSsoPrompt } = require("@microsoft/teamsfx");

const convoState = new ConversationState(new MemoryStorage());
const dialogState = convoState.createProperty("dialogState");
const dialogs = new DialogSet(dialogState);

loadConfiguration();
dialogs.add(
  new TeamsBotSsoPrompt("TeamsBotSsoPrompt", {
    scopes: ["User.Read"],
  })
);

dialogs.add(
  new WaterfallDialog("taskNeedingLogin", [
    async (step) => {
      return await step.beginDialog("TeamsBotSsoPrompt");
    },
    async (step) => {
      const token = step.result;
      if (token) {
        // ... continue with task needing access token ...
      } else {
        await step.context.sendActivity(`Sorry... We couldn't log you in. Try again later.`);
        return await step.endDialog();
      }
    },
  ])
);

Troubleshooting

Configure log

You can set custome log level and redirect outputs when using this library. Logging is turned off by default, you can turn it on by setting log level.

Enable log by setting log level

When log level is set, logging is enabled. It prints log information to console by default.

Set log level using the snippet below:

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

You can redirect log output by setting custom logger or log function.

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

Please note that log function will not take effect if you set a custom logger.

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

Next steps

Please take a look at the Samples project for detailed examples on how to use this library.

Related projects

• Microsoft Teams Toolkit for Visual Studio Code
• TeamsFx Cli

Data Collection.

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.

Contributing

There are many ways in which you can participate in the project, for example:

• Submit bugs and feature requests, and help us verify as they are checked in
• Review source code changes

If you are interested in fixing issues and contributing directly to the code base, please see the Contributing Guide.

Reporting Security Issues

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them to the Microsoft Security Response Center (MSRC) at https://msrc.microsoft.com/create-report.

If you prefer to submit without logging in, send email to [e-mail]. If possible, encrypt your message with our PGP key; please download it from the the Microsoft Security Response Center PGP Key page.

You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at microsoft.com/msrc.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

License

Copyright (c) Microsoft Corporation. All rights reserved.

Licensed under the MIT license.