npm - @microsoft/teamsfx-core - Versions diffs - 1.7.0 → 1.7.1-alpha.8d048e1f1.0 - Mend

@microsoft/teamsfx-core 1.7.0 → 1.7.1-alpha.8d048e1f1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (226) hide show

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

@@ -0,0 +1,63 @@
+## How to enable SSO in TeamsFx Bot projects
+This doc will show you how to add Single Sign On 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}.*
+### Step 1: Enable Single Sign On with TeamsFx commands
+You can follow the following steps to add SSO feature to your TeamsFx projects.
+- From Visual Studio Code: open the command palette and select: `Teams: Add SSO`.
+- From TeamsFx CLI: run command `teamsfx add sso` in your project directory.
+What TeamsFx will do when trigger this command:
+1. Create Azure AD app template under `template\appPackage\aad.template.json`
+1. Add `webApplicationInfo` object in Teams App manifest
+1. Create `README.md` and sample code under `auth/bot/`
+### Step 2: Update your source code
+There are two folders under `auth/bot`: `public` and `sso`.
+1. In `public`, there are two html files which is used for authentication. You can simply copy the folder and place it under `bot/src`. Note that you need to modify `bot/src/index` file to add routing to these pages.
+1. In `sso`, there are three files. You can simply copy the folder and place it under `bot/src`.
+    - `showUserInfo`: This file implement a function to get user info with SSO token. You can follow this method and create your own method that requires SSO token.
+    - `ssoDialog`: Create a [ComponentDialog](https://docs.microsoft.com/en-us/javascript/api/botbuilder-dialogs/componentdialog?view=botbuilder-ts-latest) that used for Single Sign On.
+    - `teamsSsoBot`: Create a [TeamsActivityHandler](https://docs.microsoft.com/en-us/dotnet/api/microsoft.bot.builder.teams.teamsactivityhandler?view=botbuilder-dotnet-stable) with `ssoDialog` and add `showUserInfo` as a command that can be triggered. You need to register your own command with `addCommand` in this file.
+1. After adding the following files, you need to new a `teamsSsoBot` instance in `bot/src/index` file with:
+    ```
+    const handler = new TeamsSsoBot();
+    server.post("/api/messages", async (req, res) => {
+        await adapter.processActivity(req, res, async (context) => {
+            await handler.run(context);
+        }).catch((err) => {
+            // Error message including "412" means it is waiting for user's consent, which is a normal process of SSO, sholdn't throw this error.
+            if (!err.message.includes("412")) {
+                throw err;
+            }
+        });
+    });
+    ```
+1. As mentioned above, you also need to add routing in `bot/src/index` file as below:
+    ```
+    server.get(
+        "/auth-*.html",
+        restify.plugins.serveStatic({
+            directory: path.join(__dirname, "public"),
+        })
+    );
+    ```
+### Step 3: Provision Azure AD app and deploy latest code
+After running `add sso` command and updating source code, you need to run `Provision` + `Deploy` or `Local Debug` again to provision an Azure AD app for Single Sign On. After the above steps, Single Sign On is successfully added in your Teams App.

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -0,0 +1,19 @@
+import { createMicrosoftGraphClient, TeamsFx } from "@microsoft/teamsfx";
+export 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;
+}

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

@@ -0,0 +1,173 @@
+import {
+  ComponentDialog,
+  WaterfallDialog,
+  Dialog,
+  DialogTurnResult,
+  DialogSet,
+  DialogTurnStatus,
+} from "botbuilder-dialogs";
+import { ActivityTypes, tokenExchangeOperationName, TurnContext } from "botbuilder";
+import { TeamsBotSsoPrompt, TeamsFx } from "@microsoft/teamsfx";
+import "isomorphic-fetch";
+const DIALOG_NAME = "SSODialog";
+const TEAMS_SSO_PROMPT_ID = "TeamsFxSsoPrompt";
+const COMMAND_ROUTE_DIALOG = "CommandRouteDialog";
+export class SsoDialog extends ComponentDialog {
+  constructor(dedupStorage, requiredScopes) {
+    super(DIALOG_NAME);
+    this.initialDialogId = COMMAND_ROUTE_DIALOG;
+    this.dedupStorage = dedupStorage;
+    this.dedupStorageKeys = [];
+    this.requiredScopes = requiredScopes;
+    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) {
+      let 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;
+  }
+}

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

@@ -0,0 +1,55 @@
+import { ConversationState, MemoryStorage, TeamsActivityHandler, UserState } from "botbuilder";
+import { showUserInfo } from "./showUserInfo";
+import { SsoDialog } from "./ssoDialog";
+export 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);
+  }
+}

package/templates/plugins/resource/aad/auth/bot/ts/public/auth-end.html ADDED Viewed

@@ -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>