This sample demonstrates how to build a declarative agent for Microsoft 365 Copilot that answers questions about repairs. The agent uses an API plugin to connect to an API that is secured with Entra ID.
Key aspects of the sample:
-
Shows how to configure Teams Toolkit make a declarative agent with an API plugin that is secured with Entra ID with just F5 to run locally.
-
Shows how to validate an Entra ID access token in NodeJS (JavaScript/TypeScript) rather than rely on an external service. This differs from the Teams Toolkit scaffolding, which doesn't authenticate users locally but instead relies on use of Azure App Services authentication (EasyAuth) for security in Azure only.
Here are some advantages of validating the token in your code instead of using Easy Auth
-
Since Easy Auth doesn't work locally, local requests are not authenticated. In addition to a small security opening, this causes the app to have 2 plugin files, including an anonymous one for local debugging. By handling in code, local requests are authenticated and the packaging source files are the same for all environments.
-
If the code is deployed outside of Azure app services, and if the included Bicep files aren't used, the code will appear to work but will do no token validation at all, thus wide open to anonymous requests.
-
With the Easy Auth scenario, Copilot is sending the access token directly to Azure App Services authentication. If something goes wrong there is no way to inspect the OAuth token, and debugging options are limited. In this sample you can set a breakpoint to inspect the token and walk through the validation to see what went wrong.
-
Easy Auth does not check the scope, or check to see if the token is an app token
For these reasons, developers may choose to follow the approach used in this sample.
Microsoft does not currently provide a library for validating OAuth tokens in NodeJS; the official documentation is here. So this sample uses an open source library (jwt-validate) by Waldek Mastykarz, which aims to follow the documented practices. This library is not a Microsoft product, and is subject to an MIT license (i.e. use at your own risk). Many thanks to Waldek for creating the library.
- Microsoft 365 tenant with Microsoft 365 Copilot
- Visual Studio Code with Teams Toolkit v5.10 or greater
- NodeJS v18
- Azure Functions core tools
| Version | Date | Author | Comments |
|---|---|---|---|
| 1.1 | October 11, 2024 | Waldek Mastykarz | Updated OAuth configuration and project setup |
| 1.0 | October 9, 2024 | Bob German | Initial release |
THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.
- Clone this repository
- Open the cloned copy of this folder with Visual Studio Code
- Install required npm packages
npm install- Press F5 to run the application. A browser window should open offering to add your application to Microsoft Teams.
This sample illustrates the following concepts:
- Building a declarative agent for Microsoft 365 Copilot with an API plugin
- Connecting an API plugin to an API secured with OAuth
- Using Azure Functions to build an API secured with Azure App
- Service authentication and authorization without Easy Auth
- Using dev tunnels to test the API plugin locally