Updates from: 11/15/2022 02:52:28
Service Microsoft Docs article Related commit history on GitHub Change details
platform Build Apps For Teams Meeting Stage https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/apps-in-teams-meetings/build-apps-for-teams-meeting-stage.md
Last updated 04/07/2022
Share to stage allows users to share an app to the meeting stage from the meeting side panel in an ongoing meeting. This sharing is interactive and collaborative in comparison to passive screen sharing.
-To invoke share to stage, users can select the **Share to Stage** icon on the top right side of the meeting side panel. **Share to Stage** icon is native to Teams client and selecting it shares the entire app to the meeting stage.
+To invoke share to stage, users can select the **Share to Stage** icon on the upper-right side of the meeting side panel. **Share to Stage** icon is native to Teams client and selecting it shares the entire app to the meeting stage.
## App manifest settings for apps in meeting stage
To share an app to the meeting stage, you must configure the context and RSC per
1. Update the `context` property in the app manifest as follows: ```json
- "context":[
- "meetingSidePanel",
- "meetingStage"
- ]
+ "context": [
+ "meetingSidePanel",
+ "meetingStage"
+ ]
``` 2. Obtain the RSC permissions by configuring the `authorization` property, and the `name` and `type` in the `resourceSpecific` field as follows: ```json "authorization": {
- "permissions": {
+ "permissions": {
"resourceSpecific": [
- {
- "name": "MeetingStage.Write.Chat",
- "type": "Delegated"
- }
+ {
+ "name": "MeetingStage.Write.Chat",
+ "type": "Delegated"
+ }
]
- }
+ }
} ```
The following table includes the query parameters:
|Value|Type|Required|Description| |||-||
-|**callback**| String | Yes | Callback contains two parameters, error and result. The *error* can either contain an error of type *SdkError*, or null when share is successful. The *result* can either contain a true value, if there's a successful share, or null when the share fails. |
+|**callback**| String | Yes | Callback contains two parameters, error and result. The *error* can either contain an error of type *SdkError* or null when share is successful. The *result* can either contain a true value if there's a successful share or null when the share fails. |
|**appContentURL**| String | Yes | The URL that will be shared on to the stage. | ### Example
The following table includes the query parameter:
|Value|Type|Required|Description| |||-||
-|**callback**| String | Yes | Callback contains two parameters, error, and result. The *error* can either contain an error of type *SdkError*, in case of an error, or null when share is successful. The *result* can either contain an `IAppContentStageSharingState` object, when share is successful, or null, in case of an error.|
+|**callback**| String | Yes | Callback contains two parameters, error and result. The *error* can either contain an error of type *SdkError* in case of an error or null when share is successful. The *result* can either contain an `IAppContentStageSharingState` object when share is successful or null in case of an error.|
### Example
The JSON response body for the `getAppContentStageSharingState` API is:
```json {
- "isAppSharing":true
-}
+ "isAppSharing": true
+}
``` ### Response codes
The following table includes the query parameter:
|Value|Type|Required|Description| |||-||
-|**callback**| String | Yes | Callback contains two parameters, error, and result. The *error* can either contain an error of type *SdkError*, or null when share is successful. The result can either contain an `IAppContentStageSharingCapabilities` object, when share is successful, or null, in case of an error.|
+|**callback**| String | Yes | Callback contains two parameters, error and result. The *error* can either contain an error of type *SdkError* or null when share is successful. The result can either contain an `IAppContentStageSharingCapabilities` object, when share is successful or null in case of an error.|
### Example
To add a deep link to share content on stage, you need to have an app context. T
The query parameters for the app context are: * `appID`: This is the ID that can be obtained from the app manifest.
-* `appSharingUrl`: The URL which needs to be shared on stage should be a valid domain defined in the app manifest. If the URL isn't a valid domain, an error dialog will pop up to provide the user with a description of the error.
-* `useMeetNow`: This includes a boolean parameter that can be either true or false.
+* `appSharingUrl`: The URL, which needs to be shared on stage should be a valid domain defined in the app manifest. If the URL isn't a valid domain, an error dialog appears to provide the user with a description of the error.
+* `useMeetNow`: This includes a Boolean parameter that can be either true or false.
* **True**: When the `UseMeetNow` value is true and if there's no ongoing meeting, a new Meet now meeting will be initiated. When there's an ongoing meeting, this value will be ignored. * **False**: The default value of `UseMeetNow` is false, which means that when a deep link is shared to stage and there's no ongoing meeting, a calendar pop-up will appear. However, you can share directly during a meeting.
The query parameters for the app context are:
Ensure that all the query parameters are properly URI encoded and the app context has to be encoded twice in the final URL. Following is an example. ```json
-var appContext= JSON.stringify({ "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view", "appId": "9cc80a93-1d41-4bcb-8170-4b9ec9e29fbb", "useMeetNow":false })
-var encodedContext = encodeURIComponent(appcontext).replace(/'/g,"%27").replace(/"/g,"%22")
-var encodedAppContext = encodeURIComponent(encodedContext).replace(/'/g,"%27").replace(/"/g,"%22")
+var appContext= JSON.stringify({
+ "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view",
+ "appId": "9cc80a93-1d41-4bcb-8170-4b9ec9e29fbb", "useMeetNow":false
+}) var encodedContext = encodeURIComponent(appcontext).replace(/'/g,"%27").replace(/"/g,"%22") var encodedAppContext = encodeURIComponent(encodedContext).replace(/'/g,"%27").replace(/"/g,"%22")
``` A deep link can be launched either from the Teams web or from the Teams desktop client.
A deep link can be launched either from the Teams web or from the Teams desktop
|Deep link|Format|Example| ||||
- |To share the app and open Teams calendar, when UseMeeetNow is **false**, default.|`https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context}`|`https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Afalse%257D`|
- |To share the app and initiate instant meeting, when UseMeeetNow is **true**.|`https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context}`|`https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D`|
+ |To share the app and open Teams calendar, when `UseMeeetNow` is **false**, default.|`https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context}`|`https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Afalse%257D`|
+ |To share the app and initiate instant meeting, when `UseMeeetNow` is **true**.|`https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context}`|`https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D`|
* **Team desktop client**: Use the following format to launch a deep link from the Teams desktop client to share content on stage.
A deep link can be launched either from the Teams web or from the Teams desktop
|Deep link|Format|Example| ||||
- |To share the app and open Teams calendar, when UseMeeetNow is **false**, default.|`msteams:/l/meeting-share? deeplinkId={deeplinkid}&fqdn={fqdn}&lm=deeplink%22&appContext={encoded app context}`|`msteams:/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Afalse%257D`|
- |To share the app and initiate instant meeting, when UseMeeetNow is **true**.|`msteams:/l/meeting-share? deeplinkId={deeplinkid}&fqdn={fqdn}&lm=deeplink%22&appContext={encoded app context}`|`msteams:/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D`|
+ |To share the app and open Teams calendar, when `UseMeeetNow` is **false**, default.|`msteams:/l/meeting-share? deeplinkId={deeplinkid}&fqdn={fqdn}&lm=deeplink%22&appContext={encoded app context}`|`msteams:/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Afalse%257D`|
+ |To share the app and initiate instant meeting, when `UseMeeetNow` is **true**.|`msteams:/l/meeting-share? deeplinkId={deeplinkid}&fqdn={fqdn}&lm=deeplink%22&appContext={encoded app context}`|`msteams:/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D`|
The query parameters are:
You can build an in-meeting app for enabling meeting participants to sign docume
You can use an in-meeting signing app to: -- Add documents to be reviewed during a meeting-- Share documents to be reviewed to main stage-- Sign documents using the signerΓÇÖs identity
+* Add documents to be reviewed during a meeting
+* Share documents to be reviewed to main stage
+* Sign documents using the signerΓÇÖs identity
The participants can review and sign documents, such as purchase agreements and purchase orders.
The participants can review and sign documents, such as purchase agreements and
The following participant roles may be involved during the meeting: -- **Document creator**: This role can add their own documents to be reviewed and signed.-- **Signer**: This role can sign reviewed documents.-- **Reader**: This role can view the documents added to the meeting.
+* **Document creator**: This role can add their own documents to be reviewed and signed.
+* **Signer**: This role can sign reviewed documents.
+* **Reader**: This role can view the documents added to the meeting.
## Code sample |Sample name | Description | C# | Node.js | |-|--|--|-|
-|Meeting stage sample | Sample app to show a tab in meeting stage for collaboration | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/meetings-stage-view/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/meetings-stage-view/nodejs) |
+|Meeting stage sample | Sample app to show a tab in meeting stage for collaboration. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/meetings-stage-view/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/meetings-stage-view/nodejs) |
| In-meeting notification | Demonstrates how to implement in-meeting notification using bot. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/meetings-content-bubble/csharp) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/meetings-content-bubble/nodejs) |
-| In-meeting document signing | Demonstrates how to implement a document signing Teams app. Includes sharing specific app content to stage, Teams SSO and user specific stage view. | [View](https://github.com/officedev/microsoft-teams-samples/tree/main/samples/meetings-share-to-stage-signing/csharp) | NA |
+| In-meeting document signing | Demonstrates how to implement a document signing Teams app. Includes sharing specific app content to stage, Teams SSO, and user specific stage view. | [View](https://github.com/officedev/microsoft-teams-samples/tree/main/samples/meetings-share-to-stage-signing/csharp) | NA |
## Step-by-step guide
platform Channel And Group Conversations https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/bots/how-to/conversations/channel-and-group-conversations.md
Bots in a group or channel only receive messages when they're mentioned @botname
See the following video to learn about channel and group chat conversations with a bot: <br>
-> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/RE4NzEs]
+> [!VIDEO <https://www.microsoft.com/en-us/videoplayer/embed/RE4NzEs>]
<br> ## Design guidelines
Don't send a message in the following cases:
## Step-by-step guide
-Follow the [step-by-step guide](../../../sbs-teams-conversation-bot.yml), to create a Teams conversational bot.
+Follow the [step-by-step guide](../../../sbs-teams-conversation-bot.yml), create Teams conversation bot.
## Next step
platform Extend M365 Teams Personal Tab https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/m365-apps/extend-m365-teams-personal-tab.md
If you used Teams Toolkit to create your personal app, you can also use it to va
## Update SDK references
-To run in Outlook and Office, your app needs to refer the npm package `@microsoft/teams-js@2.0.0` (or higher). While code with downlevel versions is supported in Outlook and Office, deprecation warnings are logged, and support for downlevel versions of TeamsJS in Outlook and Office will eventually cease.
+To run in Outlook and Office, your app needs to refer the npm package `@microsoft/teams-js@2.5.0` (or higher). While code with downlevel versions is supported in Outlook and Office, deprecation warnings are logged, and support for downlevel versions of TeamsJS in Outlook and Office will eventually cease.
-You can use Teams Toolkit to help identify and automate the required code changes to upgrade from 1.x TeamsJS versions to TeamsJS version 2.x.x. Alternately, you can perform the same steps manually; refer to [Microsoft Teams JavaScript client SDK](../tabs/how-to/using-teams-client-sdk.md#whats-new-in-teamsjs-version-20) for details.
+You can use Teams Toolkit to help identify and automate the required code changes to upgrade from 1.x TeamsJS versions to TeamsJS 2.x.x versions. Alternately, you can perform the same steps manually; refer to [Microsoft Teams JavaScript client SDK](../tabs/how-to/using-teams-client-sdk.md#whats-new-in-teamsjs-version-20) for details.
1. Open the *Command palette*: `Ctrl+Shift+P`. 1. Run the command `Teams: Upgrade Teams JS SDK and code references`.
platform Add Single Sign On https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/add-single-sign-on.md
Title: Add single sign-on to your Teams apps-+ description: In this module, learn how to add single sign-on (SSO) of Teams Toolkit, enable SSO support, update your application to use SSO-+ ms.localizationpriority: medium Last updated 05/20/2022
+zone_pivot_groups: teams-app-platform
# Add single sign-on to Teams app
-Microsoft Teams provides single sign-on function for application to obtain signed-in Teams user token to access Microsoft Graph and other APIs. Teams Toolkit facilitates the interaction by abstracting some of the Azure AD flows and integrations behind some simple APIs. This enables you to add single sign-on (SSO) features easily to your Teams application.
+Microsoft Teams provides single sign-on (SSO) function for application to obtain signed-in Teams user token to access Microsoft Graph and other APIs. Teams Toolkit facilitates the interaction by abstracting some of the Microsoft Azure Active Directory (Azure AD) flows and integrations behind some simple APIs. This enables you to add SSO features easily to your Teams application
-For applications that interact with the user in a chat, a Team, or a channel, SSO manifests as an Adaptive Card, which the user can interact with to invoke the Azure AD consent flow.
+
+## Add SSO to Teams app for Visual Studio Code
+
+For applications that interact with the user in a chat, Team, or channel, SSO manifests as an Adaptive Card, which the user can interact with to invoke the Azure AD consent flow.
## Enable SSO support
-Teams Toolkit helps you to add SSO to the following Teams capabilities:
+Teams Toolkit helps you to add SSO to the following Teams capabilities in Visual Studio Code:
* Tab * Bot
Teams Toolkit helps you to add SSO to the following Teams capabilities:
### Add SSO using Visual Studio Code
-To add SSO using Teams Toolkit in Visual Studio Code, follow these steps:
+You can perform the following steps to add SSO using Teams Toolkit in Visual Studio Code:
1. Open **Microsoft Visual Studio Code**. 2. Select Teams Toolkit :::image type="content" source="~/assets/images/teams-toolkit-v2/teams-toolkit-sidebar-icon.png" alt-text="Screenshot is an example of the Teams Toolkit option in Visual Studio Code."::: from left navigation bar.
To enable SSO in your application, follow these steps:
#### Set up the Azure AD redirects
-1. Move the `auth/bot/public` folder to `bot/src`. This folder contains HTML pages that the bot application hosts. When single sign-on flow is initiated with Azure AD, it redirects the user to the HTML pages.
+1. Move the `auth/bot/public` folder to `bot/src`. This folder contains HTML pages that the bot application hosts. When SSO flow is initiated with Azure AD, it redirects the user to the HTML pages.
1. Modify your `bot/src/index` to add the appropriate `restify` routes to HTML pages. ```ts
For more information about TeamsFx SDK, see:
* [TeamsFx SDK](TeamsFx-SDK.md) or [API reference](/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true) * [Microsoft Teams Framework (TeamsFx) Sample Gallery](https://github.com/OfficeDev/TeamsFx-Samples/tree/v2) ++
+## Add SSO to Teams app for Visual Studio
+
+For applications that interact with the user in a chat, Team, or channel, SSO manifests as an Adaptive Card, which the user can interact with to invoke the Azure AD consent flow.
+
+**Advantages**
+
+The following are the advantages of SSO in Teams:
+
+* SSO with Azure AD refreshes the authentication token in the background, which minimizes the number of times users need to enter their sign-in credentials.
+
+* SSO signs-in the user in different devices automatically, while using the app.
+
+Teams tabs and bots have similar flow for SSO support, for more information, see:
+
+1. [SSO authentication in Tabs](../tabs/how-to/authentication/tab-sso-overview.md)
+2. [SSO authentication in Bots](../bots/how-to/authentication/auth-aad-sso-bots.md)
+
+## Enable SSO support
+
+Teams Toolkit helps you add SSO to the following Teams capabilities in Visual Studio:
+
+* Tab
+* Notification bot: Restify server
+* Command bot
+
+### Add SSO using Visual Studio
+
+You can perform the following steps to add SSO using Teams Toolkit in Visual Studio:
+
+1. Open **Visual Studio** and select **Create a new project**.
+
+ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-create-proj.png" alt-text="open visual studio code to create a new project" lightbox="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-create-proj.png":::
+
+1. Select **Microsoft Teams app** project by searching for **teams** in the search box and select **Next**.
+
+ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-select-teams.png" alt-text="Select a Microsoft teams project by searching for teams." lightbox="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-select-teams.png":::
+
+1. Under **Create a new Teams application** select the required **application type**, clear the **Configure with single sign-on** check box.
+
+1. Select **create**.
+
+ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-create-teamsapp-sso-uncheck.png" alt-text="select the teams app to be created and uncheck sso check box" lightbox="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-create-teamsapp-sso-uncheck.png":::
+
+1. Enter your **Project name** and **Solution name**.
+1. Select **Create**.
+
+ > [!NOTE]
+ > You can also change the default location of your project by selecting &#x25CF;&#x25CF;&#x25CF;.
+
+ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-create-teamsapp.png" alt-text="enter project and solution name" lightbox="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-create-teamsapp.png":::
+
+1. After the project is created, select **Project** > **Teams Toolkit** > **Add Authentication Code**.
+
+ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-add-auth-code.png" alt-text="Add authentication code" lightbox="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-add-auth-code.png":::
+
+## Customize your project using Teams Toolkit
+
+The following table lists the changes by Teams Toolkit:
+
+ |**Type**|**File**|**Purpose**|
+ |--|--|--|
+ |Create|`aad.template.json` under `template/appPackage`|Azure AD application manifest represents your Azure AD app. `template/appPackage` helps you to register an Azure AD app during local debug or provision.|
+ |Modify|`manifest.template.json` under `template/appPackage`|`webApplicationInfo` object is added into your Teams app manifest template. Teams requires this field to enable SSO. When local debug or provision is triggered, you can see the change.|
+ |Modify|`appsettings.json` and `appsettings.Development.json`|Configs are added and used by TeamsFx SDK to your app settings. You can update and add the `TeamsFx` object if you have other `appsettings` files.|
+ |Create|`Auth/tab`|Reference code, auth redirect pages and a `README.md` file are generated in the folder `Auth/tab` for a tab project.|
+ |Create|`Auth/bot`|Reference code, auth redirect pages and a `README.md` file are generated in the folder `Auth/bot` for a bot project.|
+
+> [!NOTE]
+> Teams Toolkit makes no changes in the cloud by adding SSO, until you trigger a local debug. You can update your code to ensure SSO is working in the project.
+
+## Update your application to use SSO
+
+The following steps help you to enable SSO in your application:
+
+> [!NOTE]
+> The changes are based on the scaffold templates.
++
+<br>
+<br><details>
+<summary><b>Tab project
+</b></summary>
+
+1. You can move `GetUserProfile.razor` file from the `Auth/tab` folder to the`Components/` folder. `GetUserProfile` file implements a function that uses TeamsFx SDK to call Microsoft Graph API to get the user info.
+
+1. After getting the user info, you can replace `<AddSSO />` with `<GetUserProfile />` in the `Components/Welcome.razor` file.
+
+</details>
+<details>
+<summary><b>Bot project
+</b></summary>
+
+1. Ensure to upgrade your SDK version to:
+ * TeamsFx, version 1.1.0 or later.
+ * `Microsoft.Bot.Builder`, version 4.17.1 or later.
+
+2. You can create a `Pages` folder, and move files to the `Auth/bot/Pages`, which contains HTML pages that are hosted by bot application. When SSO authentication process is initiated with Azure AD, they redirect user to the HTML pages.
+
+3. After the user is redirected to the HTML pages, you can create `SSO` folder and move files in `Auth/bot/SSO`. This folder contains three files as a reference for SSO implementation:
+
+ * `SsoDialog.cs`: This file creates a `ComponentDialog` that is used for SSO.
+
+ * `SsoOperations.cs`: This file implements a class in the function to get user info with SSO token. You can follow the method defined in `SsoOperations.cs` and create your own method, that requires SSO token.
+
+ * `TeamsSsoBot.cs`: This file creates a `TeamsActivityHandler` with `SsoDialog` that adds and triggers a command `showUserInfo`.
+
+ > [!NOTE]
+ > Ensure to replace `{Your_NameSpace}` with your project namespace in the three files (`SsoDialog.cs`, `SsoOperations.cs`, and `TeamsSsoBot.cs`).
+
+ :::image type="content" source="../assets/images/teams-toolkit-v2/add-sso-vs/vs-2022-preview-replace-namespace.png" alt-text="Replace name space with the your name space":::
+
+4. You can now update `Program.cs`.
+
+ 1. You can find the following code in the file `Program.cs`, and add the code blocks in step b:
+
+ ```csharp
+ builder.Services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
+ ```
+
+ 1. Add the following code blocks:
+
+ ```csharp
+ builder.Services.AddRazorPages();
+ // Create the Bot Framework Adapter with error handling enabled.
+ builder.Services.AddSingleton<IBotFrameworkHttpAdapter, AdapterWithErrorHandler>();
+ builder.Services.AddSingleton<IStorage, MemoryStorage>();
+ // Create the Conversation state. (Used by the Dialog system itself.)
+ builder.Services.AddSingleton<ConversationState>();
+ // The Dialog that will be run by the bot.
+ builder.Services.AddSingleton<SsoDialog>();
+ // Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
+ builder.Services.AddTransient<IBot, TeamsSsoBot<SsoDialog>>();
+ builder.Services.AddOptions<AuthenticationOptions>().Bind(builder.Configuration.GetSection("TeamsFx").GetSection(AuthenticationOptions.Authentication)).ValidateDataAnnotations();
+ builder.Services.AddOptions<BotAuthenticationOptions>().Configure<IOptions<AuthenticationOptions>>((botAuthOption, authOptions) => {
+ AuthenticationOptions authOptionsValue = authOptions.Value;
+ botAuthOption.ClientId = authOptionsValue.ClientId;
+ botAuthOption.ClientSecret = authOptionsValue.ClientSecret;
+ botAuthOption.OAuthAuthority = authOptionsValue.OAuthAuthority;
+ botAuthOption.ApplicationIdUri = authOptionsValue.ApplicationIdUri;
+ botAuthOption.InitiateLoginEndpoint = authOptionsValue.Bot.InitiateLoginEndpoint;
+ }).ValidateDataAnnotations();
+ ```
+
+ 1. After you've added the code blocks, you can find and delete the following code in the file:
+
+ ```csharp
+ // Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
+ builder.Services.AddTransient<IBot, TeamsBot>();
+ ```
+
+ 1. Find the following code and replace it with the codes given in step e:
+
+ ```csharp
+ app.UseEndpoints(endpoints =>
+ {
+ endpoints.MapControllers();
+ });
+ ```
+
+ 1. Replace the codes in step d with the following codes:
+
+ ```csharp
+ app.UseEndpoints(endpoints =>
+ {
+ endpoints.MapControllers();
+ endpoints.MapRazorPages();
+ });
+ ```
+
+5. You can open `Templates/appPackage/manifest.template.json`, and add the following lines under `command` in `commandLists` of your bot to register your command in the Teams app manifest:
+
+ ```JSON
+ {
+ "title": "show",
+ "description": "Show user profile using Single Sign On feature"
+ }
+ ```
+
+</details>
+<details>
+<summary><b>Add a new command to the bot
+</b></summary>
+
+The following steps help you to add a new command, after you've added SSO in your project:
+
+> [!NOTE]
+> The instructions apply only to command bot.
+
+1. You can create a new method in class `SsoOperations` in `SSO/SsoOperations` and add your own business logic to call Graph API:
+
+ ```csharp
+ public static async Task GetUserImageInfo(ITurnContext stepContext, string token, BotAuthenticationOptions botAuthOptions)
+ {
+ await stepContext.SendActivityAsync("Retrieving user information from Microsoft Graph ...");
+ var authProvider = new DelegateAuthenticationProvider((request) =>
+ {
+ request.Headers.Authorization =
+ new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);
+ return Task.CompletedTask;
+ });
+ var graphClient = new GraphServiceClient(authProvider);
+ // You can add following code to get your photo size:
+ // var photo = await graphClient.Me.Photo.Request().GetAsync();
+ // await stepContext.SendActivityAsync($"Size of your photo is: {photo.Width} * {photo.Height}");
+ }
+ ```
+
+1. Find the following line to register a new command:
+
+ ```csharp
+ ((SsoDialog)_dialog).addCommand("showUserInfo", "show", SsoOperations.ShowUserInfo);
+ ```
+
+1. You can register the new command `"photo"` to configure the method `'GetUserImageInfo'` by adding the following code:
+
+ ```csharp
+ ((SsoDialog)_dialog).addCommand("getUserImageInfo", "photo", SsoOperations.GetUserImageInfo);
+ ```
+
+1. Open the file `templates/appPackage/manifest.template.json`, and add the following lines under `command` in `commandLists` of your bot to register your command in the Teams app manifest:
+
+ ```JSON
+ {
+ "title": "photo",
+ "description": "Show user photo size using Single Sign On feature"
+ }
+ ```
+
+</details>
+<br>
+
+ > [!NOTE]
+ > Teams Toolkit uses the Azure AD manifest file to register an Azure AD application for SSO. You need to press F5 to debug your application and test your SSO configuration.
+
+## Customize Azure AD application registration
+
+The [Azure AD app manifest](/azure/active-directory/develop/reference-app-manifest) allows you to customize various aspects of application registration. You can update the manifest file as needed. If you need to include additional API permissions to access your required APIs, see [API permissions to access your desired APIs](https://github.com/OfficeDev/TeamsFx/wiki/#customize-aad-manifest-template).
+For more information on viewing your Azure AD application in Azure Portal, see [how to view Azure AD application in Azure portal](https://github.com/OfficeDev/TeamsFx/wiki/Manage-AAD-application-in-Teams-Toolkit#How-to-view-the-AAD-app-on-the-Azure-portal).
+
+### Simplified SSO with TeamsFx
+
+TeamsFx helps to reduce your tasks by using SSO and accessing cloud resources down to single line statements with zero configuration. With TeamsFx SDK, you can write user authentication code with the user identity `TeamsUserCredential`, such as in a browser environment.
+
+For more information on TeamsFx SDK, see:
+
+* [TeamsFx SDK](TeamsFx-SDK.md) or [API reference](/javascript/api/@microsoft/teamsfx/?view=msteams-client-js-latest&preserve-view=true)
+* [Microsoft Teams Framework (TeamsFx) Sample Gallery](https://github.com/OfficeDev/TeamsFx-Samples/tree/v2)
+
+## How to use an existing Azure AD app
+
+To use an existing Azure AD app in your TeamsFx project, you can perform the following [steps](https://github.com/OfficeDev/TeamsFx/wiki/Using-existing-Azure-AD-app-in-TeamsFx-project).
++ ## See also
-[Prerequisites for creating your Teams app](tools-prerequisites.md)
+* [Prerequisites for creating your Teams app](tools-prerequisites.md)
+* [Prepare Accounts to build your Teams app](tools-prerequisites.md#accounts-to-build-your-teams-app)
platform Provision https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/toolkit/provision.md
zone_pivot_groups: teams-app-platform
# Provision cloud resources
-TeamsFx integrates with Azure and Microsoft 365 cloud, which allows you to place your application in Azure with a single command. TeamsFx integrates with Azure Resource Manager that enables you to provision Azure resources, which your application needs for code approach.
+TeamsFx integrates with Azure and the Microsoft 365 cloud, which allows you to place your application in Azure with a single command. TeamsFx integrates with Azure Resource Manager (ARM), which enables you to provision Azure resources that your application needs for code approach.
::: zone pivot="visual-studio-code" ## Provision using Teams Toolkit in Visual Studio Code
-Provision is performed with single command in Teams Toolkit for Visual Studio Code or TeamsFx CLI. For more information, see [Provision Azure-based app](/microsoftteams/platform/sbs-gs-javascript?tabs=vscode%2Cvsc%2Cviscode%2Cvcode&tutorial-step=8)
+Provision is performed with a single command in Teams Toolkit for Visual Studio Code or TeamsFx CLI. For more information, see [provision Azure-based app](/microsoftteams/platform/sbs-gs-javascript?tabs=vscode%2Cvsc%2Cviscode%2Cvcode&tutorial-step=8)
## Create Resources
-When you trigger provision command in Teams Toolkit or TeamsFx CLI, you can get the following resources:
+When you trigger the provision command in Teams Toolkit or TeamsFx CLI, you can get the following resources:
* Microsoft Azure Active Directory (Azure AD) application under your Microsoft 365 tenant. * Teams app registration under your Microsoft 365 tenant's Teams platform.
When you trigger provision command in Teams Toolkit or TeamsFx CLI, you can get
When you create a new project, you can use all the Azure resources. The ARM template defines all the Azure resources and helps to create required Azure resources during provision. When you [add new capability resource](./add-resource.md) to an existing project, the updated ARM template reflects the latest change. > [!NOTE]
-> Azure services incur costs in your subscription, for more information on cost estimation, see [the pricing calculator](https://azure.microsoft.com/pricing/calculator/).
+> Azure services incur costs in your subscription. For more information on cost estimation, see [pricing calculator](https://azure.microsoft.com/pricing/calculator/).
The following list shows the resource creation for different types of app and Azure resources: <br>
The following list shows the resource creation for different types of app and Az
|Resource|Purpose|Description | |-|--|--| | Azure storage | Host your tab app | Enables static web app feature to host your tab app |
-| App service plan for simple auth | Host the web app of Simple Auth |Not applicable |
-| Web app for simple auth | Host simple auth server to gain access to other services in your single page application | Adds user assigned identity to access other Azure resources |
| User assigned identity | Authenticate Azure service-to-service requests | Shared across different capabilities and resources | </details>
The following list shows the resource creation for different types of app and Az
|Resource|Purpose| Description| |-|--|--| | App service plan for function app | Host the function app |Not applicable |
-| Function app | Host your Azure functions APIs | Adds user assigned identity to access other Azure resources. <br /> Adds Cross-origin resource sharing (CORS) rule to allow requests from your tab app <br /> Adds authentication setting that only allows requests from your Teams app. <br /> Adds app settings required by [TeamsFx SDK](https://www.npmjs.com/package/@microsoft/teamsfx) |
+| Function app | Host your Azure functions APIs | Adds a user assigned identity to access other Azure resources. <br /> Adds cross-origin resource sharing (CORS) rule to allow requests from your tab app <br /> Adds an authentication setting that only allows requests from your Teams app. <br /> Adds app settings required by [TeamsFx SDK](https://www.npmjs.com/package/@microsoft/teamsfx) |
| Azure storage for function app | Required to create function app |Not applicable| | User assigned identity | Authenticate Azure service-to-service requests | Shared across different capabilities and resources |
The following list shows the resource creation for different types of app and Az
|-|--| | Azure AD application for API management service | Allows Microsoft Power Platform access APIs managed by API management service | | API management service | Manage your APIs hosted in function app |
-| API management product | Group your APIs, define terms of use and runtime policies |
+| API management product | Group your APIs, define terms of use, and runtime policies |
| API management OAuth server | Enables Microsoft Power Platform to access your APIs hosted in function app | | User assigned identity | Authenticate Azure service-to-service requests |
The following list shows the resource creation for different types of app and Az
|Resources|Purpose of this resource| |-|--|
-| Azure Key Vault Service | Manage secrets (e.g. Azure AD app client secret) used by other Azure Services |
+| Azure Key Vault Service | Manage secrets (for example, Azure AD app client secret) used by other Azure services |
| User Assigned Identity | Authenticate Azure service-to-service requests | </details>
The following list shows the resource creation for different types of app and Az
## Customize resource provision
-Teams Toolkit enables you to use an infrastructure-as-code approach to define Azure resources that you want to provision, and how you want to configure. The tool uses ARM template to define Azure resources. The ARM template is a set of bicep files that defines the infrastructure and configuration for your project. You can customize Azure resources by modifying the ARM template. For more information, see [bicep document](/azure/azure-resource-manager/bicep).
+Teams Toolkit enables you to use an infrastructure-as-code approach to define the Azure resources that you want to provision and how you want to configure. The tool uses the ARM template to define Azure resources. The ARM template is a set of bicep files that defines the infrastructure and configuration for your project. You can customize Azure resources by modifying the ARM template. For more information, see [bicep document](/azure/azure-resource-manager/bicep).
-Provision with ARM involves changing the following sets of files, parameters and templates:
+Provision with ARM involves changing the following sets of files, parameters, and templates:
* ARM parameter files (`azure.parameters.{your_env_name}.json`) located at `.fx/configs` folder, for passing parameters to templates. * ARM template files located at `templates/azure`, this folder contains following files:
-| File | Function | Allow customization |
-| | | |
-| main.bicep | Provide entry point for Azure resource provision | Yes |
-| provision.bicep | Create and configure Azure resources | Yes |
-| config.bicep | Add TeamsFx required configurations to Azure resources | Yes |
-| provision/xxx.bicep | Create and configure each Azure resource consumed by `provision.bicep` | Yes |
-| teamsfx/xxx.bicep | Add TeamsFx required configurations to each Azure resource consumed by `config.bicep`| No |
+ | File | Function | Allow customization |
+ | | | |
+ | main.bicep | Provide an entry point for Azure resource provision | Yes |
+ | provision.bicep | Create and configure Azure resources | Yes |
+ | config.bicep | Add TeamsFx required configurations to Azure resources | Yes |
+ | provision/xxx.bicep | Create and configure each Azure resource consumed by `provision.bicep` | Yes |
+ | teamsfx/xxx.bicep | Add TeamsFx required configurations to each Azure resource consumed by `config.bicep`| No |
> [!NOTE]
-> When you add resources or capabilities to your project, `teamsfx/xxx.bicep` will be regenerated, you can't customize the same. To modify the bicep files, you can use Git to track your changes to `teamsfx/xxx.bicep` files, which helps you to not lose changes while adding resources or capabilities.
+> When you add resources or capabilities to your project, `teamsfx/xxx.bicep` is regenerated, you can't customize the same. To modify the bicep files, you can use Git to track your changes to `teamsfx/xxx.bicep` files, which helps you not lose changes while adding resources or capabilities.
### Azure AD parameters
-The ARM template files use placeholders for parameters. The purpose of these placeholders is to ensure creation of new resources for you in new environment. The actual values are resolved from `.fx/states/state.{env}.json`.
+The ARM template files use placeholders for parameters. The purpose of the placeholders is to ensure the creation of new resources for you in new environment. The actual values are resolved from `.fx/states/state.{env}.json`.
+
+There are two types of parameters such as:
-There are two types of parameters such as Azure AD application related parameters and Azure resource-related parameters.
+* [Azure AD application-related parameters](#azure-ad-application-related-parameters)
+* [Azure resource-related parameters](#azure-resource-related-parameters)
##### Azure AD application-related parameters | Parameter name | Default value place holder | Meaning of the place holder | How to customize | | | | | |
-| Microsoft 365 ClientId | {{state.fx-resource-aad-app-for-teams.clientId}} | Your app's Azure AD app client id created during provision | [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot) |
-| Microsoft 365 ClientSecret | {{state.fx-resource-aad-app-for-teams.clientSecret}} | Your app's Azure AD app client secret created during provision | [Use an existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app) |
-| Microsoft 365 TenantId | {{state.fx-resource-aad-app-for-teams.tenantId}} | Tenant Id of your app's Azure AD app | [Use an existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app) |
-| Microsoft 365 OAuthAuthorityHost | {{state.fx-resource-aad-app-for-teams.oauthHost}} | OAuth authority host of your app's Azure AD app | [Use an existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app) |
-| botAadAppClientId | {{state.fx-resource-bot.botId}} | Bot's Azure AD app client Id created during provision | [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot) |
-| botAadAppClientSecret | {{state.fx-resource-bot.botPassword}} | Bot's Azure AD app client secret created during provision | [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot) |
+| Microsoft 365 ClientId | `{{state.fx-resource-aad-app-for-teams.clientId}}` | Your app's Azure AD app client Id is created during provision | [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot) |
+| Microsoft 365 ClientSecret | `{{state.fx-resource-aad-app-for-teams.clientSecret}}` | Your app's Azure AD app client secret is created during provision | [Use an existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app) |
+| Microsoft 365 TenantId | `{{state.fx-resource-aad-app-for-teams.tenantId}}` | Tenant Id of your app's Azure AD app | [Use an existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app) |
+| Microsoft 365 OAuthAuthorityHost | `{{state.fx-resource-aad-app-for-teams.oauthHost}}` | OAuth authority host of your app's Azure AD app | [Use an existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app) |
+| botAadAppClientId | `{{state.fx-resource-bot.botId}}` | Bot's Azure AD app client Id created during provision | [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot) |
+| botAadAppClientSecret | `{{state.fx-resource-bot.botPassword}}` | Bot's Azure AD app client secret is created during provision | [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot) |
##### Azure resource-related parameters | Parameter name | Default value place holder | Meaning of the place holder | How to customize | | | | | |
-| azureSqlAdmin | {{state.fx-resource-azure-sql.admin}} | Azure SQL Server admin account you provided during provision | Delete the placeholder and fill the actual value |
-| azureSqlAdminPassword | {{state.fx-resource-azure-sql.adminPassword}} | Azure SQL Server admin password you provided during provision | Delete the placeholder and fill the actual value |
+| azureSqlAdmin | `{{state.fx-resource-azure-sql.admin}}` | Azure SQL Server admin account you provided during provision | Delete the placeholder and fill the actual value |
+| azureSqlAdminPassword | `{{state.fx-resource-azure-sql.adminPassword}}` | Azure SQL Server admin password you provided during provision | Delete the placeholder and fill the actual value |
#### Referencing environment variables in parameter files
-If you don't want to hardcode the values in parameter files, for example, when the value is a secret. The parameter files support referencing the values from environment variables. You can use syntax `{{$env.YOUR_ENV_VARIABLE_NAME}}` in parameter values for the tool to resolve from current environment variable.
+If you don't want to hardcode the values in parameter files, for example, when the value is a secret. The parameter files support referencing the values from environment variables. You can use the syntax `{{$env.YOUR_ENV_VARIABLE_NAME}}` in parameter values for the tool to resolve the current environment variable.
-The following example reads the value of `mySelfHostedDbConnectionString` parameter from environment variable `DB_CONNECTION_STRING`:
+The following example reads the value of the `mySelfHostedDbConnectionString` parameter from the environment variable `DB_CONNECTION_STRING`:
```json ...
The following example reads the value of `mySelfHostedDbConnectionString` parame
#### Customize ARM template files
-If the predefined templates doesn't meet your application requirement, you can customize the ARM templates under `templates/azure` folder. For example, you can customize the ARM template to create some additional Azure resources for your app. You need to have basic knowledge of bicep language, which is used to author ARM template. You can get started with bicep at [bicep documentation](/azure/azure-resource-manager/bicep/).
+If the predefined templates doesn't meet your application requirement, you can customize the ARM templates under `templates/azure` folder. For example, you can customize the ARM template to create some additional Azure resources for your app. You need to have basic knowledge of the bicep language, which is used to author ARM template. You can get started with bicep at [bicep documentation](/azure/azure-resource-manager/bicep/).
> [!NOTE] > The ARM template is shared by all environments. You can use [conditional deployment](/azure/azure-resource-manager/bicep/conditional-resource-deployment) if the provision behavior varies between environments.
If the predefined templates doesn't meet your application requirement, you can c
To ensure the TeamsFx tool functions properly, ensure you customize ARM template, which satisfies the following requirement. If you use other tool for further development, you can ignore these requirements. * Keep the folder structure and file name unchanged. The tool may append new content to existing files when you add more resources or capabilities to your project.
-* Keep the name of auto-generated parameters as well as its property names unchanged. The auto-generated parameters may be used when you add more resources or capabilities to your project.
-* Keep the output of auto-generated ARM template unchanged. You can add additional outputs to ARM template. The output is `.fx/states/state.{env}.json` and can be used in other features such as deploy, validate manifest file.
+* Keep the names of the auto-generated parameters and its property names unchanged. The auto-generated parameters may be used when you add more resources or capabilities to your project.
+* Keep the output of the auto-generated ARM template unchanged. You can add additional outputs to the ARM template. The output is `.fx/states/state.{env}.json` and can be used in other features such as deploy, validate manifest file.
### Customization scenarios You can customize the following scenarios:
+* [Use and existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app)
+* [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot-1)
+ #### Use an existing Azure AD app for your Teams app
-You can add following configuration snippet to `.fx/configs/config.{env}.json` file to use an Azure AD app created by yourself for your Teams app. To create an Azure AD app, see <https://aka.ms/teamsfx-existing-aad-doc>.
+You can add the following configuration snippet to `.fx/configs/config.{env}.json` file to use an Azure AD app created by yourself for your Teams app. To create an Azure AD app, see <https://aka.ms/teamsfx-existing-aad-doc>.
```json "auth": {
You can add following configuration snippet to `.fx/configs/config.{env}.json` f
} ```
-After adding the snippet, add your secret to related environment variable so the tool can resolve the actual secret during provision.
+After adding the snippet, add your secret to the related environment variable so the tool can resolve the actual secret during provision.
> [!NOTE] > Ensure not to share the same Azure AD app in multiple environments. If you don't have permission to update the Azure AD app, you can get a warning with instructions about how to manually update the Azure AD app. Follow the instructions to update your Azure AD app after provision.
After adding the preceding snippet, add your secret to related environment varia
#### Skip adding user for SQL database
-If you have insufficient permission error when the tool tries to add user to SQL database, you can add the following configuration snippet to `.fx/configs/config.{env}.json` file to skip adding SQL database user:
+If you have an insufficient permission error when the tool tries to add a user to the SQL database, you can add the following configuration snippet to `.fx/configs/config.{env}.json` file to skip adding the SQL database user:
```json "skipAddingSqlUser": true
You can use `contosoteamsappapi` for function app instance instead of using the
> [!NOTE] > If you have already provisioned the environment, specifying the name can create a new function app instance for you, instead of renaming the instance created previously.
-The following steps are:
+Follow the steps to specify the name of the Function App instance:
1. Open `.fx/configs/azure.parameters.{env}.json` for your current environment. 2. Add a new property, for example, `functionAppName` under the `provisionParameters` section.
The following steps are:
} ```
-To add other Azure resource or storage to the application:
+To add other Azure resource or storage to the application, consider the following scenario:
-Consider the following scenario:
-
-You want to add Azure storage to your Azure function backend to store blob data. There is no auto flow to update the bicep template with Azure storage support. However, you can edit the bicep file and add the resource. The steps are as follows:
+Add Azure storage to your Azure function backend to store blob data. There's no auto flow to update the bicep template with the Azure storage support. However, you can edit the bicep file and add the resource. The steps are as follows:
1. Create a tab project. 2. Add function to the project. For more information, see [add resources](./add-resource.md).
-3. Declare the new storage account in ARM template. You can declare the resource at `templates/azure/provision/function.bicep` directly. You're free to declare the resources in other places.
+3. Declare the new storage account in ARM template. You can declare the resource at `templates/azure/provision/function.bicep` directly. You can declare the resources in other places.
`````````bicep var applicationStorageAccountName = 'myapp${uniqueString(resourceGroup().id)}'
The following steps help you to provision cloud resources using Visual Studio:
:::image type="content" source="../assets/images/Tools-and-SDK-revamp/Provision-cloud-resources-in-TTK-VS/teams-toolkit-vs-prepare-app-dependencies1.png" alt-text="Prepare teams app dependencies":::
-1. Select **Sign in** to sign in to your Azure account.
+1. Select **Sign in...** to sign in to your Azure account.
:::image type="content" source="../assets/images/Tools-and-SDK-revamp/Provision-cloud-resources-in-TTK-VS/teams-toolkit-vs-prepare1.png" alt-text="Sign in to Microsoft 365"::: > [!NOTE]
- > If you are already logged in, your username displays, or you can select the same to switch your account.
+ > If you are already singed in, your username displays, or you have an option to switch account.
1. Your default web browser opens to let you [sign in](https://developer.microsoft.com/en-us/microsoft-365/dev-program) to the account.
The following steps help you to provision cloud resources using Visual Studio:
:::image type="content" source="../assets/images/Tools-and-SDK-revamp/Provision-cloud-resources-in-TTK-VS/teams-toolkit-vs-provision-start.png" alt-text="Sign in to your Azure account"::: > [!NOTE]
- > If you're already logged in, your username is displayed, or you have an option to switch account.
+ > If you're already signed in, your username is displayed, or you have an option to switch account.
After sign in to your Azure account using your credentials, the browser closes automatically.
After you open your project in Visual Studio:
:::image type="content" source="../assets/images/Tools-and-SDK-revamp/Provision-cloud-resources-in-TTK-VS/teams-toolkit-vs-provision-in-cloud2.png" alt-text="Provision in cloud":::
- The **Provision** window appears.
-
-1. Enter the following details to provision your resources.
+ **Provision** window appears.
- :::image type="content" source="../assets/images/Tools-and-SDK-revamp/Provision-cloud-resources-in-TTK-VS/teams-toolkit-vs-provision-select-subscription1.png" alt-text="Select resource group":::
+1. Enter the following details to provision your resources:
1. Select your **Subscription name** from the dropdown list. 1. Select your **Resource group** from the dropdown list. 1. Select your **Region** from the dropdown list. > [!NOTE]
- > You can create new Resource group by selecting **New**.
+ > You can create new **Resource group** by selecting **New...**.
1. Select **Provision**.
+ :::image type="content" source="../assets/images/Tools-and-SDK-revamp/Provision-cloud-resources-in-TTK-VS/teams-toolkit-vs-provision-select-subscription1.png" alt-text="Select resource group":::
+ 1. The dialog appears mentioning that charges may be added as per Azure usage. Select **Provision**. :::image type="content" source="../assets/images/Tools-and-SDK-revamp/Provision-cloud-resources-in-TTK-VS/teams-toolkit-vs-provision-warning.png" alt-text="Provision warning":::
- The provisioning process creates resources in Azure cloud. You can monitor the progress by observing the Teams Toolkit output window.
+ The provisioning process creates resources in the Azure cloud. You can monitor the progress by observing the Teams Toolkit output window.
1. You're prompted after provisioning is complete. Select **View Provisioned Resources** to view all the resources that were provisioned.
The following list shows the resource creation for different types of app and Az
| Resource | Purpose | Description | | | | |
-| App service plan | Hosts your web app of tab. | Not applicable |
-| App service | Hosts your Blazor tab app and simple auth server that helps gain access to other services. | Adds user assigned identity to access other Azure resources. |
-| Manage identity | Authenticate Azure service-to-service requests. | Shares across different capabilities and resources. |
+| App service plan | Hosts your web app of tab | Not applicable |
+| App service | Hosts your Blazor tab app | Not applicable |
+| Manage identity | Authenticate Azure service-to-service requests | Shares across different capabilities and resources |
</details> <br>
The following list shows the resource creation for different types of app and Az
| Resource | Purpose | Description | | | | |
-| Azure bot | Registers your app as a bot with the bot framework. | Connects bot to Teams. |
-| App Service plan | Hosts your web bot app. | Not applicable |
-| App Service | Hosts your bot app. | Adds user assigned identity to access other Azure resources. |
-| Manage identity | Authenticate Azure service-to-service requests. | Shares across different capabilities and resources. |
+| Azure bot | Registers your app as a bot with the bot framework | Connects bot to Teams |
+| App Service plan | Hosts your web bot app | Not applicable |
+| App Service | Hosts your bot app | Adds user assigned identity to access other Azure resources |
+| Manage identity | Authenticate Azure service-to-service requests | Shares across different capabilities and resources |
</details> <br>
The following list shows the resource creation for different types of app and Az
| Resource | Purpose | Description | | | | |
-| Azure bot | Registers your app as a bot with the bot framework. | Connects bot to Teams. |
-| App service plan | Hosts your web bot app. | Not applicable |
-| App service | Hosts your bot app. | Adds user assigned identity to access other Azure resources. |
-| Manage identity | Authenticate Azure service-to-service requests. | Shares across different capabilities and resources. |
+| Azure bot | Registers your app as a bot with the bot framework | Connects bot to Teams |
+| App service plan | Hosts your web bot app | Not applicable |
+| App service | Hosts your bot app | Adds user assigned identity to access other Azure resources |
+| Manage identity | Authenticate Azure service-to-service requests | Shares across different capabilities and resources |
</details> <br>
The following list shows the resource creation for different types of app and Az
| Resource | Purpose | Description | | | | |
-| Azure bot | Registers your app as a bot with the bot framework. | Connects bot to Teams. |
-| App service plan | Hosts your web bot app. | Not applicable |
-| App service | Host your bot app. | Adds user assigned identity to access other Azure resources. |
-| Managed Identity | Authenticate Azure service-to-service requests. | Shares across different capabilities and resources. |
+| Azure bot | Registers your app as a bot with the bot framework | Connects bot to Teams |
+| App service plan | Hosts your web bot app | Not applicable |
+| App service | Host your bot app | Adds user assigned identity to access other Azure resources |
+| Managed Identity | Authenticate Azure service-to-service requests | Shares across different capabilities and resources |
</details> <br>
The following list shows the resource creation for different types of app and Az
| Resource | Purpose | Description | | | | |
-| Azure bot | Registers your app as a bot with the bot framework. | Connects bot to Teams. |
-| Manage identity | Authenticates Azure service-to-service requests. | Shared across different capabilities and resources. |
-| Storage account | Helps to create function app. | Not applicable |
-| App service plan | Hosts the function bot App. | Not applicable |
-| Function app | Hosts your bot app. | -Adds user assigned identity to access other Azure resources.<br>-Adds Cross-origin resource sharing (CORS) rule to allow requests from your tab app.<br>-Adds authentication setting that only allows requests from your Teams app.<br>-Adds app settings required by TeamsFx SDK. |
+| Azure bot | Registers your app as a bot with the bot framework | Connects bot to Teams |
+| Manage identity | Authenticates Azure service-to-service requests | Shared across different capabilities and resources |
+| Storage account | Helps to create function app | Not applicable |
+| App service plan | Hosts the function bot App | Not applicable |
+| Function app | Hosts your bot app | - Adds user assigned identity to access other Azure resources<br>- Adds Cross-origin resource sharing (CORS) rule to allow requests from your tab app<br>- Adds authentication setting that only allows requests from your Teams app<br>- Adds app settings required by TeamsFx SDK |
</details> <br>
The following list shows the resource creation for different types of app and Az
| Resource | Purpose | Description | | | | |
-| Azure bot | Registers your app as a bot with the bot framework. | Connects bot to Teams. |
-| Manage identity | Authenticate Azure service-to-service requests. | Shares across different capabilities and resources. |
-| Storage account | Helps to create function app. | Not applicable. |
-| App service plan | Hosts the function bot app. | Not applicable |
-| Function app | Hosts your bot app. | -Adds user assigned identity to access other Azure resources.<br>-Adds Cross-origin resource sharing (CORS) rule to allow requests from your tab app.<br>-Adds authentication setting that only allows requests from your Teams app.<br>-Adds app settings required by TeamsFx SDK. |
+| Azure bot | Registers your app as a bot with the bot framework | Connects bot to Teams |
+| Manage identity | Authenticate Azure service-to-service requests | Shares across different capabilities and resources |
+| Storage account | Helps to create function app | Not applicable |
+| App service plan | Hosts the function bot app | Not applicable |
+| Function app | Hosts your bot app | - Adds user assigned identity to access other Azure resources<br>-Adds Cross-origin resource sharing (CORS) rule to allow requests from your tab app<br>- Adds authentication setting that only allows requests from your Teams app<br>- Adds app settings required by TeamsFx SDK |
</details> <br>
Teams Toolkit enables you to use an infrastructure for the code approach to defi
Teams Toolkit uses ARM template to define Azure resources. The ARM template is a set of bicep files that defines the infrastructure and configuration for your project. You can customize Azure resources by modifying the ARM template. For more information, see [bicep document](/azure/azure-resource-manager/bicep).
-Provision with ARM involves changing the following sets of files, parameters and templates:
+Provision with ARM involves changing the following sets of files, parameters, and templates:
* ARM parameter files (`azure.parameters.{your_env_name}.json`) located in `.fx/configs` folder, for passing parameters to templates. * ARM template files located in `templates/azure` folder contains following files:
-| File | Function | Allow customization |
-| | | |
-| main.bicep | Provide entry point for Azure resource. provision | Yes |
-| provision.bicep | Create and configure Azure resources. | Yes |
-| config.bicep | Add TeamsFx required configurations to Azure resources. | Yes |
-| provision/xxx.bicep | Create and configure each Azure resource consumed by `provision.bicep`. | Yes |
-| teamsfx/xxx.bicep | Add TeamsFx required configurations to each Azure resource consumed by `config.bicep`.| No |
+ | File | Function | Allow customization |
+ | | | |
+ | main.bicep | Provide entry point for Azure resource. provision | Yes |
+ | provision.bicep | Create and configure Azure resources. | Yes |
+ | config.bicep | Add TeamsFx required configurations to Azure resources. | Yes |
+ | provision/xxx.bicep | Create and configure each Azure resource consumed by `provision.bicep`. | Yes |
+ | teamsfx/xxx.bicep | Add TeamsFx required configurations to each Azure resource consumed by `config.bicep`.| No |
> [!NOTE] > After you add resources or capabilities to your project, `teamsfx/xxx.bicep` is regenerated. To modify the bicep files, you can use Git to track your changes to `teamsfx/xxx.bicep` files. This doesn't make you lose any changes while adding resources or capabilities to your project.
The ARM template files use placeholders for parameters. The purpose of the place
### Reference environment variables in parameter files
-When the value is secret, then you don't need to hardcode them in parameter file. The parameter files support referencing the values from environment variables. You can use this syntax `{{$env.YOUR_ENV_VARIABLE_NAME}}` in the parameter values for Teams Toolkit to resolve from current environment variable.
+When the value is secret, then you don't need to hardcode them in parameter file. The parameter files support referencing the values from the environment variables. You can use this syntax `{{$env.YOUR_ENV_VARIABLE_NAME}}` in the parameter values for Teams Toolkit to resolve from current environment variable.
-The following example reads the value of `mySelfHostedDbConnectionString` parameter from environment variable `DB_CONNECTION_STRING`:
+The following example reads the value of the `mySelfHostedDbConnectionString` parameter from the environment variable `DB_CONNECTION_STRING`:
```json ...
The following example reads the value of `mySelfHostedDbConnectionString` parame
If the predefined templates don't meet your application requirement, you can customize the ARM templates under `templates/azure` folder. For example, you can customize the ARM template to create some extra Azure resources for your app. You need to have basic knowledge of bicep language, which is used to author ARM template.
-To ensure the TeamsFx tool functions properly, customize ARM template, that satisfies the following requirement:
+To ensure the TeamsFx tool functions properly, customize ARM template that satisfies the following requirements:
* Ensure that the folder structure and file name remain unchanged. The tool may append new content to the existing files when you add more resources or capabilities to your project. * Ensure that the name of auto-generated parameters and its property names remain unhanged. The auto-generated parameters may be used when you add more resources or capabilities to your project.
-* Ensure that the output of auto-generated ARM template is unchanged as well. You can add more outputs to ARM template. The output is `.fx/states/state.{env}.json` and can be used in other features such as deploy and validate manifest file.
+* Ensure that the output of auto-generated ARM template is unchanged as well. You can add more outputs to ARM template. The output is `.fx/states/state.{env}.json` and can be used in other features such as deploy and validate manifest files.
### Customize Teams app
-You can customize your bot or the Teams app by adding configuration snippets to use an Azure AD app created by you. You can perform in the following ways:
+You can customize your bot or the Teams app by adding configuration snippets to use an Azure AD app created by you.
+Perform in the following ways to customize the Teams app:
+
+* [Use an existing Azure AD app for your Teams app](#use-an-existing-azure-ad-app-for-your-teams-app)
+* [Use an existing Azure AD app for your bot](#use-an-existing-azure-ad-app-for-your-bot)
#### Use an existing Azure AD app for your Teams app
You can add the following configuration snippet `.fx/configs/config.{env}.json`
} ```
-After adding the snippet, add your client secret to the related environment variable so that Teams Toolkit can resolve the actual client secret during provision.
+After adding the snippet, add your client secret to the related environment variable for Teams Toolkit to resolve the actual client secret during provision.
> [!NOTE] > Ensure not to share the same Azure AD app in multiple environments. If you don't have permission to update the Azure AD app, you get a warning with instructions to manually update the Azure AD app. Follow these instructions to update your Azure AD app after provision.
After adding the snippet, add your client secret to the related environment vari
#### Skip adding user for SQL database
-If you get an insufficient permission error when Teams Toolkit tries to add user to SQL database, you can then add the following configuration snippet to `.fx/configs/config.{env}.json` to skip adding SQL database user:
+If you get an insufficient permission error when Teams Toolkit tries to add user to SQL database, add the following configuration snippet to `.fx/configs/config.{env}.json` to skip adding SQL database user:
```json "skipAddingSqlUser": true
platform Whats New https://github.com/MicrosoftDocs/msteams-docs/commits/main/msteams-platform/whats-new.md
Teams platform features that are available to all app developers.
**2022 November**
+***November 14, 2022***: [Introducing single sign-on for Visual Studio](toolkit/add-single-sign-on.md).
+ ***November 02, 2022***: [Support global routing for bot APIs](bots/how-to/conversations/send-proactive-messages.md#create-the-conversation). :::column-end:::