-
Notifications
You must be signed in to change notification settings - Fork 201
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[JS] docs: update 06.auth.teamsSSO.bot (#995)
## Linked issues closes: #983 ## Details 1. Update readme structure to align with other samples 2. Remove step to install dependency in `teamsapp.local.yml` ## Attestation Checklist - [x] My code follows the style guidelines of this project - I have checked for/fixed spelling, linting, and other errors - I have commented my code for clarity - I have made corresponding changes to the documentation (we use [TypeDoc](https://typedoc.org/) to document our code) - My changes generate no new warnings - I have added tests that validates my changes, and provides sufficient test coverage. I have tested with: - Local testing - E2E testing in Teams - New and existing unit tests pass locally with my changes
- Loading branch information
1 parent
05ca25f
commit e122a67
Showing
6 changed files
with
100 additions
and
26 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,18 +4,12 @@ This sample shows how to incorporate a basic conversational flow with SSO into a | |
|
||
This sample depends on Teams SSO and gives you more flexibility on how to configure AAD, like using a client certificate. There is no need to create an OAuth Connection in Azure Bot Service to run this sample. | ||
|
||
<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} --> | ||
## Showcase | ||
|
||
<!-- code_chunk_output --> | ||
|
||
- [Teams SSO Bot](#teams-message-extension-sso-bot) | ||
- [Setting up the sample](#setting-up-the-sample) | ||
- [Interacting with the bot](#interacting-with-the-bot) | ||
- [Test using Teams Toolkit for Visual Studio Code](#test-using-teams-toolkit-for-visual-studio-code) | ||
- [Deploy the bot to Azure](#deploy-the-bot-to-azure) | ||
- [Further reading](#further-reading) | ||
|
||
<!-- /code_chunk_output --> | ||
- The bot echos back any message it receives. That's it! | ||
- This app is the bot-equivalent of 'Hello world'. | ||
- The minimum setup shows how to set up a bot with the Teams AI SDK. | ||
- This sample leverages Teams SSO to acquire a token for app user. | ||
|
||
## Setting up the sample | ||
|
||
|
@@ -31,7 +25,7 @@ This sample depends on Teams SSO and gives you more flexibility on how to config | |
npm install -g [email protected] | ||
``` | ||
|
||
1. In the root JavaScript folder, install and build all dependencies | ||
1. In the root **JavaScript folder**, install and build all dependencies | ||
|
||
```bash | ||
cd teams-ai/js | ||
|
@@ -45,30 +39,66 @@ This sample depends on Teams SSO and gives you more flexibility on how to config | |
cd samples/<this-sample-folder>/ | ||
``` | ||
|
||
## Interacting with the bot | ||
The easiest and fastest way to get up and running is with Teams Toolkit as your development guide. To use Teams Toolkit to continue setup and debugging, please continue below. To read about other options, skip to [Other ways to run the sample](#other-ways-to-run-the-sample). | ||
|
||
Send anything to the bot. The bot will single sign-on the current user and send the length of the acquired token back to the user. | ||
## Teams Toolkit for Visual Studio Code | ||
|
||
## Test using Teams Toolkit for Visual Studio Code | ||
Teams Toolkit automates the setup of Azure Bot Resources and provides a local development environment for your bot. It also provides a debugging experience in VS Code that allows you to test your bot in a Teams web client. | ||
|
||
The simplest way to run this sample in Teams is to use Teams Toolkit for Visual Studio Code. | ||
### Prerequisites | ||
|
||
1. Ensure you have downloaded and installed [Visual Studio Code](https://code.visualstudio.com/docs/setup/setup-overview) | ||
1. Install the [Teams Toolkit extension](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | ||
|
||
### Run the sample | ||
1. Select **File > Open Folder** in VS Code and choose this sample's directory from the repo | ||
1. Using the extension, sign in with your Microsoft 365 account where you have permissions to upload custom apps | ||
1. Select **Debug > Start Debugging** or **F5** to run the app in a Teams web client. | ||
- Running the debugger from the root of the repo will not work - you must open a new window at the sample's root. | ||
1. Using the TTK extension, sign in with your Microsoft 365 account where you have permissions to upload custom apps to Teams. | ||
1. Further, detailed instructions can be found at [Getting Started - Teams Toolkit](../../../getting-started/OTHER/TEAMS-TOOLKIT.md) | ||
1. Select **Debug > Start Debugging** or **F5** to run the app in a Teams web client (in Microsoft Edge). | ||
1. In the browser that launches, select the **Add** button to install the app to Teams. | ||
|
||
> If you do not have permission to upload custom apps (sideloading), Teams Toolkit will recommend creating and using a Microsoft 365 Developer Program account - a free program to get your own dev environment sandbox that includes Teams. | ||
|
||
## Interacting with the bot | ||
|
||
In the chat window of the Teams client, you can interact with the bot by sending it a message. The bot will echo back the message you sent. In the meanwhile, the bot will also single sign-on your account and send the length of the acquired token back to you. | ||
|
||
## Other ways to run the sample | ||
### Teams Toolkit CLI | ||
|
||
[TeamsFx command line interface](https://learn.microsoft.com/microsoftteams/platform/toolkit/teamsfx-cli?pivots=version-two) is a text-based command line interface that accelerates Teams application development. It aims to provide keyboard centric experience while building Teams applications. | ||
|
||
Navigate to [Teams Toolkit CLI](../../../getting-started/OTHER/TEAMS-TOOLKIT-CLI.md) for setup instructions. | ||
|
||
### Manual resource management and uploading to Teams | ||
|
||
[Manual resource setup](../../../getting-started/OTHER/MANUAL-RESOURCE-SETUP.md) provides instructions on how to manually create the Azure Bot Resources and upload the app to Teams. | ||
|
||
These directions are useful if you do not wish to use Teams Toolkit or you already have resources created and deployed. | ||
|
||
If you are doing manual setup, you can ignore the `env` folder entirely. | ||
|
||
### BotFramework Emulator | ||
|
||
[Bot Framework Emulator](https://github.com/microsoft/BotFramework-Emulator) Allows testing bots independently from channels when developing your bot if you do not wish to use Teams Toolkit. | ||
|
||
[Running BF Emulator](../../../getting-started/OTHER/BOTFRAMEWORK-EMULATOR.md) directions provide instructions on how to run the bot in Emulator. | ||
|
||
> Note: Emulator is channel-agnostic, meaning that features specific to Teams will not be testable in Emulator. | ||
|
||
## Deploy the bot to Azure | ||
|
||
You can use Teams Toolkit for VS Code or CLI to host the bot in Azure. The sample includes Bicep templates in the `/infra` directory which are used by the tools to create resources in Azure. Use the **Provision** and **Deploy** menus of the Teams Toolkit extension or from the CLI with `teamsfx provision` and `teamsfx deploy`. [Visit the documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/provision) for more info on hosting your app in Azure with Teams Toolkit. | ||
You can use Teams Toolkit for VS Code or CLI to host the bot in Azure. The sample includes Bicep templates in the `/infra` directory which are used by the tools to create resources in Azure. | ||
* Use the **Provision** and **Deploy** menus of the Teams Toolkit extension | ||
* Run CLI commands `teamsfx provision` and `teamsfx deploy`. | ||
* [Visit the documentation](https://learn.microsoft.com/microsoftteams/platform/toolkit/provision) for more info on hosting your app in Azure with Teams Toolkit. | ||
|
||
Alternatively, you can learn more about deploying a bot to Azure manually in the [Deploy your bot to Azure](https://aka.ms/azuredeployment) documentation. | ||
|
||
## Further reading | ||
|
||
- [Teams Toolkit overview](https://learn.microsoft.com/en-us/microsoftteams/platform/toolkit/teams-toolkit-fundamentals) | ||
- [How Microsoft Teams bots work](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-basics-teams?view=azure-bot-service-4.0&tabs=javascript) | ||
- [Getting started with Teams AI](../../../getting-started/README.md) | ||
- Introduces the Teams AI Library and reviews bot and AI-related concepts | ||
- [Teams Toolkit overview](https://learn.microsoft.com/microsoftteams/platform/toolkit/teams-toolkit-fundamentals) | ||
- [How Microsoft Teams bots work](https://docs.microsoft.com/azure/bot-service/bot-builder-basics-teams?view=azure-bot-service-4.0&tabs=javascript) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
# This file includes environment variables that will be committed to git by default. | ||
# Built-in environment variables | ||
TEAMSFX_ENV=dev | ||
APP_NAME_SUFFIX=dev | ||
|
||
# Updating AZURE_SUBSCRIPTION_ID or AZURE_RESOURCE_GROUP_NAME after provision may also require an update to RESOURCE_SUFFIX, because some services require a globally unique name across subscriptions/resource groups. | ||
AZURE_SUBSCRIPTION_ID= | ||
AZURE_RESOURCE_GROUP_NAME= | ||
RESOURCE_SUFFIX= | ||
|
||
# Generated during provision, you can also add your own variables. If you're adding a secret value, add SECRET_ prefix to the name so Teams Toolkit can handle them properly | ||
BOT_ID= | ||
BOT_DOMAIN= | ||
AAD_APP_CLIENT_ID= | ||
AAD_APP_OBJECT_ID= | ||
AAD_APP_TENANT_ID= | ||
AAD_APP_OAUTH_AUTHORITY= | ||
AAD_APP_OAUTH_AUTHORITY_HOST= | ||
TEAMS_APP_ID= | ||
TEAMS_APP_TENANT_ID= | ||
AAD_APP_ACCESS_AS_USER_PERMISSION_ID= |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
# This file includes environment variables that will not be committed to git by default. You can set these environment variables in your CI/CD system for your project. | ||
|
||
# If you're adding a secret value, add SECRET_ prefix to the name so Teams Toolkit can handle them properly | ||
SECRET_AAD_APP_CLIENT_SECRET= | ||
SECRET_BOT_PASSWORD= |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,18 @@ | ||
# This file includes environment variables that can be committed to git. It's gitignored by default because it represents your local development environment. | ||
|
||
# Built-in environment variables | ||
TEAMSFX_ENV=local | ||
APP_NAME_SUFFIX=local | ||
|
||
# If you're adding a secret value, add SECRET_ prefix to the name so Teams Toolkit can handle them properly | ||
BOT_ID= | ||
BOT_ENDPOINT= | ||
BOT_DOMAIN= | ||
AAD_APP_CLIENT_ID= | ||
AAD_APP_OBJECT_ID= | ||
AAD_APP_TENANT_ID= | ||
AAD_APP_OAUTH_AUTHORITY= | ||
AAD_APP_OAUTH_AUTHORITY_HOST= | ||
TEAMS_APP_ID= | ||
TEAMS_APP_TENANT_ID= | ||
AAD_APP_ACCESS_AS_USER_PERMISSION_ID= |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
# This file includes environment variables that will not be committed to git by default. You can set these environment variables in your CI/CD system for your project. | ||
|
||
# Generated during provision, you can also add your own variables. If you're adding a secret value, add SECRET_ prefix to the name so Teams Toolkit can handle them properly | ||
SECRET_AAD_APP_CLIENT_SECRET= | ||
SECRET_BOT_PASSWORD= |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters