Skip to content

Commit

Permalink
[JS] docs: update 06.auth.teamsSSO.bot (#995)
Browse files Browse the repository at this point in the history
## 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
blackchoey authored Dec 4, 2023
1 parent 05ca25f commit e122a67
Show file tree
Hide file tree
Showing 6 changed files with 100 additions and 26 deletions.
72 changes: 51 additions & 21 deletions js/samples/06.auth.teamsSSO.bot/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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)
21 changes: 21 additions & 0 deletions js/samples/06.auth.teamsSSO.bot/env/.env.dev
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=
5 changes: 5 additions & 0 deletions js/samples/06.auth.teamsSSO.bot/env/.env.dev.user
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=
18 changes: 18 additions & 0 deletions js/samples/06.auth.teamsSSO.bot/env/.env.local
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=
5 changes: 5 additions & 0 deletions js/samples/06.auth.teamsSSO.bot/env/.env.local.user
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=
5 changes: 0 additions & 5 deletions js/samples/06.auth.teamsSSO.bot/teamsapp.local.yml
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,6 @@ provision:
# Defines what the `deploy` lifecycle step does with Teams Toolkit.
# Runs after `provision` during Start Debugging (F5) or run manually using `teamsfx deploy --env local`.
deploy:
# Ensures that the project dependnecies are installed.
- uses: cli/runNpmCommand
with:
args: install --no-audit

# Provides the Teams Toolkit .env file values to the apps runtime so they can be accessed with `process.env`.
- uses: file/createOrUpdateEnvironmentFile
with:
Expand Down

0 comments on commit e122a67

Please sign in to comment.