@microsoft/teamsfx 0.5.2-alpha.313131ea.0 → 0.6.0-rc.0

package/README.md

@@ -1,6 +1,6 @@
 # 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".
+TeamsFx aims to reduce the developer tasks of leveraging Teams SSO and access to cloud resources down to single-line statements with "zero configuration".
 
 Use the library to:
 
@@ -23,7 +23,7 @@ Please check the [README](https://github.com/OfficeDev/TeamsFx/blob/main/package
 
 - Node.js version 10.x.x or higher
 - A project created by the Teams Toolkit VS Code extension or `teamsfx` CLI tool.
-- If your project has installed `botbuilder` related [packages](https://github.com/Microsoft/botbuilder-js#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](https://github.com/BotBuilderCommunity/botbuilder-community-js/issues/57#issuecomment-508538548))
+- If your project has installed `botbuilder` related [packages](https://github.com/Microsoft/botbuilder-js#packages) as dependencies, ensure they are of the same version and the version `>= 4.15.0`. ([Issue - all of the BOTBUILDER packages should be the same version](https://github.com/BotBuilderCommunity/botbuilder-community-js/issues/57#issuecomment-508538548))
 
 ### Install the `@microsoft/teamsfx` package
 
@@ -33,80 +33,114 @@ Install the TeamsFx SDK for TypeScript/JavaScript with `npm`:
 npm install @microsoft/teamsfx
 ```
 
-### Create and authenticate a `MicrosoftGraphClient`
+### Scenarios
 
-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.
+TeamsFx SDK is built to be used in browser and NodeJS environment. Common scenarios include:
+- Teams tab application
+- Azure Function
+- Teams bot
 
-Please note that you need to load configuration before using any credentials.
+### Create and authenticate a service like `MicrosoftGraphClient`
 
-- In browser environment, you need to explicitly pass in the config parameters. The scaffolded React project has provided environment variables to use.
+To create a graph client object to access the Microsoft Graph API, you will need the credential to do authentication. The SDK provides APIs to configure for developers. Please choose the proper identity type and follow below steps:
 
-```ts
-loadConfiguration({
-  authentication: {
-    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
-    clientId: process.env.REACT_APP_CLIENT_ID,
-  },
-});
-```
+#### Invoke Graph API on behalf of Teams User (User Identity)
 
-- In NodeJS environment like Azure Function, you can just call `loadConfiguration`. It will load from environment variables by default.
+Use the snippet below:
 
 ```ts
-loadConfiguration();
+// Equivalent to:
+// const teamsfx = new TeamsFx(IdentityType.User, {
+//   initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
+//   clientId: process.env.REACT_APP_CLIENT_ID,
+// }
+const teamsfx = new TeamsFx();
+const graphClient = createMicrosoftGraphClient(teamsfx, ["User.Read"]); // Initializes MS Graph SDK using our MsGraphAuthProvider
+const profile = await graphClient.api("/me").get(); // Get the profile of current user
 ```
 
-#### Using Teams App User Credential
+#### Invoke Graph API without user (Application Identity)
 
+It doesn't require the interaction with Teams user. You can call Microsoft Graph as application identity.
 Use the snippet below:
 
-**Note:** You can only use this credential class in browser application like Teams Tab App.
-
 ```ts
-loadConfiguration({
-  authentication: {
-    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
-    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();
+// Equivalent to:
+// const teamsfx = new TeamsFx(IdentityType.App, {
+//   initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
+//   clientId: process.env.REACT_APP_CLIENT_ID,
+// });
+const teamsfx = new TeamsFx(IdentityType.App);
+const graphClient = createMicrosoftGraphClient(teamsfx);
+const profile = await graphClient.api("/users/{object_id_of_another_people}").get(); // Get the profile of certain user
 ```
 
-#### Using Microsoft 365 Tenant Credential
+## Core Concepts & Code Structure
 
-It doesn't require the interaction with Teams App user. You can call Microsoft Graph as application.
-Use the snippet below:
+### TeamsFx class
+`TeamsFx` class instance reads all TeamsFx settings from environment variables by default. You can also set customized configuration values to override the default values. Please check [Override configuration](#override-configuration) for details.
 
-```ts
-loadConfiguration();
-const credential = new M365TenantCredential();
-const graphClient = createMicrosoftGraphClient(credential);
-const profile = await graphClient.api("/users/{object_id_of_another_people}").get();
-```
+When creating a TeamsFx instance, you also need to specify the identity type. There are 2 identity types:
 
-## Core Concepts & Code Structure
+#### User Identity
+Using `new TeamsFx(IdentityType.User)` means the application will be authenticated as current Teams user. This one is the default choice. You need to call `TeamsFx:setSsoToken()` when you use user identity in NodeJS environment(without browser).
+
+You can use `TeamsFx:getUserInfo()` to get user's basic information.
+`TeamsFx:login()` is used to let user perform consent process if you want to use SSO to get access token for certain OAuth scopes.
+
+#### Application Identity
+Using `new TeamsFx(IdentityType.App)` means the application will be authenticated as an application. The permission usually need administrator's approval.
+
+`TeamsFx:getCredential()` provides credential instances automatically corresponding to identity type:
+- User Identity: It means that you can access resources on behalf of current Teams user.
+- App Identity: It means that you are acting as a managed app identity which usually need admin consent for resources.
 
 ### Credential
 
+//Developers should choose identity type when initializing TeamsFx. SDK provides 2 types: User and App.
+After developer has specified the identity type when initializing TeamsFx, SDK uses different kinds of credential class to represent the identity and get access token by corresponding auth flow.
+
 There are 3 credential classes that are used to help simplifying authentication. They are located under [credential](src/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.
+Credential classes implements `TokenCredential` interface that is broadly used in Azure library APIs. They are designed to provide access token for specific scopes. Other APIs that relies on credential call `TeamsFx:getCredential()` to get an instance of `TokenCredential`.
 
-`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.
+Here's the corresponding scenarios that each credential class targets.
 
-### Bot
+#### User Identity in browser environment
+`TeamsUserCredential` represents Teams current user's identity. Using this credential will request user consent at the first time. It leverages the Teams SSO and On-Behalf-Of flow to do token exchange. SDK uses this credential when developer choose "User" identity in browser environment.
+
+Required configuration: initiateLoginEndpoint, clientId.
+
+#### User Identity in NodeJS environment
+`OnBehalfOfUserCredential` uses On-Behalf-Of flow and need Teams ssoToken. It's designed to be used in Azure Function or Bot scenarios. SDK uses this credential when developer choose "User" identity in NodeJS environment.
+
+Required configuration: authorityHost, tenantId, clientId, clientSecret / certificateContent.
+
+#### Application Identity in NodeJS environment
+`AppCredential` represents the application identity. It is usually used when user is not involved like time-triggered automation job. SDK uses this credential when developer choose "App" identity in NodeJS environment.
+
+Required configuration: tenantId, clientId, clientSecret / certificateContent.
+
+### Bot SSO
 
 Bot related classes are stored under [bot](src/bot) folder.
 
-`TeamsBotSsoPrompt` has a good integration with Bot framework. It simplifies the authentication process when you develops bot application.
+`TeamsBotSsoPrompt` has a good integration with Bot framework. It simplifies the authentication process when you develops bot application and want to leverage the Bot SSO.
+
+Required configuration: initiateLoginEndpoint, tenantId, clientId, applicationIdUri.
 
 ### Helper Function
 
-TeamsFx SDK provides helper functions to ease the configuration for third-party libraries. They are located under [core](src/core) folder.
+TeamsFx SDK provides several helper functions to ease the configuration for third-party libraries. They are located under [core](src/core) folder.
+
+#### Microsoft Graph Service
+`createMicrosoftGraphClient` and `MsGraphAuthProvider` help to create authenticated Graph instance.
+
+#### SQL
+`getTediousConnectionConfig` returns a tedious connection config.
+
+Required configuration:
+- sqlServerEndpoint, sqlUsername, sqlPassword if you want to use user identity
+- sqlServerEndpoint, sqlIdentityId if you want to use MSI identity
 
 ### Error Handling
 
@@ -116,8 +150,8 @@ For example, to filter out specific error, you could use the following check:
 
 ```ts
 try {
-  const credential = new TeamsUserCredential();
-  await credential.login("User.Read");
+  const teamsfx = new TeamsFx();
+  await teamsfx.login("User.Read");
 } catch (err: unknown) {
   if (err instanceof ErrorWithCode && err.code !== ErrorCode.ConsentFailed) {
     throw err;
@@ -132,8 +166,8 @@ And if credential instance is used in other library like Microsoft Graph, it's p
 
 ```ts
 try {
-  const credential = new TeamsUserCredential();
-  const graphClient = createMicrosoftGraphClient(credential, ["User.Read"]); // Initializes MS Graph SDK using our MsGraphAuthProvider
+  const teamsfx = new TeamsFx();
+  const graphClient = createMicrosoftGraphClient(teamsfx, ["User.Read"]); // Initializes MS Graph SDK using our MsGraphAuthProvider
   const profile = await graphClient.api("/me").get();
 } catch (err: unknown) {
   // ErrorWithCode is handled by Graph client
@@ -157,17 +191,11 @@ The following sections provide several code snippets covering some of the most c
 
 ### Use Graph API in tab app
 
-Use `TeamsUserCredential` and `createMicrosoftGraphClient`.
+Use `TeamsFx` and `createMicrosoftGraphClient`.
 
 ```ts
-loadConfiguration({
-  authentication: {
-    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
-    clientId: process.env.REACT_APP_CLIENT_ID,
-  },
-});
-const credential: any = new TeamsUserCredential();
-const graphClient = createMicrosoftGraphClient(credential, ["User.Read"]);
+const teamsfx = new TeamsFx();
+const graphClient = createMicrosoftGraphClient(teamsfx, ["User.Read"]);
 const profile = await graphClient.api("/me").get();
 ```
 
@@ -176,17 +204,11 @@ const profile = await graphClient.api("/me").get();
 Use `axios` library to make HTTP request to Azure Function.
 
 ```ts
-loadConfiguration({
-  authentication: {
-    initiateLoginEndpoint: process.env.REACT_APP_START_LOGIN_PAGE_URL,
-    clientId: process.env.REACT_APP_CLIENT_ID,
-  },
-});
-const credential: any = new TeamsUserCredential();
-const token = credential.getToken(""); // Get SSO token for the user
+const teamsfx = new TeamsFx();
+const token = teamsfx.getCredential().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", {
+const apiEndpoint = teamsfx.getConfig("apiEndpoint");
+const response = await axios.default.get(apiEndpoint + "api/httptrigger1", {
   headers: {
     authorization: "Bearer " + token,
   },
@@ -199,12 +221,17 @@ Use `tedious` library to access SQL and leverage `DefaultTediousConnectionConfig
 Apart from `tedious`, you can also compose connection config of other SQL libraries based on the result of `sqlConnectionConfig.getConfig()`.
 
 ```ts
-loadConfiguration();
-const sqlConnectConfig = new DefaultTediousConnectionConfiguration();
+// Equivalent to:
+// const sqlConnectConfig = new DefaultTediousConnectionConfiguration({
+//    sqlServerEndpoint: process.env.SQL_ENDPOINT,
+//    sqlUsername: process.env.SQL_USER_NAME,
+//    sqlPassword: process.env.SQL_PASSWORD,
+// });
+const teamsfx = new TeamsFx();
 // if there's only one SQL database
-const config = await sqlConnectConfig.getConfig();
+const config = await getTediousConnectionConfig(teamsfx);
 // if there are multiple SQL databases
-const config2 = await sqlConnectionConfig.getConfig("your database name");
+const config2 = await getTediousConnectionConfig(teamsfx, "your database name");
 const connection = new Connection(config);
 connection.on("connect", (error) => {
   if (error) {
@@ -216,14 +243,17 @@ connection.on("connect", (error) => {
 ### Use certificate-based authentication in Azure Function
 
 ```ts
-loadConfiguration({
-  authentication: {
-    clientId: process.env.M365_CLIENT_ID,
-    certificateContent: "The content of a PEM-encoded public/private key certificate",
-    authorityHost: process.env.M365_AUTHORITY_HOST,
-    tenantId: process.env.M365_TENANT_ID,
-  },
+const authConfig = {
+  clientId: process.env.M365_CLIENT_ID,
+  certificateContent: "The content of a PEM-encoded public/private key certificate",
+  authorityHost: process.env.M365_AUTHORITY_HOST,
+  tenantId: process.env.M365_TENANT_ID,
+};
+const teamsfx = new TeamsFx(IdentityType.App);
+teamsfx.setCustomeConfig({
+  certificateContent: "The content of a PEM-encoded public/private key certificate"
 });
+const token = teamsfx.getCredential().getToken();
 ```
 
 ### Use Graph API in Bot application
@@ -239,9 +269,9 @@ const convoState = new ConversationState(new MemoryStorage());
 const dialogState = convoState.createProperty("dialogState");
 const dialogs = new DialogSet(dialogState);
 
-loadConfiguration();
+const teamsfx = new TeamsFx();
 dialogs.add(
-  new TeamsBotSsoPrompt("TeamsBotSsoPrompt", {
+  new TeamsBotSsoPrompt(teamsfx, "TeamsBotSsoPrompt", {
     scopes: ["User.Read"],
   })
 );
@@ -264,7 +294,7 @@ dialogs.add(
 );
 ```
 
-## Troubleshooting
+## Advanced Customization
 
 ### Configure log
 
@@ -309,6 +339,44 @@ setLogFunction((level: LogLevel, message: string) => {
 });
 ```
 
+
+### Override configuration
+You can pass custom config when creating `TeamsFx` instance to override default configuration or set required fields when environment variables are missing.
+
+- If you have created tab project using VS Code toolkit, the following config values will be used from pre-configured environment variables:
+  * authorityHost (REACT_APP_AUTHORITY_HOST)
+  * tenantId (REACT_APP_TENANT_ID)
+  * clientId (REACT_APP_CLIENT_ID)
+  * initiateLoginEndpoint (REACT_APP_START_LOGIN_PAGE_URL)
+  * applicationIdUri (REACT_APP_START_LOGIN_PAGE_URL)
+  * apiEndpoint (REACT_APP_FUNC_ENDPOINT)
+  * apiName (REACT_APP_FUNC_NAME)
+
+- If you have created Azure Function / Bot project using VS Code toolkit, the following config values will be used from pre-configured environment variables:
+  * initiateLoginEndpoint (INITIATE_LOGIN_ENDPOINT)
+  * authorityHost (M365_AUTHORITY_HOST)
+  * tenantId (M365_TENANT_ID)
+  * clientId (M365_CLIENT_ID)
+  * clientSecret (M365_CLIENT_SECRET)
+  * applicationIdUri (M365_APPLICATION_ID_URI)
+  * apiEndpoint (API_ENDPOINT)
+  * sqlServerEndpoint (SQL_ENDPOINT)
+  * sqlUsername (SQL_USER_NAME)
+  * sqlPassword (SQL_PASSWORD)
+  * sqlDatabaseName (SQL_DATABASE_NAME)
+  * sqlIdentityId (IDENTITY_ID)
+
+## How to fix the breaking change if upgraded from previous SDK version
+
+If you are using the version of SDK that has `loadConfiguration()`, you can follow these steps to upgrade to the latest SDK version.
+1. Remove `loadConfiguration()` and pass customized settings using `new TeamsFx(IdentityType.User, { ...customConfig })`.
+2. Replace `new TeamsUserCredential()` with `new TeamsFx()`.
+3. Replace `new M365TenantCredential()` with `new TeamsFx(IdentityType.App)`.
+4. Replace `new OnBehalfOfUserCredential(ssoToken)` with `new TeamsFx().setSsoToken(ssoToken)`.
+5. Pass the instance of `TeamsFx` to helper functions to replace credential instance.
+
+Also see [TeamsFx class](#teamsfx-class) for furthur description.
+
 ## Next steps
 
 Please take a look at the [Samples](https://github.com/OfficeDev/TeamsFx-Samples) project for detailed examples on how to use this library.