@microsoft/teamsfx-core 1.7.0 → 1.7.1-alpha.42a29d71b.0

package/templates/core/README.md

@@ -0,0 +1,46 @@
+# Embed Existing Web App
+
+Embed existing web app is to bring your own static webpages and embed in Microsoft Teams.
+
+## Get Started
+
+Before run this app locally, make sure you have prepared the following prerequisites:
+* An [M365 account for development](https://docs.microsoft.com/microsoftteams/platform/toolkit/accounts).
+
+Also, make sure your own static webpages meets the [prerequisites](https://aka.ms/teamsfx-existing-tab#prerequisites) and launches locally.
+
+Then, you can quickly start local preview via the environment tree view in Teams Toolkit, refer [Preview your Teams app](https://aka.ms/teamsfx-existing-tab#preview-your-teams-app) for more information.
+
+## Develop
+
+The following table lists all the scaffolded folder and files by Teams Toolkit:
+
+| File name | Contents |
+|- | -|
+|`.fx/configs/config.local.json`| Configuration file for local environment |
+|`.fx/configs/config.dev.json`| Configuration file for dev environment |
+|`.fx/configs/projectSettings.json`| Global project settings, which apply to all environments |
+|`templates/appPackage/manifest.template.json`|Teams app manifest template|
+|`templates/appPackage/resources`|Teams app's icon referenced by manifest template|
+|`.gitignore` | The git ignore file to exclude local files from TeamsFx project |
+
+### Edit Teams App manifest
+
+You can find the Teams app manifest in `templates/appPackage/manifest.template.json`.
+
+The file contains template arguments with `{...}` statements which will be replaced at build time. You may add any extra properties or permissions you require to this file. See the [schema reference](https://docs.microsoft.com/microsoftteams/platform/resources/schema/manifest-schema) for more information.
+
+## Deployment
+
+Teams Toolkit can help provision new Teams app per different environments.
+
+After provisioned, you can preview your app via the environment tree view in Teams Toolkit, refer [Preview your Teams app](https://aka.ms/teamsfx-existing-tab#preview-your-teams-app) for more information.
+
+After finish development and to distribute your app to others, you can [Publish Teams apps using Teams Toolkit](https://docs.microsoft.com/microsoftteams/platform/toolkit/publish).
+
+## Reference
+
+* [Embed Existing Web App with Teams Toolkit](https://aka.ms/teamsfx-existing-tab)
+* [Teams Toolkit and Step-by-step Documentations](https://docs.microsoft.com/microsoftteams/platform/toolkit/teams-toolkit-fundamentals)
+* [Teams Toolkit CLI](https://docs.microsoft.com/microsoftteams/platform/toolkit/teamsfx-cli)
+* [Teams Toolkit Samples](https://github.com/OfficeDev/TeamsFx-Samples)

package/templates/plugins/resource/aad/auth/bot/README.md

@@ -0,0 +1,17 @@
+## How to enable SSO in TeamsFx Bot projects
+
+This doc will show you how to add Single sign-on (SSO) feature to TeamsFx Bot projects. Note that this article is only for Teams Toolkit Visual Studio Code Extension version after x.x.x or TeamsFx CLI version after x.x.x.
+
+*Note: This article is only for bot hosted on Azure App Service. Bot that hosted on Azure Function is not supported now.*
+
+*Note: This article is only for TeamsFx projects by Javascript and Typescript. For Dotnet, please refer to ${help link}.*
+
+For more detail about SSO, please refer to the [wiki](https://aka.ms/teamsfx-add-sso-readme#overview).
+
+### What we have done in 'Add SSO' command
+
+By triggering `Add SSO` command, we will help you to setup your project to enable SSO and create `auth/bot` folder with some code snippet. For detail, please refer to the [wiki](https://aka.ms/teamsfx-add-sso-readme#what-we-will-do-in-add-sso-command).
+
+### What you need to do after triggering 'Add SSO' command
+
+Please follow the [wiki](https://aka.ms/teamsfx-add-sso-readme#what-you-need-to-do-after-triggering-add-sso-command) to update your source code, provision Azure AD app and deploy latest code.

package/templates/plugins/resource/aad/auth/bot/js/public/auth-end.html

@@ -0,0 +1,65 @@
+<html>
+  <head>
+    <title>Login End Page</title>
+    <meta charset="utf-8" />
+  </head>
+
+  <body>
+    <script
+      src="https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js"
+      integrity="sha384-mhp2E+BLMiZLe7rDIzj19WjgXJeI32NkPvrvvZBrMi5IvWup/1NUfS5xuYN5S3VT"
+      crossorigin="anonymous"
+    ></script>
+    <div id="divError"></div>
+    <script type="text/javascript">
+      microsoftTeams.initialize();
+      let hashParams = getHashParameters();
+
+      if (hashParams["error"]) {
+        // Authentication failed
+        handleAuthError(hashParams["error"], hashParams);
+      } else if (hashParams["code"]) {
+        // Get the stored state parameter and compare with incoming state
+        let expectedState = localStorage.getItem("state");
+        if (expectedState !== hashParams["state"]) {
+          // State does not match, report error
+          handleAuthError("StateDoesNotMatch", hashParams);
+        } else {
+          microsoftTeams.authentication.notifySuccess();
+        }
+      } else {
+        // Unexpected condition: hash does not contain error or access_token parameter
+        handleAuthError("UnexpectedFailure", hashParams);
+      }
+
+      // Parse hash parameters into key-value pairs
+      function getHashParameters() {
+        let hashParams = {};
+        location.hash
+          .substr(1)
+          .split("&")
+          .forEach(function (item) {
+            let s = item.split("="),
+              k = s[0],
+              v = s[1] && decodeURIComponent(s[1]);
+            hashParams[k] = v;
+          });
+        return hashParams;
+      }
+
+      // Show error information
+      function handleAuthError(errorType, errorMessage) {
+        const err = JSON.stringify({
+          error: errorType,
+          message: JSON.stringify(errorMessage),
+        });
+        let para = document.createElement("p");
+        let node = document.createTextNode(err);
+        para.appendChild(node);
+
+        let element = document.getElementById("divError");
+        element.appendChild(para);
+      }
+    </script>
+  </body>
+</html>

package/templates/plugins/resource/aad/auth/bot/js/public/auth-start.html

@@ -0,0 +1,177 @@
+<!--This file is used during the Teams Bot authentication flow to assist with retrieval of the access token.-->
+<!--If you're not familiar with this, do not alter or remove this file from your project.-->
+<html>
+  <head>
+    <title>Login Start Page</title>
+    <meta charset="utf-8" />
+  </head>
+
+  <body>
+    <script type="text/javascript">
+      popUpSignInWindow();
+
+      async function popUpSignInWindow() {
+        // Generate random state string and store it, so we can verify it in the callback
+        let state = _guid();
+        localStorage.setItem("state", state);
+        localStorage.removeItem("codeVerifier");
+        var currentURL = new URL(window.location);
+        var clientId = currentURL.searchParams.get("clientId");
+        var tenantId = currentURL.searchParams.get("tenantId");
+        var loginHint = currentURL.searchParams.get("loginHint");
+        if (!loginHint) {
+          loginHint = "";
+        }
+
+        var scope = currentURL.searchParams.get("scope");
+
+        var originalCode = _guid();
+        var codeChallenge = await pkceChallengeFromVerifier(originalCode);
+
+        localStorage.setItem("codeVerifier", originalCode);
+        let queryParams = {
+          client_id: clientId,
+          response_type: "code",
+          response_mode: "fragment",
+          scope: scope,
+          redirect_uri: window.location.origin + "/auth-end.html",
+          nonce: _guid(),
+          login_hint: loginHint,
+          state: state,
+          code_challenge: codeChallenge,
+          code_challenge_method: "S256",
+        };
+
+        let authorizeEndpoint = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/authorize?${toQueryString(
+          queryParams
+        )}`;
+        window.location.assign(authorizeEndpoint);
+      }
+
+      // Build query string from map of query parameter
+      function toQueryString(queryParams) {
+        let encodedQueryParams = [];
+        for (let key in queryParams) {
+          encodedQueryParams.push(key + "=" + encodeURIComponent(queryParams[key]));
+        }
+        return encodedQueryParams.join("&");
+      }
+
+      // Converts decimal to hex equivalent
+      // (From ADAL.js: https://github.com/AzureAD/azure-activedirectory-library-for-js/blob/dev/lib/adal.js)
+      function _decimalToHex(number) {
+        var hex = number.toString(16);
+        while (hex.length < 2) {
+          hex = "0" + hex;
+        }
+        return hex;
+      }
+
+      // Generates RFC4122 version 4 guid (128 bits)
+      // (From ADAL.js: https://github.com/AzureAD/azure-activedirectory-library-for-js/blob/dev/lib/adal.js)
+      function _guid() {
+        // RFC4122: The version 4 UUID is meant for generating UUIDs from truly-random or
+        // pseudo-random numbers.
+        // The algorithm is as follows:
+        //     Set the two most significant bits (bits 6 and 7) of the
+        //        clock_seq_hi_and_reserved to zero and one, respectively.
+        //     Set the four most significant bits (bits 12 through 15) of the
+        //        time_hi_and_version field to the 4-bit version number from
+        //        Section 4.1.3. Version4
+        //     Set all the other bits to randomly (or pseudo-randomly) chosen
+        //     values.
+        // UUID                   = time-low "-" time-mid "-"time-high-and-version "-"clock-seq-reserved and low(2hexOctet)"-" node
+        // time-low               = 4hexOctet
+        // time-mid               = 2hexOctet
+        // time-high-and-version  = 2hexOctet
+        // clock-seq-and-reserved = hexOctet:
+        // clock-seq-low          = hexOctet
+        // node                   = 6hexOctet
+        // Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+        // y could be 1000, 1001, 1010, 1011 since most significant two bits needs to be 10
+        // y values are 8, 9, A, B
+        var cryptoObj = window.crypto || window.msCrypto; // for IE 11
+        if (cryptoObj && cryptoObj.getRandomValues) {
+          var buffer = new Uint8Array(16);
+          cryptoObj.getRandomValues(buffer);
+          //buffer[6] and buffer[7] represents the time_hi_and_version field. We will set the four most significant bits (4 through 7) of buffer[6] to represent decimal number 4 (UUID version number).
+          buffer[6] |= 0x40; //buffer[6] | 01000000 will set the 6 bit to 1.
+          buffer[6] &= 0x4f; //buffer[6] & 01001111 will set the 4, 5, and 7 bit to 0 such that bits 4-7 == 0100 = "4".
+          //buffer[8] represents the clock_seq_hi_and_reserved field. We will set the two most significant bits (6 and 7) of the clock_seq_hi_and_reserved to zero and one, respectively.
+          buffer[8] |= 0x80; //buffer[8] | 10000000 will set the 7 bit to 1.
+          buffer[8] &= 0xbf; //buffer[8] & 10111111 will set the 6 bit to 0.
+          return (
+            _decimalToHex(buffer[0]) +
+            _decimalToHex(buffer[1]) +
+            _decimalToHex(buffer[2]) +
+            _decimalToHex(buffer[3]) +
+            "-" +
+            _decimalToHex(buffer[4]) +
+            _decimalToHex(buffer[5]) +
+            "-" +
+            _decimalToHex(buffer[6]) +
+            _decimalToHex(buffer[7]) +
+            "-" +
+            _decimalToHex(buffer[8]) +
+            _decimalToHex(buffer[9]) +
+            "-" +
+            _decimalToHex(buffer[10]) +
+            _decimalToHex(buffer[11]) +
+            _decimalToHex(buffer[12]) +
+            _decimalToHex(buffer[13]) +
+            _decimalToHex(buffer[14]) +
+            _decimalToHex(buffer[15])
+          );
+        } else {
+          var guidHolder = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx";
+          var hex = "0123456789abcdef";
+          var r = 0;
+          var guidResponse = "";
+          for (var i = 0; i < 36; i++) {
+            if (guidHolder[i] !== "-" && guidHolder[i] !== "4") {
+              // each x and y needs to be random
+              r = (Math.random() * 16) | 0;
+            }
+            if (guidHolder[i] === "x") {
+              guidResponse += hex[r];
+            } else if (guidHolder[i] === "y") {
+              // clock-seq-and-reserved first hex is filtered and remaining hex values are random
+              r &= 0x3; // bit and with 0011 to set pos 2 to zero ?0??
+              r |= 0x8; // set pos 3 to 1 as 1???
+              guidResponse += hex[r];
+            } else {
+              guidResponse += guidHolder[i];
+            }
+          }
+          return guidResponse;
+        }
+      }
+
+      // Calculate the SHA256 hash of the input text.
+      // Returns a promise that resolves to an ArrayBuffer
+      function sha256(plain) {
+        const encoder = new TextEncoder();
+        const data = encoder.encode(plain);
+        return window.crypto.subtle.digest("SHA-256", data);
+      }
+
+      // Base64-urlencodes the input string
+      function base64urlencode(str) {
+        // Convert the ArrayBuffer to string using Uint8 array to convert to what btoa accepts.
+        // btoa accepts chars only within ascii 0-255 and base64 encodes them.
+        // Then convert the base64 encoded to base64url encoded
+        //   (replace + with -, replace / with _, trim trailing =)
+        return btoa(String.fromCharCode.apply(null, new Uint8Array(str)))
+          .replace(/\+/g, "-")
+          .replace(/\//g, "_")
+          .replace(/=+$/, "");
+      }
+
+      // Return the base64-urlencoded sha256 hash for the PKCE challenge
+      async function pkceChallengeFromVerifier(v) {
+        hashed = await sha256(v);
+        return base64urlencode(hashed);
+      }
+    </script>
+  </body>
+</html>

package/templates/plugins/resource/aad/auth/bot/js/sso/showUserInfo.js

@@ -0,0 +1,23 @@
+const { createMicrosoftGraphClient, TeamsFx } = require("@microsoft/teamsfx");
+
+async function showUserInfo(context, ssoToken) {
+  await context.sendActivity("Retrieving user information from Microsoft Graph ...");
+  const teamsfx = new TeamsFx().setSsoToken(ssoToken);
+  const graphClient = createMicrosoftGraphClient(teamsfx, ["User.Read"]);
+  const me = await graphClient.api("/me").get();
+  if (me) {
+    await context.sendActivity(
+      `You're logged in as ${me.displayName} (${me.userPrincipalName})${
+        me.jobTitle ? `; your job title is: ${me.jobTitle}` : ""
+      }.`
+    );
+  } else {
+    await context.sendActivity("Could not retrieve profile information from Microsoft Graph.");
+  }
+
+  return;
+}
+
+module.exports = {
+  showUserInfo,
+};

package/templates/plugins/resource/aad/auth/bot/js/sso/ssoDialog.js

@@ -0,0 +1,176 @@
+const {
+  ComponentDialog,
+  WaterfallDialog,
+  Dialog,
+  DialogTurnResult,
+  DialogSet,
+  DialogTurnStatus,
+} = require("botbuilder-dialogs");
+const { ActivityTypes, tokenExchangeOperationName, TurnContext } = require("botbuilder");
+const { TeamsBotSsoPrompt, TeamsFx } = require("@microsoft/teamsfx");
+require("isomorphic-fetch");
+
+const DIALOG_NAME = "SSODialog";
+const TEAMS_SSO_PROMPT_ID = "TeamsFxSsoPrompt";
+const COMMAND_ROUTE_DIALOG = "CommandRouteDialog";
+
+class SsoDialog extends ComponentDialog {
+  constructor(dedupStorage, requiredScopes) {
+    super(DIALOG_NAME);
+
+    this.initialDialogId = COMMAND_ROUTE_DIALOG;
+
+    this.dedupStorage = dedupStorage;
+    this.dedupStorageKeys = [];
+    this.requiredScopes = requiredScopes;
+    this.commandMapping = new Map();
+
+    const teamsFx = new TeamsFx();
+    const ssoDialog = new TeamsBotSsoPrompt(teamsFx, TEAMS_SSO_PROMPT_ID, {
+      scopes: this.requiredScopes,
+      endOnInvalidMessage: true,
+    });
+    this.addDialog(ssoDialog);
+
+    const commandRouteDialog = new WaterfallDialog(COMMAND_ROUTE_DIALOG, [
+      this.commandRouteStep.bind(this),
+    ]);
+    this.addDialog(commandRouteDialog);
+  }
+
+  addCommand(commandId, commandText, operation) {
+    const dialog = new WaterfallDialog(commandId, [
+      this.ssoStep.bind(this),
+      this.dedupStep.bind(this),
+      async (stepContext) => {
+        const tokenResponse = stepContext.result;
+        const context = stepContext.context;
+        if (tokenResponse) {
+          await operation(context, tokenResponse.ssoToken);
+        } else {
+          await context.sendActivity("Failed to retrieve user token from conversation context.");
+        }
+        return await stepContext.endDialog();
+      },
+    ]);
+
+    if (this.commandMapping.has(commandId)) {
+      throw new Error(`Cannot add command. There is already a command with same id ${commandId}`);
+    }
+    this.commandMapping.set(commandId, commandText);
+    this.addDialog(dialog);
+  }
+
+  /**
+   * The run method handles the incoming activity (in the form of a DialogContext) and passes it through the dialog system.
+   * If no dialog is active, it will start the default dialog.
+   * @param {*} dialogContext
+   */
+  async run(context, accessor) {
+    const dialogSet = new DialogSet(accessor);
+    dialogSet.add(this);
+
+    const dialogContext = await dialogSet.createContext(context);
+    const results = await dialogContext.continueDialog();
+    if (results && results.status === DialogTurnStatus.empty) {
+      await dialogContext.beginDialog(this.id);
+    }
+  }
+
+  async commandRouteStep(stepContext) {
+    const turnContext = stepContext.context;
+
+    // remove the mention of this bot
+    let text = TurnContext.removeRecipientMention(turnContext.activity);
+    if (text) {
+      // remove the line break
+      text = text.toLowerCase().replace(/\n|\r/g, "").trim();
+    }
+
+    const commandId = this.matchCommands(text);
+    if (commandId) {
+      return await stepContext.beginDialog(commandId);
+    }
+    return await stepContext.endDialog();
+  }
+
+  async ssoStep(stepContext) {
+    return await stepContext.beginDialog(TEAMS_SSO_PROMPT_ID);
+  }
+
+  async dedupStep(stepContext) {
+    const tokenResponse = stepContext.result;
+    // Only dedup after ssoStep to make sure that all Teams client would receive the login request
+    if (tokenResponse && (await this.shouldDedup(stepContext.context))) {
+      return Dialog.EndOfTurn;
+    }
+    return await stepContext.next(tokenResponse);
+  }
+
+  async onEndDialog(context) {
+    const conversationId = context.activity.conversation.id;
+    const currentDedupKeys = this.dedupStorageKeys.filter((key) => key.indexOf(conversationId) > 0);
+    await this.dedupStorage.delete(currentDedupKeys);
+    this.dedupStorageKeys = this.dedupStorageKeys.filter((key) => key.indexOf(conversationId) < 0);
+  }
+
+  // If a user is signed into multiple Teams clients, the Bot might receive a "signin/tokenExchange" from each client.
+  // Each token exchange request for a specific user login will have an identical activity.value.Id.
+  // Only one of these token exchange requests should be processed by the bot. For a distributed bot in production,
+  // this requires a distributed storage to ensure only one token exchange is processed.
+  async shouldDedup(context) {
+    const storeItem = {
+      eTag: context.activity.value.id,
+    };
+
+    const key = this.getStorageKey(context);
+    const storeItems = { [key]: storeItem };
+
+    try {
+      await this.dedupStorage.write(storeItems);
+      this.dedupStorageKeys.push(key);
+    } catch (err) {
+      if (err instanceof Error && err.message.indexOf("eTag conflict")) {
+        return true;
+      }
+      throw err;
+    }
+    return false;
+  }
+
+  getStorageKey(context) {
+    if (!context || !context.activity || !context.activity.conversation) {
+      throw new Error("Invalid context, can not get storage key!");
+    }
+    const activity = context.activity;
+    const channelId = activity.channelId;
+    const conversationId = activity.conversation.id;
+    if (activity.type !== ActivityTypes.Invoke || activity.name !== tokenExchangeOperationName) {
+      throw new Error("TokenExchangeState can only be used with Invokes of signin/tokenExchange.");
+    }
+    const value = activity.value;
+    if (!value || !value.id) {
+      throw new Error("Invalid signin/tokenExchange. Missing activity.value.id.");
+    }
+    return `${channelId}/${conversationId}/${value.id}`;
+  }
+
+  matchCommands(text) {
+    for (const command of this.commandMapping) {
+      const pattern = command[1];
+      let matchResult;
+      if (typeof pattern == "string") {
+        matchResult = text === pattern;
+      } else {
+        matchResult = pattern.exec(text);
+      }
+      if (matchResult) {
+        return command[0]; // Return the command id
+      }
+    }
+
+    return undefined;
+  }
+}
+
+exports.SsoDialog = SsoDialog;

package/templates/plugins/resource/aad/auth/bot/js/sso/teamsSsoBot.js

@@ -0,0 +1,57 @@
+const { ConversationState, MemoryStorage, TeamsActivityHandler, UserState } = require("botbuilder");
+const { showUserInfo } = require("./showUserInfo");
+const { SsoDialog } = require("./ssoDialog");
+
+class TeamsSsoBot extends TeamsActivityHandler {
+  constructor() {
+    super();
+
+    // Define the state store for your bot.
+    // See https://aka.ms/about-bot-state to learn more about using MemoryStorage.
+    // A bot requires a state storage system to persist the dialog and user state between messages.
+    const memoryStorage = new MemoryStorage();
+
+    // Create conversation and user state with in-memory storage provider.
+    this.conversationState = new ConversationState(memoryStorage);
+    this.userState = new UserState(memoryStorage);
+    this.dialog = new SsoDialog(new MemoryStorage(), ["User.Read"]);
+    this.dialogState = this.conversationState.createProperty("DialogState");
+
+    // Add commands that requires user authentication
+    this.dialog.addCommand("ShowUserProfile", "show", showUserInfo);
+    // call the `addCommand` function to add more customized commands
+
+    this.onMessage(async (context, next) => {
+      console.log("Running with Message Activity.");
+
+      // Run the Dialog with the new message Activity.
+      await this.dialog.run(context, this.dialogState);
+
+      // By calling next() you ensure that the next BotHandler is run.
+      await next();
+    });
+  }
+
+  async run(context) {
+    await super.run(context);
+
+    // Save any state changes. The load happened during the execution of the Dialog.
+    await this.conversationState.saveChanges(context, false);
+    await this.userState.saveChanges(context, false);
+  }
+
+  async handleTeamsSigninVerifyState(context, query) {
+    console.log("Running dialog with signin/verifystate from an Invoke Activity.");
+    await this.dialog.run(context, this.dialogState);
+  }
+
+  async handleTeamsSigninTokenExchange(context, query) {
+    await this.dialog.run(context, this.dialogState);
+  }
+
+  async onSignInInvoke(context) {
+    await this.dialog.run(context, this.dialogState);
+  }
+}
+
+exports.TeamsSsoBot = TeamsSsoBot;