From 83647a3251bd0ec1cbdb16123334f43b38358ba9 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Wed, 9 Oct 2024 21:44:24 +0530 Subject: [PATCH 01/25] [Doc Issue][Develop single sign on experience in Teams][4030650] --- ...elop-single-sign-on-experience-in-Teams.md | 468 ++++++++++++++++++ 1 file changed, 468 insertions(+) create mode 100644 msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md new file mode 100644 index 00000000000..e7b4a85e553 --- /dev/null +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -0,0 +1,468 @@ +--- +title: Develop single sign-on experience in Teams +author: surbhigupta +description: Learn to how to develop single sign-on experience in Teams. +ms.topic: how-to-guides +ms.localizationpriority: medium +--- + +# Enable single sign-on for tab app + +Microsoft Teams allows an app to acquire the token of the signed-in Teams user. This token can be used to access Microsoft Graph and other APIs. The Teams Toolkit simplifies this process by encapsulating some of the Microsoft Entra flows and integrations within straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams application. + +## Key Configurations + +To enable SSO, configure as follows: + +* Microsoft Entra app manifest: Ensure to define URIs, including the URI that identifies the Microsoft Entra authentication app and the redirect URI that returns the token. + +* Teams app manifest: Connect your single sign-on (SSO) app to your Teams app by incorporating the correct configuration. + +* Teams Toolkit configuration and infra files: Ensure the necessary configurations are in place to enable SSO for your Teams app. + +* Add SSO app information in Teams Toolkit configuration files: Ensure the authentication app registers on the backend service and the Teams Toolkit initiates it during the debugging or previewing of the Teams app. + +# [Tab app](#tab/tab-app) + +## Create Microsoft Entra app manifest + +Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more inforamtion, see [manifest](/entra/identity-platform/reference-app-manifest). + +## Update Teams app manifest + +In the `./appPackages/manifest.json` file, add the `webApplicationInfo` section to provide your Microsoft Entra app ID and Microsoft Graph information. + +```json +"webApplicationInfo": { + "id": "${{AAD_APP_CLIENT_ID}}", + "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}" +} +``` + +> [!NOTE] +> You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. + +## Teams Toolkit configuration files + +Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml` Update necessary configurations related to Microsoft Entra into these files. + +* Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra apps used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): + + ```yaml + - uses: aadApp/create + with: + name: "YOUR_AAD_APP_NAME" + generateClientSecret: true + signInAudience: "AzureADMyOrg" + writeToEnvironmentFile: + clientId: AAD_APP_CLIENT_ID + clientSecret: SECRET_AAD_APP_CLIENT_SECRET + objectId: AAD_APP_OBJECT_ID + tenantId: AAD_APP_TENANT_ID + authority: AAD_APP_OAUTH_AUTHORITY + ``` + + > [!NOTE] + > Replace the `name` value with the desired name for your Microsoft Teams app. + +* Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): + + ```yaml + - uses: aadApp/update + with: + manifestPath: "./aad.manifest.json" + outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json" + ``` + + > [!NOTE] + > * Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. + > * In a local setup, position the `aad/update` after the `file/createOrUpdateEnvironmentFile` action. This is because `aad/update` utilizes the output from `file/createOrUpdateEnvironmentFile`. + +* For React project, update `cli/runNpmCommand` under `deploy`: + +* If you're building a tab app using the React framework, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: + + ```yml + env: + REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}} + REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html + ``` + +* If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deploy in `teamsapp.local.yml` and add the following env: + + ```yml + envs: + ... + REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}} + REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html + ``` + +## Update source code + +After implementing the above changes, your environment is prepared. You can now update your code to incorporate SSO into your Teams app. + +#### Vanilla JavaScript + +Use the following code to retrieve the SSO token and user information: + +```javascript +function getSSOToken() { + return new Promise((resolve, reject) => { + microsoftTeams.authentication.getAuthToken() + .then((token) => resolve(token)) + .catch((error) => reject("Error getting token: " + error)); + }); +} + +function getBasicUserInfo() { + getSSOToken().then((ssoToken) => { + const tokenObj = JSON.parse(window.atob(ssoToken.split(".")[1])); + console.log(`username: ${tokenObj.name}`); + console.log(`user email: ${tokenObj.preferred_username}`); + }); +} +``` + +#### React + +For React projects, ensure the following environment variables are set in your deployment process: + +* For javascript project, see [tab javascript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/js) + +* For typescript project, see [tab typescript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts) + +To update your source code, follow these steps: + +1. Move the `auth-start.html` and `auth-end.html` files from the `auth/public` folder to the `public/` folder. These HTML files serve the purpose of handling authentication redirects. + +1. Move `sso` folder under `auth/` to `src/sso/`: + + 1. `InitTeamsFx`: This file executes a function that initializes the TeamsFx SDK. After the SDK initialization, it opens the `GetUserProfile` component. + 1. `GetUserProfile`: This file executes a function, retrieving user information by invoking the Microsoft Graph API. + +1. Import and add `InitTeamsFx` in `Welcome.*`. + +For more information, see [sample.](https://github.com/OfficeDev/teams-toolkit-samples/tree/dev/hello-world-tab-with-backend) + +# [Bot/Messaging extension app](#tab/tab-app) + +## Create Microsoft Entra app manifest + +Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more inforamtion, see [manifest](/entra/identity-platform/reference-app-manifest). + +## Update Teams app manifest + +* In the `./appPackages/manifest.json` file, add the `webApplicationInfo` section to provide your Microsoft Entra app ID and Microsoft Graph information. + + ```json + "webApplicationInfo": { + "id": "${{AAD_APP_CLIENT_ID}}", + "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}" + } + ``` + + > [!NOTE] + > You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. + +* Register command in `commandLists`. + + The `commandLists` includes commands that your bot can suggest to users. If you're using the `teamsFx` bot template, set the following values: + + ```yml + { + "title": "profile", + "description": "Show user profile using Single Sign On feature" + } + ``` + +* The `validDomains` field includes the legitimate domains for websites that the app anticipates loading within the Teams client. If you're using the `teamsFx` bot template, you can set the following values: + +```yml +"validDomains": [ + "${{BOT_DOMAIN}}" +] +``` + +## Teams Toolkit configuration files + +Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml` Update necessary configurations related to Microsoft Entra into these files. + +* Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra apps used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): + + ```yaml + - uses: aadApp/create + with: + name: "YOUR_AAD_APP_NAME" + generateClientSecret: true + signInAudience: "AzureADMyOrg" + writeToEnvironmentFile: + clientId: AAD_APP_CLIENT_ID + clientSecret: SECRET_AAD_APP_CLIENT_SECRET + objectId: AAD_APP_OBJECT_ID + tenantId: AAD_APP_TENANT_ID + authority: AAD_APP_OAUTH_AUTHORITY + authorityHost: AAD_APP_OAUTH_AUTHORITY_HOST + ``` + + > [!NOTE] + > Replace the `name` value with the desired name for your Microsoft Teams app. + +* Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): + + ```yaml + - uses: aadApp/update + with: + manifestPath: "./aad.manifest.json" + outputFilePath: "./build/aad.manifest.${{TEAMSFX_ENV}}.json" + ``` + + > [!NOTE] + > Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. + +* `file/createOrUpdateEnvironmentFile`: Locate the `createOrUpdateEnvironmentFile` action in `teamsapp.local.yml` file and add the following environment variables: + + ```yml + envs: + ... + M365_CLIENT_ID: ${{AAD_APP_CLIENT_ID}} + M365_CLIENT_SECRET: ${{SECRET_AAD_APP_CLIENT_SECRET}} + M365_TENANT_ID: ${{AAD_APP_TENANT_ID}} + INITIATE_LOGIN_ENDPOINT: ${{BOT_ENDPOINT}}/auth-start.html + M365_AUTHORITY_HOST: ${{AAD_APP_OAUTH_AUTHORITY_HOST}} + M365_APPLICATION_ID_URI: api://botid-${{BOT_ID}} + ``` + +## Update Infra + +To set up Microsoft Teams related configurations, update in your remote service. The following example shows the config settings on an Azure Webapp. + +* M365_CLIENT_ID: Microsoft Entra app client id. +* M365_CLIENT_SECRET: Microsoft Entra app client secret. +* M365_TENANT_ID: Tenant id of Microsoft Entra app. +* INITIATE_LOGIN_ENDPOINT: Login start page for authentication. +* M365_AUTHORITY_HOST: Microsoft Entra app oauth authority host. +* M365_APPLICATION_ID_URI: IdentifierUri for Microsoft Entra app. + +To use the `teamsFx` tab or bot template, follow these steps: + +1. Open `infra/azure.parameters.json` file and add the following: + + ```yml + "m365ClientId": { + "value": "${{AAD_APP_CLIENT_ID}}" + }, + "m365ClientSecret": { + "value": "${{SECRET_AAD_APP_CLIENT_SECRET}}" + }, + "m365TenantId": { + "value": "${{AAD_APP_TENANT_ID}}" + }, + "m365OauthAuthorityHost": { + "value": "${{AAD_APP_OAUTH_AUTHORITY_HOST}}" + } + ``` + +1. Open `infra/azure.bicep` file, add the following code after `param location string = resourceGroup().location`: + + ```yml + param m365ClientId string + param m365TenantId string + param m365OauthAuthorityHost string + param m365ApplicationIdUri string = 'api://botid-${botAadAppClientId}' + @secure() + param m365ClientSecret string + ``` + +1. Add following code before output: + + ```yml + resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = { + name: '${webAppName}/appsettings' + properties: { + M365_CLIENT_ID: m365ClientId + M365_CLIENT_SECRET: m365ClientSecret + INITIATE_LOGIN_ENDPOINT: uri('https://${webApp.properties.defaultHostName}', 'auth-start.html') + M365_AUTHORITY_HOST: m365OauthAuthorityHost + M365_TENANT_ID: m365TenantId + M365_APPLICATION_ID_URI: m365ApplicationIdUri + BOT_ID: botAadAppClientId + BOT_PASSWORD: botAadAppClientSecret + RUNNING_ON_AZURE: '1' + } + } + ``` + +> [!NOTE] +> +> * To add additional configurations into your Azure Webapp, add the configurations in the `webAppSettings`. +> * You might also need to define the default node version by adding the following configuration: + ```yml + WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' + ``` + +## Update Source Code + +# [Bot](#tab1/bot) + + 1. Move the files located in the `auth/sso` folder to `src`. The `ProfileSsoCommandHandler` class serves as an SSO command handler, designed to retrieve user information using an SSO token. You can adopt this method to develop your own SSO command handler. + + 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages by Microsoft Entra. + + 1. Run the following command in `./` folder: + + ```bash + npm install copyfiles --save-dev + ``` + + 1. Replace the following command in `package.json` file: + + ```bash + "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src", + ``` + + With + + ```bash + "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/", + ``` + + The HTML pages used for auth redirect will be copied when building this bot project. + + 1. In `src/index` file, add the following command to import `isomorphic-fetch`: + + ```yml + require("isomorphic-fetch"); + ``` + + 1. Add the following command to redirect to auth pages: + + ```yml + server.get( + "/auth-:name(start|end).html", + restify.plugins.serveStatic({ + directory: path.join(__dirname, "public"), + }) + ); + ``` + + 1. update `commandApp.requestHandler` to make auth works with the following code: + + ```yml + await commandApp.requestHandler(req, res).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. Add `ssoConfig` and `ssoCommands` in conversation bot in `src/internal/initialize`: + + ```yml + import { ProfileSsoCommandHandler } from "../profileSsoCommandHandler"; + + export const commandBot = new ConversationBot({ + ... + // To learn more about ssoConfig, please refer teamsfx sdk document: https://docs.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk + ssoConfig: { + aad :{ + scopes:["User.Read"], + }, + }, + command: { + enabled: true, + commands: [new HelloWorldCommandHandler() ], + ssoCommands: [new ProfileSsoCommandHandler()], + }, + }); + ``` + +# [Messaging extension](#tab/messaging-extension) + + Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) + + 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages by Microsoft Entra. + + 1. Update your `src/index` file to add the appropriate `restify`: + + ```bash + const path = require("path"); + + // Listen for incoming requests. + server.post("/api/messages", async (req, res) => { + await adapter.process(req, res, async (context) => { + await bot.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; + } + }) + }); + + server.get( + "/auth-:name(start|end).html", + restify.plugins.serveStatic({ + directory: path.join(__dirname, "public"), + }) + ); + ``` + + 1. Run the following command under `./` folder: + + ```bash + npm install @microsoft/teamsfx + ``` + + 1. Run the following command under `./` folder: + + ```bash + npm install isomorphic-fetch + ``` + + 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. + + 1. Install `copyfiles` npm packages in your typescript bot project, add or update the `build` script in `src/package.json` file as follows: + + ```bash + "build": "tsc --build && copyfiles ./public/*.html lib/", + ``` + + The HTML pages used for auth redirect will be copied when building this bot project. + + 1. Update `templates/appPackage/aad.template.json` file with the scopes you use in the `handleMessageExtensionQueryWithSSO` function: + + ```bash + "requiredResourceAccess": [ + { + "resourceAppId": "Microsoft Graph", + "resourceAccess": [ + { + "id": "User.Read", + "type": "Scope" + } + ] + } + ] + ``` + + --- + +--- + +## Debug Your Application + +You can debug your app by pressing F5. Teams Toolkit will use the Microsoft Entra manifest to register an SSO-enabled application. For more information, see [debug your Teams app locally.] + +## Customize Microsoft Entra apps + +The Microsoft Teams [manifest](/entra/identity-platform/reference-app-manifest) enables you to customize different aspects of your app registration. You have the ability to update the manifest as required. + +To include additional API permissions to access your desired APIs, see [edit Microsoft Entra manifest](AAD-manifest-customization.md). + +To view your Microsoft Entra app in Azure Portal, see [edit Microsoft Entra manifest](AAD-manifest-customization.md). + +## Next step + +> [!div class="nextstepaction"] +> [Add single sign-on to Teams app](../../../../Documents/GitHub/dev%20docs/msteams-docs/msteams-platform/toolkit/add-single-sign-on.md) From f84a377245ee6f42095489dbf182d18518022b5e Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Wed, 9 Oct 2024 21:47:25 +0530 Subject: [PATCH 02/25] Update develop-single-sign-on-experience-in-Teams.md --- ...develop-single-sign-on-experience-in-Teams.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index e7b4a85e553..f033ebc5699 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -26,7 +26,7 @@ To enable SSO, configure as follows: ## Create Microsoft Entra app manifest -Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more inforamtion, see [manifest](/entra/identity-platform/reference-app-manifest). +Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [manifest](/entra/identity-platform/reference-app-manifest). ## Update Teams app manifest @@ -127,9 +127,9 @@ function getBasicUserInfo() { For React projects, ensure the following environment variables are set in your deployment process: -* For javascript project, see [tab javascript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/js) +* For JavaScript project, see [tab JavaScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/js) -* For typescript project, see [tab typescript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts) +* For TypeScript project, see [tab TypeScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts) To update your source code, follow these steps: @@ -148,7 +148,7 @@ For more information, see [sample.](https://github.com/OfficeDev/teams-toolkit-s ## Create Microsoft Entra app manifest -Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more inforamtion, see [manifest](/entra/identity-platform/reference-app-manifest). +Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [manifest](/entra/identity-platform/reference-app-manifest). ## Update Teams app manifest @@ -236,9 +236,9 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t To set up Microsoft Teams related configurations, update in your remote service. The following example shows the config settings on an Azure Webapp. -* M365_CLIENT_ID: Microsoft Entra app client id. +* M365_CLIENT_ID: Microsoft Entra app client ID. * M365_CLIENT_SECRET: Microsoft Entra app client secret. -* M365_TENANT_ID: Tenant id of Microsoft Entra app. +* M365_TENANT_ID: Tenant ID of Microsoft Entra app. * INITIATE_LOGIN_ENDPOINT: Login start page for authentication. * M365_AUTHORITY_HOST: Microsoft Entra app oauth authority host. * M365_APPLICATION_ID_URI: IdentifierUri for Microsoft Entra app. @@ -422,7 +422,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. - 1. Install `copyfiles` npm packages in your typescript bot project, add or update the `build` script in `src/package.json` file as follows: + 1. Install `copyfiles` npm packages in your TypeScript bot project, add, or update the `build` script in `src/package.json` file as follows: ```bash "build": "tsc --build && copyfiles ./public/*.html lib/", @@ -460,7 +460,7 @@ The Microsoft Teams [manifest](/entra/identity-platform/reference-app-manifest) To include additional API permissions to access your desired APIs, see [edit Microsoft Entra manifest](AAD-manifest-customization.md). -To view your Microsoft Entra app in Azure Portal, see [edit Microsoft Entra manifest](AAD-manifest-customization.md). +To view your Microsoft Entra app in Azure portal, see [edit Microsoft Entra manifest](AAD-manifest-customization.md). ## Next step From f9cd87fb823b61990a9773953187e211374d9c49 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 10:53:44 +0530 Subject: [PATCH 03/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index f033ebc5699..66cf3d227a2 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -2,7 +2,7 @@ title: Develop single sign-on experience in Teams author: surbhigupta description: Learn to how to develop single sign-on experience in Teams. -ms.topic: how-to-guides +ms.topic: overview ms.localizationpriority: medium --- @@ -144,13 +144,13 @@ To update your source code, follow these steps: For more information, see [sample.](https://github.com/OfficeDev/teams-toolkit-samples/tree/dev/hello-world-tab-with-backend) -# [Bot/Messaging extension app](#tab/tab-app) +# [Bot/Message extension app](#tab/message-extension-app) -## Create Microsoft Entra app manifest +## Create Microsoft Entra app manifest for bot/message extension app Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [manifest](/entra/identity-platform/reference-app-manifest). -## Update Teams app manifest +## Update Teams app manifest for bot/message extension app * In the `./appPackages/manifest.json` file, add the `webApplicationInfo` section to provide your Microsoft Entra app ID and Microsoft Graph information. @@ -183,7 +183,7 @@ Download the Microsoft Entra app manifest [template](https://github.com/OfficeDe ] ``` -## Teams Toolkit configuration files +## Teams Toolkit configuration files for bot/message extension app Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml` Update necessary configurations related to Microsoft Entra into these files. @@ -300,9 +300,9 @@ To use the `teamsFx` tab or bot template, follow these steps: WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' ``` -## Update Source Code +## Update Source Code for bot/message extension app -# [Bot](#tab1/bot) + # [Bot](#tab/bot) 1. Move the files located in the `auth/sso` folder to `src`. The `ProfileSsoCommandHandler` class serves as an SSO command handler, designed to retrieve user information using an SSO token. You can adopt this method to develop your own SSO command handler. @@ -377,7 +377,7 @@ To use the `teamsFx` tab or bot template, follow these steps: }); ``` -# [Messaging extension](#tab/messaging-extension) + # [Messaging extension](#tab/messaging-extension) Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) @@ -465,4 +465,5 @@ To view your Microsoft Entra app in Azure portal, see [edit Microsoft Entra mani ## Next step > [!div class="nextstepaction"] -> [Add single sign-on to Teams app](../../../../Documents/GitHub/dev%20docs/msteams-docs/msteams-platform/toolkit/add-single-sign-on.md) +> [Add single sign-on to Teams app](add-single-sign-on.md) + From e8b8c0bc09039e1acc82fa369b509eb111aa37bc Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 10:59:56 +0530 Subject: [PATCH 04/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 66cf3d227a2..0d9de132043 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -379,7 +379,7 @@ To use the `teamsFx` tab or bot template, follow these steps: # [Messaging extension](#tab/messaging-extension) - Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) + 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages by Microsoft Entra. @@ -446,9 +446,9 @@ To use the `teamsFx` tab or bot template, follow these steps: ] ``` - --- + --- ---- + --- ## Debug Your Application From a558a8cf05d8d6d55cda54256bd604e817eec210 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 11:09:32 +0530 Subject: [PATCH 05/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 0d9de132043..8ec6caa7487 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -446,7 +446,7 @@ To use the `teamsFx` tab or bot template, follow these steps: ] ``` - --- + --- --- From fccd6e1f65a89435ee4125aec7f478deab3652a1 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 11:18:46 +0530 Subject: [PATCH 06/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 8ec6caa7487..0b15b6d3cd2 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -432,21 +432,21 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Update `templates/appPackage/aad.template.json` file with the scopes you use in the `handleMessageExtensionQueryWithSSO` function: - ```bash - "requiredResourceAccess": [ - { - "resourceAppId": "Microsoft Graph", - "resourceAccess": [ - { - "id": "User.Read", - "type": "Scope" - } - ] - } - ] - ``` - - --- + ```bash + "requiredResourceAccess": [ + { + "resourceAppId": "Microsoft Graph", + "resourceAccess": [ + { + "id": "User.Read", + "type": "Scope" + } + ] + } + ] + ``` + + --- --- From 820f31c12a5df6c0ecbb781136ae49a1aa1b65e1 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 11:28:24 +0530 Subject: [PATCH 07/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 0b15b6d3cd2..3aaa689ab26 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -177,11 +177,11 @@ Download the Microsoft Entra app manifest [template](https://github.com/OfficeDe * The `validDomains` field includes the legitimate domains for websites that the app anticipates loading within the Teams client. If you're using the `teamsFx` bot template, you can set the following values: -```yml -"validDomains": [ - "${{BOT_DOMAIN}}" -] -``` + ```yml + "validDomains": [ + "${{BOT_DOMAIN}}" + ] + ``` ## Teams Toolkit configuration files for bot/message extension app @@ -292,13 +292,13 @@ To use the `teamsFx` tab or bot template, follow these steps: } ``` -> [!NOTE] -> -> * To add additional configurations into your Azure Webapp, add the configurations in the `webAppSettings`. -> * You might also need to define the default node version by adding the following configuration: - ```yml - WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' - ``` + > [!NOTE] + > + > * To add additional configurations into your Azure Webapp, add the configurations in the `webAppSettings`. + > * You might also need to define the default node version by adding the following configuration: + ```yml + WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' + ``` ## Update Source Code for bot/message extension app @@ -446,9 +446,9 @@ To use the `teamsFx` tab or bot template, follow these steps: ] ``` - --- + --- - --- +--- ## Debug Your Application From 16a88186fd8be1c659b6a7261bb4b29facb25a98 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 11:49:03 +0530 Subject: [PATCH 08/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 3aaa689ab26..49033e4aaa7 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -300,7 +300,7 @@ To use the `teamsFx` tab or bot template, follow these steps: WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' ``` -## Update Source Code for bot/message extension app + ## Update Source Code for bot/message extension app # [Bot](#tab/bot) @@ -432,21 +432,20 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Update `templates/appPackage/aad.template.json` file with the scopes you use in the `handleMessageExtensionQueryWithSSO` function: - ```bash - "requiredResourceAccess": [ - { - "resourceAppId": "Microsoft Graph", - "resourceAccess": [ - { - "id": "User.Read", - "type": "Scope" - } + ```bash + "requiredResourceAccess": [ + { + "resourceAppId": "Microsoft Graph", + "resourceAccess": [ + { + "id": "User.Read", + "type": "Scope" + } + ] + } ] - } - ] - ``` - - --- + ``` + --- --- From 5ad162648fcc34fcc1e6fd82278b95adc8ec3464 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 11:56:45 +0530 Subject: [PATCH 09/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 49033e4aaa7..58c53ae39dc 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -432,19 +432,19 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Update `templates/appPackage/aad.template.json` file with the scopes you use in the `handleMessageExtensionQueryWithSSO` function: - ```bash - "requiredResourceAccess": [ - { - "resourceAppId": "Microsoft Graph", - "resourceAccess": [ - { - "id": "User.Read", - "type": "Scope" - } - ] - } - ] - ``` + ```bash + "requiredResourceAccess": [ + { + "resourceAppId": "Microsoft Graph", + "resourceAccess": [ + { + "id": "User.Read", + "type": "Scope" + } + ] + } + ] + ``` --- --- From b3f1d10750cd3a9c4bab12c06c6d645025a21514 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 12:01:19 +0530 Subject: [PATCH 10/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 58c53ae39dc..aacbb197b7d 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -168,7 +168,7 @@ Download the Microsoft Entra app manifest [template](https://github.com/OfficeDe The `commandLists` includes commands that your bot can suggest to users. If you're using the `teamsFx` bot template, set the following values: - ```yml + ```bash { "title": "profile", "description": "Show user profile using Single Sign On feature" @@ -177,7 +177,7 @@ Download the Microsoft Entra app manifest [template](https://github.com/OfficeDe * The `validDomains` field includes the legitimate domains for websites that the app anticipates loading within the Teams client. If you're using the `teamsFx` bot template, you can set the following values: - ```yml + ```bash "validDomains": [ "${{BOT_DOMAIN}}" ] @@ -247,7 +247,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Open `infra/azure.parameters.json` file and add the following: - ```yml + ```bash "m365ClientId": { "value": "${{AAD_APP_CLIENT_ID}}" }, @@ -264,7 +264,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Open `infra/azure.bicep` file, add the following code after `param location string = resourceGroup().location`: - ```yml + ```bash param m365ClientId string param m365TenantId string param m365OauthAuthorityHost string @@ -275,7 +275,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Add following code before output: - ```yml + ```bash resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = { name: '${webAppName}/appsettings' properties: { @@ -296,7 +296,7 @@ To use the `teamsFx` tab or bot template, follow these steps: > > * To add additional configurations into your Azure Webapp, add the configurations in the `webAppSettings`. > * You might also need to define the default node version by adding the following configuration: - ```yml + ```bash WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' ``` @@ -330,13 +330,13 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. In `src/index` file, add the following command to import `isomorphic-fetch`: - ```yml + ```bash require("isomorphic-fetch"); ``` 1. Add the following command to redirect to auth pages: - ```yml + ```bash server.get( "/auth-:name(start|end).html", restify.plugins.serveStatic({ @@ -347,7 +347,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. update `commandApp.requestHandler` to make auth works with the following code: - ```yml + ```bash await commandApp.requestHandler(req, res).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")) { @@ -358,7 +358,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Add `ssoConfig` and `ssoCommands` in conversation bot in `src/internal/initialize`: - ```yml + ```bash import { ProfileSsoCommandHandler } from "../profileSsoCommandHandler"; export const commandBot = new ConversationBot({ From dd07288431c4457cdd358bcfb183747354a904f9 Mon Sep 17 00:00:00 2001 From: v-bvishnu <129953098+v-bvishnu@users.noreply.github.com> Date: Thu, 10 Oct 2024 12:27:53 +0530 Subject: [PATCH 11/25] Update add-single-sign-on.md --- msteams-platform/toolkit/add-single-sign-on.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/toolkit/add-single-sign-on.md b/msteams-platform/toolkit/add-single-sign-on.md index a9dd6c2e058..f0217319185 100644 --- a/msteams-platform/toolkit/add-single-sign-on.md +++ b/msteams-platform/toolkit/add-single-sign-on.md @@ -42,7 +42,7 @@ You can perform the following steps to add SSO using Teams Toolkit in Visual Stu |**Development** | **How-to Guide** | | -------- | --------| - |Develop Single Sign-on Experience in Teams | [How to Develop Single Sign-on Experience](https://github.com/OfficeDev/TeamsFx/wiki/Develop-single-sign-on-experience-in-Teams) | + |Develop Single Sign-on Experience in Teams | [Enable single sign-on for tab app](develop-single-sign-on-experience-in-Teams.md) | > [!NOTE] > When SSO is enabled, Teams Toolkit by default provisions a single-tenant Microsoft Entra app, which means only user and guest accounts in the same directory as your M365 account can sign in to your Teams app. For more information on supporting multitenant to update your TeamsFx project, see [Multi-tenancy support for Microsoft Entra app](https://github.com/OfficeDev/TeamsFx/wiki/Multi-tenancy-Support-for-Azure-AD-app). From bc117603237bf2c8dd81030529020bc3ee760203 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 12 Nov 2024 12:34:39 +0530 Subject: [PATCH 12/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index aacbb197b7d..1bf61c8df8f 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -127,7 +127,7 @@ function getBasicUserInfo() { For React projects, ensure the following environment variables are set in your deployment process: -* For JavaScript project, see [tab JavaScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/js) +* For JavaScript project, see [tab JavaScript sample.](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts/sso/InitTeamsFx.tsx#L12) * For TypeScript project, see [tab TypeScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts) From eb02b79f0192167f117837fc4773beaa131b1876 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 12 Nov 2024 12:55:55 +0530 Subject: [PATCH 13/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 1 + 1 file changed, 1 insertion(+) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 1bf61c8df8f..53bfc9c6213 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -3,6 +3,7 @@ title: Develop single sign-on experience in Teams author: surbhigupta description: Learn to how to develop single sign-on experience in Teams. ms.topic: overview +ms.date: 11/12/2024 ms.localizationpriority: medium --- From 53dfdbb97140c096a6663a9175c0cdcdaa4491a5 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 12 Nov 2024 15:38:25 +0530 Subject: [PATCH 14/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 53bfc9c6213..db3cbffbc04 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -9,7 +9,7 @@ ms.localizationpriority: medium # Enable single sign-on for tab app -Microsoft Teams allows an app to acquire the token of the signed-in Teams user. This token can be used to access Microsoft Graph and other APIs. The Teams Toolkit simplifies this process by encapsulating some of the Microsoft Entra flows and integrations within straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams application. +Microsoft Teams allows an app to acquire the token of the signed-in Teams user. This token can be used to access Microsoft Graph and other APIs. The Teams Toolkit simplifies this process by encapsulating some of the Microsoft Entra flows and integrations within straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams app. ## Key Configurations @@ -446,13 +446,14 @@ To use the `teamsFx` tab or bot template, follow these steps: } ] ``` + --- --- ## Debug Your Application -You can debug your app by pressing F5. Teams Toolkit will use the Microsoft Entra manifest to register an SSO-enabled application. For more information, see [debug your Teams app locally.] +You can debug your app by pressing F5. Teams Toolkit will use the Microsoft Entra manifest to register an SSO-enabled application. For more information, see [debug your Teams app locally.](debug-local.md) ## Customize Microsoft Entra apps @@ -466,4 +467,3 @@ To view your Microsoft Entra app in Azure portal, see [edit Microsoft Entra mani > [!div class="nextstepaction"] > [Add single sign-on to Teams app](add-single-sign-on.md) - From 864edf1193dbbed76390d55e8bce41f30e671769 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Mon, 16 Dec 2024 19:19:07 +0530 Subject: [PATCH 15/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index db3cbffbc04..b77c08248c3 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -1,7 +1,7 @@ --- -title: Develop single sign-on experience in Teams +title: Develop Single Sign-on Experience in Teams author: surbhigupta -description: Learn to how to develop single sign-on experience in Teams. +description: Learn how to develop single sign-on experience in Teams. ms.topic: overview ms.date: 11/12/2024 ms.localizationpriority: medium @@ -9,9 +9,9 @@ ms.localizationpriority: medium # Enable single sign-on for tab app -Microsoft Teams allows an app to acquire the token of the signed-in Teams user. This token can be used to access Microsoft Graph and other APIs. The Teams Toolkit simplifies this process by encapsulating some of the Microsoft Entra flows and integrations within straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams app. +Microsoft Teams allows an app to acquire the token of the signed-in Teams user. This token can be used to access Microsoft Graph and other APIs. Teams Toolkit streamlines the process by incorporating certain Microsoft Entra workflows and integrations into straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams app. -## Key Configurations +## Key configurations To enable SSO, configure as follows: @@ -27,7 +27,7 @@ To enable SSO, configure as follows: ## Create Microsoft Entra app manifest -Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [manifest](/entra/identity-platform/reference-app-manifest). +Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). ## Update Teams app manifest @@ -45,9 +45,9 @@ In the `./appPackages/manifest.json` file, add the `webApplicationInfo` section ## Teams Toolkit configuration files -Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml` Update necessary configurations related to Microsoft Entra into these files. +Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update the required configurations related with Microsoft Entra in these files. -* Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra apps used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): +* Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra app used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): ```yaml - uses: aadApp/create @@ -64,7 +64,7 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t ``` > [!NOTE] - > Replace the `name` value with the desired name for your Microsoft Teams app. + > Replace the `name` value with the desired name for your Teams app. * Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): @@ -79,7 +79,7 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t > * Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. > * In a local setup, position the `aad/update` after the `file/createOrUpdateEnvironmentFile` action. This is because `aad/update` utilizes the output from `file/createOrUpdateEnvironmentFile`. -* For React project, update `cli/runNpmCommand` under `deploy`: +* For React project, update `cli/runNpmCommand` under `deploy`. * If you're building a tab app using the React framework, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: @@ -145,11 +145,11 @@ To update your source code, follow these steps: For more information, see [sample.](https://github.com/OfficeDev/teams-toolkit-samples/tree/dev/hello-world-tab-with-backend) -# [Bot/Message extension app](#tab/message-extension-app) +# [Bot/message extension app](#tab/message-extension-app) ## Create Microsoft Entra app manifest for bot/message extension app -Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [manifest](/entra/identity-platform/reference-app-manifest). +Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). ## Update Teams app manifest for bot/message extension app @@ -274,7 +274,7 @@ To use the `teamsFx` tab or bot template, follow these steps: param m365ClientSecret string ``` -1. Add following code before output: +1. Add the following code before output: ```bash resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = { @@ -453,11 +453,11 @@ To use the `teamsFx` tab or bot template, follow these steps: ## Debug Your Application -You can debug your app by pressing F5. Teams Toolkit will use the Microsoft Entra manifest to register an SSO-enabled application. For more information, see [debug your Teams app locally.](debug-local.md) +You can debug your app by pressing F5. Teams Toolkit uses the Microsoft Entra manifest to register an SSO-enabled app For more information, see [debug your Teams app locally.](debug-local.md) ## Customize Microsoft Entra apps -The Microsoft Teams [manifest](/entra/identity-platform/reference-app-manifest) enables you to customize different aspects of your app registration. You have the ability to update the manifest as required. +Teams [app manifest](/entra/identity-platform/reference-app-manifest) enables you to customize different aspects of your app registration. You can update the manifest as required. To include additional API permissions to access your desired APIs, see [edit Microsoft Entra manifest](AAD-manifest-customization.md). From ed95d7f341d92f134b2fd630af4ca3931ccea726 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 13:06:18 +0530 Subject: [PATCH 16/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 108 ++++++++++-------- 1 file changed, 60 insertions(+), 48 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index b77c08248c3..dfd7574a032 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -1,37 +1,41 @@ --- -title: Develop Single Sign-on Experience in Teams +title: Develop Single Sign-on Experience author: surbhigupta -description: Learn how to develop single sign-on experience in Teams. -ms.topic: overview -ms.date: 11/12/2024 +description: Learn how to develop single sign-on experience in Teams app using Teams Toolkit. +ms.topic: reference +ms.date: 12/17/2024 ms.localizationpriority: medium --- -# Enable single sign-on for tab app +# Enable single sign-on for Teams app -Microsoft Teams allows an app to acquire the token of the signed-in Teams user. This token can be used to access Microsoft Graph and other APIs. Teams Toolkit streamlines the process by incorporating certain Microsoft Entra workflows and integrations into straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams app. +Microsoft Teams provides single sign-on (SSO) function for an app to obtain signed in Teams user token to access Microsoft Graph and other APIs. Teams Toolkit streamlines the process by incorporating certain Microsoft Entra workflows and integrations into straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams app. For more information, see [authenticate users in Microsoft Teams.](../concepts/authentication/authentication.md) ## Key configurations To enable SSO, configure as follows: -* Microsoft Entra app manifest: Ensure to define URIs, including the URI that identifies the Microsoft Entra authentication app and the redirect URI that returns the token. +* **Microsoft Entra app manifest**: Ensure to define URIs, including the URI that identifies the Microsoft Entra authentication app and the redirect URI that returns the token. -* Teams app manifest: Connect your single sign-on (SSO) app to your Teams app by incorporating the correct configuration. +* **Teams app manifest**: Connect your SSO app to your Teams app by incorporating the correct configuration. -* Teams Toolkit configuration and infra files: Ensure the necessary configurations are in place to enable SSO for your Teams app. +* **Teams Toolkit configuration and infra files**: Ensure the necessary configurations are in place to enable SSO for your Teams app. -* Add SSO app information in Teams Toolkit configuration files: Ensure the authentication app registers on the backend service and the Teams Toolkit initiates it during the debugging or previewing of the Teams app. +* **SSO app information in Teams Toolkit configuration files**: Ensure the authentication app registers on the backend service and Teams Toolkit initiates it during the debugging or previewing of the Teams app. # [Tab app](#tab/tab-app) ## Create Microsoft Entra app manifest -Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). +1. Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json). -## Update Teams app manifest +1. Add the downloaded app manifest code to `./aad.manifest.json` file. + +This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). + +## Teams app manifest -In the `./appPackages/manifest.json` file, add the `webApplicationInfo` section to provide your Microsoft Entra app ID and Microsoft Graph information. +In the `./appPackages/manifest.json` file, add the following code: ```json "webApplicationInfo": { @@ -40,6 +44,8 @@ In the `./appPackages/manifest.json` file, add the `webApplicationInfo` section } ``` +`webApplicationInfo` provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app. + > [!NOTE] > You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. @@ -77,11 +83,11 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t > [!NOTE] > * Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. - > * In a local setup, position the `aad/update` after the `file/createOrUpdateEnvironmentFile` action. This is because `aad/update` utilizes the output from `file/createOrUpdateEnvironmentFile`. + > * In a local setup, position the `aad/update` after the `file/createOrUpdateEnvironmentFile` action. This is required because `aad/update` uses the output from `file/createOrUpdateEnvironmentFile`. * For React project, update `cli/runNpmCommand` under `deploy`. -* If you're building a tab app using the React framework, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: +* If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: ```yml env: @@ -143,17 +149,21 @@ To update your source code, follow these steps: 1. Import and add `InitTeamsFx` in `Welcome.*`. -For more information, see [sample.](https://github.com/OfficeDev/teams-toolkit-samples/tree/dev/hello-world-tab-with-backend) +For more information, see [sample app.](https://github.com/OfficeDev/teams-toolkit-samples/tree/dev/hello-world-tab-with-backend) # [Bot/message extension app](#tab/message-extension-app) -## Create Microsoft Entra app manifest for bot/message extension app +## Create Microsoft Entra app manifest + +1. Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json). + +1. Add the downloaded app manifest code to `./aad.manifest.json` file. -Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json) to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). +This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). -## Update Teams app manifest for bot/message extension app +## Update Teams app manifest -* In the `./appPackages/manifest.json` file, add the `webApplicationInfo` section to provide your Microsoft Entra app ID and Microsoft Graph information. +1. In the `./appPackages/manifest.json` file, add the following code: ```json "webApplicationInfo": { @@ -162,10 +172,12 @@ Download the Microsoft Entra app manifest [template](https://github.com/OfficeDe } ``` + `webApplicationInfo` provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app. + > [!NOTE] > You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. -* Register command in `commandLists`. +1. Register command in `commandLists`. The `commandLists` includes commands that your bot can suggest to users. If you're using the `teamsFx` bot template, set the following values: @@ -176,7 +188,7 @@ Download the Microsoft Entra app manifest [template](https://github.com/OfficeDe } ``` -* The `validDomains` field includes the legitimate domains for websites that the app anticipates loading within the Teams client. If you're using the `teamsFx` bot template, you can set the following values: +1. The `validDomains` field includes the domains for websites that the app loads within the Teams client. Update the following values: ```bash "validDomains": [ @@ -184,11 +196,11 @@ Download the Microsoft Entra app manifest [template](https://github.com/OfficeDe ] ``` -## Teams Toolkit configuration files for bot/message extension app +## Teams Toolkit configuration files -Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml` Update necessary configurations related to Microsoft Entra into these files. +1. Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update necessary configurations related to Microsoft Entra into these files. -* Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra apps used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): +1. Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra apps used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): ```yaml - uses: aadApp/create @@ -208,7 +220,7 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t > [!NOTE] > Replace the `name` value with the desired name for your Microsoft Teams app. -* Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): +1. Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): ```yaml - uses: aadApp/update @@ -220,9 +232,9 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t > [!NOTE] > Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. -* `file/createOrUpdateEnvironmentFile`: Locate the `createOrUpdateEnvironmentFile` action in `teamsapp.local.yml` file and add the following environment variables: +1. Locate the `createOrUpdateEnvironmentFile` action in `teamsapp.local.yml` file and add the following environment variables: - ```yml + ```yaml envs: ... M365_CLIENT_ID: ${{AAD_APP_CLIENT_ID}} @@ -235,20 +247,20 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t ## Update Infra -To set up Microsoft Teams related configurations, update in your remote service. The following example shows the config settings on an Azure Webapp. +Update Microsoft Entra-related configurations in your remote service. The following example shows the configuration settings on an Azure web app: -* M365_CLIENT_ID: Microsoft Entra app client ID. -* M365_CLIENT_SECRET: Microsoft Entra app client secret. -* M365_TENANT_ID: Tenant ID of Microsoft Entra app. -* INITIATE_LOGIN_ENDPOINT: Login start page for authentication. -* M365_AUTHORITY_HOST: Microsoft Entra app oauth authority host. -* M365_APPLICATION_ID_URI: IdentifierUri for Microsoft Entra app. +* `M365_CLIENT_ID`: Microsoft Entra app client ID +* `M365_CLIENT_SECRET`: Microsoft Entra app client secret +* `M365_TENANT_ID`: Tenant ID of Microsoft Entra app +* `INITIATE_LOGIN_ENDPOINT`: Login start page for authentication +* `M365_AUTHORITY_HOST`: Microsoft Entra app OAuth authority host +* `M365_APPLICATION_ID_URI`: Identifier URI for Microsoft Entra app To use the `teamsFx` tab or bot template, follow these steps: 1. Open `infra/azure.parameters.json` file and add the following: - ```bash + ```json "m365ClientId": { "value": "${{AAD_APP_CLIENT_ID}}" }, @@ -265,7 +277,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Open `infra/azure.bicep` file, add the following code after `param location string = resourceGroup().location`: - ```bash + ```bicep param m365ClientId string param m365TenantId string param m365OauthAuthorityHost string @@ -276,7 +288,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Add the following code before output: - ```bash + ```bicep resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = { name: '${webAppName}/appsettings' properties: { @@ -295,19 +307,19 @@ To use the `teamsFx` tab or bot template, follow these steps: > [!NOTE] > - > * To add additional configurations into your Azure Webapp, add the configurations in the `webAppSettings`. + > * To add additional configurations into your Azure web app, add the configurations in the `webAppSettings`. > * You might also need to define the default node version by adding the following configuration: ```bash WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' ``` - ## Update Source Code for bot/message extension app + ## Update Source Code # [Bot](#tab/bot) 1. Move the files located in the `auth/sso` folder to `src`. The `ProfileSsoCommandHandler` class serves as an SSO command handler, designed to retrieve user information using an SSO token. You can adopt this method to develop your own SSO command handler. - 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages by Microsoft Entra. + 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages. 1. Run the following command in `./` folder: @@ -317,13 +329,13 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Replace the following command in `package.json` file: - ```bash + ```json "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src", ``` With - ```bash + ```json "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/", ``` @@ -346,7 +358,7 @@ To use the `teamsFx` tab or bot template, follow these steps: ); ``` - 1. update `commandApp.requestHandler` to make auth works with the following code: + 1. Update `commandApp.requestHandler` to ensure auth works with the following code: ```bash await commandApp.requestHandler(req, res).catch((err) => { @@ -382,7 +394,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) - 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages by Microsoft Entra. + 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages. 1. Update your `src/index` file to add the appropriate `restify`: @@ -423,7 +435,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. - 1. Install `copyfiles` npm packages in your TypeScript bot project, add, or update the `build` script in `src/package.json` file as follows: + 1. Install `copyfiles` npm packages in your TypeScript bot project, update the `build` script in `src/package.json` file as follows: ```bash "build": "tsc --build && copyfiles ./public/*.html lib/", @@ -451,9 +463,9 @@ To use the `teamsFx` tab or bot template, follow these steps: --- -## Debug Your Application +## Debug your app -You can debug your app by pressing F5. Teams Toolkit uses the Microsoft Entra manifest to register an SSO-enabled app For more information, see [debug your Teams app locally.](debug-local.md) +Debug your app by pressing **F5**. Teams Toolkit uses the Microsoft Entra manifest to register an SSO-enabled app. For more information, see [debug your Teams app locally.](debug-local.md) ## Customize Microsoft Entra apps From 679daf9de771a40afbf835f81bd8145c01840390 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 13:22:11 +0530 Subject: [PATCH 17/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index dfd7574a032..3b7755ebebc 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -247,7 +247,7 @@ This allows you to customize different aspects of your app registration and upda ## Update Infra -Update Microsoft Entra-related configurations in your remote service. The following example shows the configuration settings on an Azure web app: +Update Microsoft Entra-related configurations in your remote service. The following example shows the configuration settings on an Azure Web App: * `M365_CLIENT_ID`: Microsoft Entra app client ID * `M365_CLIENT_SECRET`: Microsoft Entra app client secret @@ -286,7 +286,7 @@ To use the `teamsFx` tab or bot template, follow these steps: param m365ClientSecret string ``` -1. Add the following code before output: +1. Add the following code before output in the `infra/azure.bicep` file: ```bicep resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = { @@ -307,7 +307,7 @@ To use the `teamsFx` tab or bot template, follow these steps: > [!NOTE] > - > * To add additional configurations into your Azure web app, add the configurations in the `webAppSettings`. + > * To add additional configurations into your Azure Web App, add the configurations in the `webAppSettings`. > * You might also need to define the default node version by adding the following configuration: ```bash WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' @@ -465,7 +465,7 @@ To use the `teamsFx` tab or bot template, follow these steps: ## Debug your app -Debug your app by pressing **F5**. Teams Toolkit uses the Microsoft Entra manifest to register an SSO-enabled app. For more information, see [debug your Teams app locally.](debug-local.md) +To debug your app, select the **F5** key. Teams Toolkit uses the Microsoft Entra manifest to register an SSO-enabled app. For more information, see [debug your Teams app locally.](debug-local.md) ## Customize Microsoft Entra apps From fb497c309980a2fd2540eeb1486e21ab9893687b Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 13:34:34 +0530 Subject: [PATCH 18/25] Update develop-single-sign-on-experience-in-Teams.md --- .../develop-single-sign-on-experience-in-Teams.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 3b7755ebebc..9604c0fd3b1 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -106,7 +106,7 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t ## Update source code -After implementing the above changes, your environment is prepared. You can now update your code to incorporate SSO into your Teams app. +With the above changes implemented, your environment is prepared. You can now update your code to incorporate SSO into your Teams app. #### Vanilla JavaScript @@ -258,7 +258,7 @@ Update Microsoft Entra-related configurations in your remote service. The follow To use the `teamsFx` tab or bot template, follow these steps: -1. Open `infra/azure.parameters.json` file and add the following: +1. Open the `infra/azure.parameters.json` file and add the following code: ```json "m365ClientId": { @@ -319,7 +319,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Move the files located in the `auth/sso` folder to `src`. The `ProfileSsoCommandHandler` class serves as an SSO command handler, designed to retrieve user information using an SSO token. You can adopt this method to develop your own SSO command handler. - 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages. + 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. On initiating SSO flows with Microsoft Entra, the user is redirected to these pages. 1. Run the following command in `./` folder: @@ -339,7 +339,7 @@ To use the `teamsFx` tab or bot template, follow these steps: "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/", ``` - The HTML pages used for auth redirect will be copied when building this bot project. + The HTML pages used for auth redirect are copied when building this bot project. 1. In `src/index` file, add the following command to import `isomorphic-fetch`: @@ -394,7 +394,7 @@ To use the `teamsFx` tab or bot template, follow these steps: 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) - 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. When initiating SSO flows with Microsoft Entra, the user is redirected to these pages. + 1. Move the `auth/public` folder to `src/public`. This folder contains HTML pages for the bot app. On initiating SSO flows with Microsoft Entra, the user is redirected to these pages. 1. Update your `src/index` file to add the appropriate `restify`: @@ -441,7 +441,7 @@ To use the `teamsFx` tab or bot template, follow these steps: "build": "tsc --build && copyfiles ./public/*.html lib/", ``` - The HTML pages used for auth redirect will be copied when building this bot project. + The HTML pages used for auth redirect are copied when building this bot project. 1. Update `templates/appPackage/aad.template.json` file with the scopes you use in the `handleMessageExtensionQueryWithSSO` function: From 82e972efe6b77b5738bb766a9152047789cd039b Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 13:51:51 +0530 Subject: [PATCH 19/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 9604c0fd3b1..d1261d01af2 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -31,29 +31,29 @@ To enable SSO, configure as follows: 1. Add the downloaded app manifest code to `./aad.manifest.json` file. -This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). + This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). ## Teams app manifest -In the `./appPackages/manifest.json` file, add the following code: +1. In the `./appPackages/manifest.json` file, add the following code: -```json -"webApplicationInfo": { - "id": "${{AAD_APP_CLIENT_ID}}", - "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}" -} -``` + ```json + "webApplicationInfo": { + "id": "${{AAD_APP_CLIENT_ID}}", + "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}" + } + ``` -`webApplicationInfo` provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app. +1. `webApplicationInfo` provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app. -> [!NOTE] -> You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. + > [!NOTE] + > You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. ## Teams Toolkit configuration files -Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update the required configurations related with Microsoft Entra in these files. +1. Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update the required configurations related with Microsoft Entra in these files. -* Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra app used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): +1. Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra app used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): ```yaml - uses: aadApp/create @@ -72,7 +72,7 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t > [!NOTE] > Replace the `name` value with the desired name for your Teams app. -* Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): +1. Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): ```yaml - uses: aadApp/update @@ -85,9 +85,9 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t > * Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. > * In a local setup, position the `aad/update` after the `file/createOrUpdateEnvironmentFile` action. This is required because `aad/update` uses the output from `file/createOrUpdateEnvironmentFile`. -* For React project, update `cli/runNpmCommand` under `deploy`. +1. For React project, update `cli/runNpmCommand` under `deploy`. -* If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: +1. If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: ```yml env: @@ -95,7 +95,7 @@ Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./t REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html ``` -* If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deploy in `teamsapp.local.yml` and add the following env: +1. If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deploy in `teamsapp.local.yml` and add the following env: ```yml envs: From 90338399c6b76712bea90b75e7a98996a5c564a2 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 16:27:41 +0530 Subject: [PATCH 20/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 76 ++++++++++--------- 1 file changed, 40 insertions(+), 36 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index d1261d01af2..16d5cf8bb8a 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -9,11 +9,11 @@ ms.localizationpriority: medium # Enable single sign-on for Teams app -Microsoft Teams provides single sign-on (SSO) function for an app to obtain signed in Teams user token to access Microsoft Graph and other APIs. Teams Toolkit streamlines the process by incorporating certain Microsoft Entra workflows and integrations into straightforward, high-level APIs. As a result, you can effortlessly incorporate single sign-on (SSO) capabilities into your Teams app. For more information, see [authenticate users in Microsoft Teams.](../concepts/authentication/authentication.md) +Microsoft Teams provides single sign-on (SSO) function for an app to obtain signed in Teams user token to access Microsoft Graph and other APIs. Microsoft Teams Toolkit streamlines the process by incorporating certain Microsoft Entra workflows and integrations into straightforward, high-level APIs. As a result, you can effortlessly incorporate SSO capabilities into your Teams app. For more information, see [authenticate users in Microsoft Teams.](../concepts/authentication/authentication.md) ## Key configurations -To enable SSO, configure as follows: +To enable SSO, configure your Teams app as follows: * **Microsoft Entra app manifest**: Ensure to define URIs, including the URI that identifies the Microsoft Entra authentication app and the redirect URI that returns the token. @@ -29,13 +29,11 @@ To enable SSO, configure as follows: 1. Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json). -1. Add the downloaded app manifest code to `./aad.manifest.json` file. +1. Add the downloaded app manifest code to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). - This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). - -## Teams app manifest +## Update Teams app manifest -1. In the `./appPackages/manifest.json` file, add the following code: +In the `./appPackages/manifest.json` file, add the following code: ```json "webApplicationInfo": { @@ -44,16 +42,16 @@ To enable SSO, configure as follows: } ``` -1. `webApplicationInfo` provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app. +`webApplicationInfo` provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app. > [!NOTE] > You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. -## Teams Toolkit configuration files +## Update Teams Toolkit configuration files -1. Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update the required configurations related with Microsoft Entra in these files. +1. Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update the required configurations related to Microsoft Entra in these files. -1. Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra app used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): +1. Add the `aadApp/create` action under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra app used for SSO: ```yaml - uses: aadApp/create @@ -72,7 +70,9 @@ To enable SSO, configure as follows: > [!NOTE] > Replace the `name` value with the desired name for your Teams app. -1. Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): + For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate) + +1. Add the `aadApp/update` action under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app: ```yaml - uses: aadApp/update @@ -85,19 +85,21 @@ To enable SSO, configure as follows: > * Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. > * In a local setup, position the `aad/update` after the `file/createOrUpdateEnvironmentFile` action. This is required because `aad/update` uses the output from `file/createOrUpdateEnvironmentFile`. -1. For React project, update `cli/runNpmCommand` under `deploy`. + For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate) + +1. For a React project, update `cli/runNpmCommand` under `deploy`. 1. If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: - ```yml + ```yaml env: REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}} REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html ``` -1. If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deploy in `teamsapp.local.yml` and add the following env: +1. If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deployment in `teamsapp.local.yml` file and add the following environment: - ```yml + ```yaml envs: ... REACT_APP_CLIENT_ID: ${{AAD_APP_CLIENT_ID}} @@ -108,7 +110,7 @@ To enable SSO, configure as follows: With the above changes implemented, your environment is prepared. You can now update your code to incorporate SSO into your Teams app. -#### Vanilla JavaScript +### Vanilla JavaScript Use the following code to retrieve the SSO token and user information: @@ -130,22 +132,22 @@ function getBasicUserInfo() { } ``` -#### React +### React For React projects, ensure the following environment variables are set in your deployment process: -* For JavaScript project, see [tab JavaScript sample.](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts/sso/InitTeamsFx.tsx#L12) +* For a JavaScript project, see [tab JavaScript sample.](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts/sso/InitTeamsFx.tsx#L12) -* For TypeScript project, see [tab TypeScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts) +* For a TypeScript project, see [tab TypeScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts) To update your source code, follow these steps: 1. Move the `auth-start.html` and `auth-end.html` files from the `auth/public` folder to the `public/` folder. These HTML files serve the purpose of handling authentication redirects. -1. Move `sso` folder under `auth/` to `src/sso/`: +1. Move `sso` folder under `auth/` to `src/sso/`. 1. `InitTeamsFx`: This file executes a function that initializes the TeamsFx SDK. After the SDK initialization, it opens the `GetUserProfile` component. - 1. `GetUserProfile`: This file executes a function, retrieving user information by invoking the Microsoft Graph API. + 1. `GetUserProfile`: This file executes a function to retrieve user information by invoking the Microsoft Graph API. 1. Import and add `InitTeamsFx` in `Welcome.*`. @@ -157,9 +159,7 @@ For more information, see [sample app.](https://github.com/OfficeDev/teams-toolk 1. Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json). -1. Add the downloaded app manifest code to `./aad.manifest.json` file. - -This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). +1. Add the downloaded app manifest code to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). ## Update Teams app manifest @@ -177,7 +177,7 @@ This allows you to customize different aspects of your app registration and upda > [!NOTE] > You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. -1. Register command in `commandLists`. +1. Register one or more commands in `commandLists`. The `commandLists` includes commands that your bot can suggest to users. If you're using the `teamsFx` bot template, set the following values: @@ -188,7 +188,7 @@ This allows you to customize different aspects of your app registration and upda } ``` -1. The `validDomains` field includes the domains for websites that the app loads within the Teams client. Update the following values: +1. The `validDomains` field includes the domains for websites that the app loads within the Teams client. Update the following value: ```bash "validDomains": [ @@ -196,11 +196,11 @@ This allows you to customize different aspects of your app registration and upda ] ``` -## Teams Toolkit configuration files +## Update Teams Toolkit configuration files -1. Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update necessary configurations related to Microsoft Entra into these files. +1. Locate your Teams Toolkit configuration files, such as `./teamsapp.yml` and `./teamsapp.local.yml`. Update necessary configurations related to Microsoft Entra in these files. -1. Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra apps used for SSO. For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate): +1. Add the following code `aadApp/create` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to create new Microsoft Entra apps used for SSO: ```yaml - uses: aadApp/create @@ -220,7 +220,9 @@ This allows you to customize different aspects of your app registration and upda > [!NOTE] > Replace the `name` value with the desired name for your Microsoft Teams app. -1. Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app. For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate): + For more information, see [`aadApp/create`.](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappcreate) + +1. Add the following code `aadApp/update` under `provision` in `./teamsapp.yml` and `./teamsapp.local.yml` to update your Microsoft Entra app: ```yaml - uses: aadApp/update @@ -232,6 +234,8 @@ This allows you to customize different aspects of your app registration and upda > [!NOTE] > Update the `manifestPath` value to the relative path of the Microsoft Entra app manifest template `aad.manifest.json`, if you've changed the file's path. + For more information, see [`aadApp/update`](https://github.com/OfficeDev/teams-toolkit/wiki/Available-actions-in-Teams-Toolkit#aadappupdate) + 1. Locate the `createOrUpdateEnvironmentFile` action in `teamsapp.local.yml` file and add the following environment variables: ```yaml @@ -275,7 +279,7 @@ To use the `teamsFx` tab or bot template, follow these steps: } ``` -1. Open `infra/azure.bicep` file, add the following code after `param location string = resourceGroup().location`: +1. Open `infra/azure.bicep` file and add the following code after `param location string = resourceGroup().location`: ```bicep param m365ClientId string @@ -286,7 +290,7 @@ To use the `teamsFx` tab or bot template, follow these steps: param m365ClientSecret string ``` -1. Add the following code before output in the `infra/azure.bicep` file: +1. Add the following code before `output` in the `infra/azure.bicep` file: ```bicep resource webAppSettings 'Microsoft.Web/sites/config@2021-02-01' = { @@ -313,9 +317,9 @@ To use the `teamsFx` tab or bot template, follow these steps: WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' ``` - ## Update Source Code +## Update Source Code - # [Bot](#tab/bot) +# [Bot](#tab/bot) 1. Move the files located in the `auth/sso` folder to `src`. The `ProfileSsoCommandHandler` class serves as an SSO command handler, designed to retrieve user information using an SSO token. You can adopt this method to develop your own SSO command handler. @@ -390,7 +394,7 @@ To use the `teamsFx` tab or bot template, follow these steps: }); ``` - # [Messaging extension](#tab/messaging-extension) +# [Messaging extension](#tab/messaging-extension) 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) From a73f33e18342e99e939c1726f7aabe9e6bca8e51 Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 16:43:20 +0530 Subject: [PATCH 21/25] Update develop-single-sign-on-experience-in-Teams.md --- ...elop-single-sign-on-experience-in-Teams.md | 160 +++++++++--------- 1 file changed, 76 insertions(+), 84 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 16d5cf8bb8a..b710397c635 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -317,9 +317,9 @@ To use the `teamsFx` tab or bot template, follow these steps: WEBSITE_NODE_DEFAULT_VERSION: '14.20.0' ``` -## Update Source Code + ## Update Source Code -# [Bot](#tab/bot) + # [Bot](#tab/bot) 1. Move the files located in the `auth/sso` folder to `src`. The `ProfileSsoCommandHandler` class serves as an SSO command handler, designed to retrieve user information using an SSO token. You can adopt this method to develop your own SSO command handler. @@ -331,70 +331,64 @@ To use the `teamsFx` tab or bot template, follow these steps: npm install copyfiles --save-dev ``` - 1. Replace the following command in `package.json` file: + 1. Update the following command in `package.json` file: - ```json - "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src", - ``` - - With - - ```json - "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/", - ``` + ```json + "build": "tsc --build && shx cp -r ./src/adaptiveCards ./lib/src && copyfiles src/public/*.html lib/", + ``` The HTML pages used for auth redirect are copied when building this bot project. 1. In `src/index` file, add the following command to import `isomorphic-fetch`: - ```bash - require("isomorphic-fetch"); - ``` + ```bash + require("isomorphic-fetch"); + ``` - 1. Add the following command to redirect to auth pages: + 1. Add the following command to redirect to auth pages: - ```bash - server.get( - "/auth-:name(start|end).html", - restify.plugins.serveStatic({ - directory: path.join(__dirname, "public"), - }) - ); - ``` + ```bash + server.get( + "/auth-:name(start|end).html", + restify.plugins.serveStatic({ + directory: path.join(__dirname, "public"), + }) + ); + ``` - 1. Update `commandApp.requestHandler` to ensure auth works with the following code: + 1. Update `commandApp.requestHandler` to ensure auth works with the following code: - ```bash - await commandApp.requestHandler(req, res).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; - } - }); - ``` + ```bash + await commandApp.requestHandler(req, res).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. Add `ssoConfig` and `ssoCommands` in conversation bot in `src/internal/initialize`: + 1. Add `ssoConfig` and `ssoCommands` in `ConversationBot` in `src/internal/initialize`: - ```bash - import { ProfileSsoCommandHandler } from "../profileSsoCommandHandler"; - - export const commandBot = new ConversationBot({ - ... - // To learn more about ssoConfig, please refer teamsfx sdk document: https://docs.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk - ssoConfig: { - aad :{ - scopes:["User.Read"], - }, - }, - command: { - enabled: true, - commands: [new HelloWorldCommandHandler() ], - ssoCommands: [new ProfileSsoCommandHandler()], - }, - }); - ``` + ```bash + import { ProfileSsoCommandHandler } from "../profileSsoCommandHandler"; + + export const commandBot = new ConversationBot({ + ... + // To learn more about ssoConfig, please refer teamsfx sdk document: https://docs.microsoft.com/microsoftteams/platform/toolkit/teamsfx-sdk + ssoConfig: { + aad :{ + scopes:["User.Read"], + }, + }, + command: { + enabled: true, + commands: [new HelloWorldCommandHandler() ], + ssoCommands: [new ProfileSsoCommandHandler()], + }, + }); + ``` -# [Messaging extension](#tab/messaging-extension) + # [Messaging extension](#tab/messaging-extension) 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension) @@ -404,66 +398,64 @@ To use the `teamsFx` tab or bot template, follow these steps: ```bash const path = require("path"); - + // Listen for incoming requests. server.post("/api/messages", async (req, res) => { - await adapter.process(req, res, async (context) => { - await bot.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; + await adapter.process(req, res, async (context) => { + await bot.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; } - }) + }) }); - + server.get( - "/auth-:name(start|end).html", - restify.plugins.serveStatic({ - directory: path.join(__dirname, "public"), - }) + "/auth-:name(start|end).html", + restify.plugins.serveStatic({ + directory: path.join(__dirname, "public"), + }) ); ``` - 1. Run the following command under `./` folder: + 1. Run the following commands under `./` folder: ```bash npm install @microsoft/teamsfx ``` - 1. Run the following command under `./` folder: - ```bash npm install isomorphic-fetch ``` 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. - 1. Install `copyfiles` npm packages in your TypeScript bot project, update the `build` script in `src/package.json` file as follows: + 1. Install `copyfiles` npm packages in your TypeScript bot project and update the `build` script in `src/package.json` file as follows: - ```bash + ```json "build": "tsc --build && copyfiles ./public/*.html lib/", ``` - The HTML pages used for auth redirect are copied when building this bot project. + The HTML pages used for auth redirect are copied when building this bot project. 1. Update `templates/appPackage/aad.template.json` file with the scopes you use in the `handleMessageExtensionQueryWithSSO` function: - ```bash + ```json "requiredResourceAccess": [ - { - "resourceAppId": "Microsoft Graph", - "resourceAccess": [ - { - "id": "User.Read", - "type": "Scope" - } - ] - } - ] + { + "resourceAppId": "Microsoft Graph", + "resourceAccess": [ + { + "id": "User.Read", + "type": "Scope" + } + ] + } + ] ``` - --- + --- --- From aa507d353ef97227d952c6b69acf323c8e5dca0c Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 16:47:24 +0530 Subject: [PATCH 22/25] Update develop-single-sign-on-experience-in-Teams.md --- ...develop-single-sign-on-experience-in-Teams.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index b710397c635..34f0b5b87f7 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -35,17 +35,17 @@ To enable SSO, configure your Teams app as follows: In the `./appPackages/manifest.json` file, add the following code: - ```json - "webApplicationInfo": { - "id": "${{AAD_APP_CLIENT_ID}}", - "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}" - } - ``` +```json +"webApplicationInfo": { + "id": "${{AAD_APP_CLIENT_ID}}", + "resource": "api://${{TAB_DOMAIN}}/${{AAD_APP_CLIENT_ID}}" +} +``` `webApplicationInfo` provides your Microsoft Entra App ID and Microsoft Graph information to assist users sign in to your app. - > [!NOTE] - > You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. +> [!NOTE] +> You can use `{{ENV_NAME}}` to reference variables in `env/.env.{TEAMSFX_ENV}` file. ## Update Teams Toolkit configuration files From da5cc3a69d9f8b93f7c812008d5bcfc34632950a Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 17:02:13 +0530 Subject: [PATCH 23/25] Update develop-single-sign-on-experience-in-Teams.md --- ...develop-single-sign-on-experience-in-Teams.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 34f0b5b87f7..3b266bed81c 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -29,7 +29,7 @@ To enable SSO, configure your Teams app as follows: 1. Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/tab/aad.manifest.template.json). -1. Add the downloaded app manifest code to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). +1. Add the downloaded app manifest template code to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). ## Update Teams app manifest @@ -89,7 +89,7 @@ In the `./appPackages/manifest.json` file, add the following code: 1. For a React project, update `cli/runNpmCommand` under `deploy`. -1. If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file. Then, add the following environment variable: +1. If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file and add the following environment variable: ```yaml env: @@ -97,7 +97,7 @@ In the `./appPackages/manifest.json` file, add the following code: REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html ``` -1. If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deployment in `teamsapp.local.yml` file and add the following environment: +1. If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deployment in `teamsapp.local.yml` file and add the following environment variable: ```yaml envs: @@ -112,7 +112,7 @@ With the above changes implemented, your environment is prepared. You can now up ### Vanilla JavaScript -Use the following code to retrieve the SSO token and user information: +For a tab app that doesn't uses React, use the following code as a basic example to obtain the SSO token: ```javascript function getSSOToken() { @@ -136,7 +136,7 @@ function getBasicUserInfo() { For React projects, ensure the following environment variables are set in your deployment process: -* For a JavaScript project, see [tab JavaScript sample.](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts/sso/InitTeamsFx.tsx#L12) +* For a JavaScript project, see [tab JavaScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/js) * For a TypeScript project, see [tab TypeScript sample.](https://github.com/OfficeDev/teams-toolkit/tree/main/packages/fx-core/templates/plugins/resource/aad/auth/tab/ts) @@ -151,7 +151,7 @@ To update your source code, follow these steps: 1. Import and add `InitTeamsFx` in `Welcome.*`. -For more information, see [sample app.](https://github.com/OfficeDev/teams-toolkit-samples/tree/dev/hello-world-tab-with-backend) +For more information, see [SSO enabled tab app.](https://github.com/OfficeDev/teams-toolkit-samples/tree/dev/hello-world-tab-with-backend) # [Bot/message extension app](#tab/message-extension-app) @@ -159,7 +159,7 @@ For more information, see [sample app.](https://github.com/OfficeDev/teams-toolk 1. Download the Microsoft Entra app manifest [template](https://github.com/OfficeDev/teams-toolkit/blob/dev/packages/fx-core/templates/plugins/resource/aad/manifest/bot/aad.manifest.template.json). -1. Add the downloaded app manifest code to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). +1. Add the downloaded app manifest template code to `./aad.manifest.json` file. This allows you to customize different aspects of your app registration and update the manifest as required. For more information, see [app manifest](/entra/identity-platform/reference-app-manifest). ## Update Teams app manifest @@ -437,7 +437,7 @@ To use the `teamsFx` tab or bot template, follow these steps: "build": "tsc --build && copyfiles ./public/*.html lib/", ``` - The HTML pages used for auth redirect are copied when building this bot project. + The HTML pages used for auth redirect are copied when building this bot project. 1. Update `templates/appPackage/aad.template.json` file with the scopes you use in the `handleMessageExtensionQueryWithSSO` function: From b0a8d03ae2553fba954eab59d04b11b3ece1d6ff Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 17:09:04 +0530 Subject: [PATCH 24/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index 3b266bed81c..a37b680860a 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -89,7 +89,7 @@ In the `./appPackages/manifest.json` file, add the following code: 1. For a React project, update `cli/runNpmCommand` under `deploy`. -1. If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file and add the following environment variable: +1. If you're building a tab app using the React framework in CLI, find the `cli/runNpmCommand` action with `build app` in the `teamsapp.yml` file and add the following environment variables: ```yaml env: @@ -97,7 +97,7 @@ In the `./appPackages/manifest.json` file, add the following code: REACT_APP_START_LOGIN_PAGE_URL: ${{TAB_ENDPOINT}}/auth-start.html ``` -1. If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deployment in `teamsapp.local.yml` file and add the following environment variable: +1. If you're building a tab app with React framework, find the `file/createOrUpdateEnvironmentFile` action for deployment in `teamsapp.local.yml` file and add the following environment variables: ```yaml envs: From c7000d57996be26b67d21417347a5d05c53df47a Mon Sep 17 00:00:00 2001 From: Vishnu Date: Tue, 17 Dec 2024 17:13:47 +0530 Subject: [PATCH 25/25] Update develop-single-sign-on-experience-in-Teams.md --- .../toolkit/develop-single-sign-on-experience-in-Teams.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md index a37b680860a..d331f5eb1af 100644 --- a/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md +++ b/msteams-platform/toolkit/develop-single-sign-on-experience-in-Teams.md @@ -388,7 +388,7 @@ To use the `teamsFx` tab or bot template, follow these steps: }); ``` - # [Messaging extension](#tab/messaging-extension) + # [Message extension](#tab/messaging-extension) 1. Implement the API key `handleMessageExtensionQueryWithSSO` in `TeamsActivityHandler.handleTeamsMessagingExtensionQuery`. For more information, see [SSO for message extensions.](https://github.com/OfficeDev/teams-toolkit/wiki/SSO-for-Message-Extension)