@microsoft/teamsfx package

Classes

DefaultTediousConnectionConfiguration	SQL connection configuration instance.
ErrorWithCode	Error class with code and message thrown by the SDK.
M365TenantCredential	Represent Microsoft 365 tenant identity, and it is usually used when user is not involved like time-triggered automation job. Example TypeScript loadConfiguration(); // load configuration from environment variables const credential = new M365TenantCredential();
MsGraphAuthProvider	Microsoft Graph auth provider for Teams Framework
OnBehalfOfUserCredential	Represent on-behalf-of flow to get user identity, and it is designed to be used in server side. Example TypeScript loadConfiguration(); // load configuration from environment variables const credential = new OnBehalfOfUserCredential(ssoToken);
TeamsBotSsoPrompt	Creates a new prompt that leverage Teams Single Sign On (SSO) support for bot to automatically sign in user and help receive oauth token, asks the user to consent if needed. Example When used with your bots DialogSet you can simply add a new instance of the prompt as a named dialog using DialogSet.add(). You can then start the prompt from a waterfall step using either DialogContext.beginDialog() or DialogContext.prompt(). The user will be prompted to sign in as needed and their access token will be passed as an argument to the callers next waterfall step: JavaScript 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(); } } ]));
TeamsUserCredential	Represent Teams current user's identity, and it is used within Teams client applications.

Interfaces

AuthenticationConfiguration	Authentication related configuration.
Configuration	Configuration for current environment.
GetTokenOptions	Defines options for TokenCredential.getToken.
Logger	Interface for customized logger.
ResourceConfiguration	Configuration for resources.
TeamsBotSsoPromptSettings	Settings used to configure an TeamsBotSsoPrompt instance.
TeamsBotSsoPromptTokenResponse	Token response provided by Teams Bot SSO prompt
TokenCredential	Represents a credential capable of providing an authentication token.
UserInfo	UserInfo with user displayName, objectId and preferredUserName.

Type Aliases

LogFunction

Log function for customized logging.

Enums

ErrorCode	Error code to trace the error types.
LogLevel	Log level.
ResourceType	Available resource type.

Functions

createMicrosoftGraphClient(TokenCredential, string | string[])	Get Microsoft graph client. Example Get Microsoft graph client by TokenCredential TypeScript // Sso token example (Azure Function) const ssoToken = "YOUR_TOKEN_STRING"; const options = {"AAD_APP_ID", "AAD_APP_SECRET"}; const credential = new OnBehalfOfAADUserCredential(ssoToken, options); const graphClient = await createMicrosoftGraphClient(credential); const profile = await graphClient.api("/me").get(); // TeamsBotSsoPrompt example (Bot Application) const requiredScopes = ["User.Read"]; const config: Configuration = { loginUrl: loginUrl, clientId: clientId, clientSecret: clientSecret, tenantId: tenantId }; const prompt = new TeamsBotSsoPrompt(dialogId, { config: config scopes: '["User.Read"], }); this.addDialog(prompt); const oboCredential = new OnBehalfOfAADUserCredential( getUserId(dialogContext), { clientId: "AAD_APP_ID", clientSecret: "AAD_APP_SECRET" }); try { const graphClient = await createMicrosoftGraphClient(credential); const profile = await graphClient.api("/me").get(); } catch (e) { dialogContext.beginDialog(dialogId); return Dialog.endOfTurn(); }
getAuthenticationConfiguration()	Get configuration for authentication.
getLogLevel()	Get log level.
getResourceConfiguration(ResourceType, string)	Get configuration for a specific resource.
loadConfiguration(Configuration)	Initialize configuration from environment variables or configuration object and set the global instance
setLogFunction(LogFunction)	Set custom log function. Use the function if it's set. Priority is lower than setLogger. Example TypeScript setLogFunction((level: LogLevel, message: string) => { if (level === LogLevel.Error) { console.log(message); } });
setLogLevel(LogLevel)	Update log level helper.
setLogger(Logger)	Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction. Example TypeScript setLogger({ verbose: console.debug, info: console.info, warn: console.warn, error: console.error, });

Function Details

createMicrosoftGraphClient(TokenCredential, string | string[])

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Get Microsoft graph client.

Example

Get Microsoft graph client by TokenCredential

TypeScript

// Sso token example (Azure Function)
const ssoToken = "YOUR_TOKEN_STRING";
const options = {"AAD_APP_ID", "AAD_APP_SECRET"};
const credential = new OnBehalfOfAADUserCredential(ssoToken, options);
const graphClient = await createMicrosoftGraphClient(credential);
const profile = await graphClient.api("/me").get();

// TeamsBotSsoPrompt example (Bot Application)
const requiredScopes = ["User.Read"];
const config: Configuration = {
   loginUrl: loginUrl,
   clientId: clientId,
   clientSecret: clientSecret,
   tenantId: tenantId
};
const prompt = new TeamsBotSsoPrompt(dialogId, {
   config: config
   scopes: '["User.Read"],
});
this.addDialog(prompt);

const oboCredential = new OnBehalfOfAADUserCredential(
 getUserId(dialogContext),
 {
   clientId: "AAD_APP_ID",
   clientSecret: "AAD_APP_SECRET"
 });
try {
   const graphClient = await createMicrosoftGraphClient(credential);
   const profile = await graphClient.api("/me").get();
} catch (e) {
   dialogContext.beginDialog(dialogId);
   return Dialog.endOfTurn();
}

TypeScript

function createMicrosoftGraphClient(credential: TokenCredential, scopes?: string | string[]): Client

Parameters

credential

TokenCredential

token credential instance.

scopes

string | string[]

The array of Microsoft Token scope of access. Default value is [.default].

Returns

Client

Graph client with specified scopes.

getAuthenticationConfiguration()

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Get configuration for authentication.

TypeScript

function getAuthenticationConfiguration(): AuthenticationConfiguration | undefined

Returns

AuthenticationConfiguration | undefined

Authentication configuration from global configuration instance, the value may be undefined if no authentication config exists in current environment.

getLogLevel()

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Get log level.

TypeScript

function getLogLevel(): LogLevel | undefined

Returns

LogLevel | undefined

Log level

getResourceConfiguration(ResourceType, string)

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Get configuration for a specific resource.

TypeScript

function getResourceConfiguration(resourceType: ResourceType, resourceName?: string): {[index: string]: any}

Parameters

resourceType

ResourceType

The type of resource

resourceName

string

The name of resource, default value is "default".

Returns

{[index: string]: any}

Resource configuration for target resource from global configuration instance.

loadConfiguration(Configuration)

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Initialize configuration from environment variables or configuration object and set the global instance

TypeScript

function loadConfiguration(configuration?: Configuration)

Parameters

configuration

Configuration

Optional configuration that overrides the default configuration values. The override depth is 1.

setLogFunction(LogFunction)

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Set custom log function. Use the function if it's set. Priority is lower than setLogger.

Example

TypeScript

setLogFunction((level: LogLevel, message: string) => {
  if (level === LogLevel.Error) {
    console.log(message);
  }
});

TypeScript

function setLogFunction(logFunction?: LogFunction)

Parameters

logFunction

LogFunction

custom log function. If it's undefined, custom log function will be cleared.

setLogLevel(LogLevel)

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Update log level helper.

TypeScript

function setLogLevel(level: LogLevel)

Parameters

level

LogLevel

log level in configuration

setLogger(Logger)

Note

This API is in Beta and provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

Set custom logger. Use the output functions if it's set. Priority is higher than setLogFunction.

Example

TypeScript

setLogger({
  verbose: console.debug,
  info: console.info,
  warn: console.warn,
  error: console.error,
});

TypeScript

function setLogger(logger?: Logger)

Parameters

logger

Logger

custom logger. If it's undefined, custom logger will be cleared.