Merge pull request #2 from BobGerman/BG-Repairs-local-auth-sample

Add new sample da-repairs-oauth-validated
pnp · Oct 9, 2024 · 6857148 · 6857148
2 parents df6729b + c0fda89
commit 6857148
Show file tree

Hide file tree

Showing 31 changed files with 1,846 additions and 0 deletions.
diff --git a/samples/da-repairs-oauth-validated/.funcignore b/samples/da-repairs-oauth-validated/.funcignore
@@ -0,0 +1,21 @@
+.funcignore
+*.js.map
+*.ts
+.git*
+.localConfigs
+.vscode
+local.settings.json
+test
+tsconfig.json
+.DS_Store
+.deployment
+node_modules/.bin
+node_modules/azure-functions-core-tools
+README.md
+tsconfig.json
+teamsapp.yml
+teamsapp.*.yml
+/env/
+/appPackage/
+/infra/
+/devTools/
diff --git a/samples/da-repairs-oauth-validated/.gitignore b/samples/da-repairs-oauth-validated/.gitignore
@@ -0,0 +1,31 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+# TeamsFx files
+env/.env.*.user
+env/.env.dev
+env/.env.local
+.DS_Store
+build
+appPackage/build
+.deployment
+
+# dependencies
+/node_modules
+
+# testing
+/coverage
+
+# Dev tool directories
+/devTools/
+
+# TypeScript output
+dist
+out
+
+# Azure Functions artifacts
+bin
+obj
+appsettings.json
+local.settings.json
+
+# Local data
+.localConfigs
diff --git a/samples/da-repairs-oauth-validated/.vscode/extensions.json b/samples/da-repairs-oauth-validated/.vscode/extensions.json
@@ -0,0 +1,5 @@
+{
+  "recommendations": [
+    "TeamsDevApp.ms-teams-vscode-extension"
+  ]
+}
diff --git a/samples/da-repairs-oauth-validated/.vscode/launch.json b/samples/da-repairs-oauth-validated/.vscode/launch.json
@@ -0,0 +1,97 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Launch App in Teams (Edge)",
+            "type": "msedge",
+            "request": "launch",
+            "url": "https://www.office.com/chat?auth=2",
+            "cascadeTerminateToConfigurations": [
+                "Attach to Backend"
+            ],
+            "presentation": {
+                "group": "all",
+                "hidden": true
+            },
+            "internalConsoleOptions": "neverOpen",
+            "perScriptSourcemaps": "yes"
+        },
+        {
+            "name": "Launch App in Teams (Chrome)",
+            "type": "chrome",
+            "request": "launch",
+            "url": "https://www.office.com/chat?auth=2",
+            "cascadeTerminateToConfigurations": [
+                "Attach to Backend"
+            ],
+            "presentation": {
+                "group": "all",
+                "hidden": true
+            },
+            "internalConsoleOptions": "neverOpen",
+            "perScriptSourcemaps": "yes"
+        },
+        {
+            "name": "Preview in Copilot (Edge)",
+            "type": "msedge",
+            "request": "launch",
+            "url": "https://www.office.com/chat?auth=2",
+            "presentation": {
+                "group": "remote",
+                "order": 1
+            },
+            "internalConsoleOptions": "neverOpen"
+        },
+        {
+            "name": "Preview in Copilot (Chrome)",
+            "type": "chrome",
+            "request": "launch",
+            "url": "https://www.office.com/chat?auth=2",
+            "presentation": {
+                "group": "remote",
+                "order": 2
+            },
+            "internalConsoleOptions": "neverOpen"
+        },
+        {
+            "name": "Attach to Backend",
+            "type": "node",
+            "request": "attach",
+            "port": 9229,
+            "restart": true,
+            "presentation": {
+                "group": "all",
+                "hidden": true
+            },
+            "internalConsoleOptions": "neverOpen"
+        }
+    ],
+    "compounds": [
+        {
+            "name": "Debug in Copilot (Edge)",
+            "configurations": [
+                "Launch App in Teams (Edge)",
+                "Attach to Backend"
+            ],
+            "preLaunchTask": "Start Teams App Locally",
+            "presentation": {
+                "group": "all",
+                "order": 1
+            },
+            "stopAll": true
+        },
+        {
+            "name": "Debug in Copilot (Chrome)",
+            "configurations": [
+                "Launch App in Teams (Chrome)",
+                "Attach to Backend"
+            ],
+            "preLaunchTask": "Start Teams App Locally",
+            "presentation": {
+                "group": "all",
+                "order": 2
+            },
+            "stopAll": true
+        }
+    ]
+}
diff --git a/samples/da-repairs-oauth-validated/.vscode/settings.json b/samples/da-repairs-oauth-validated/.vscode/settings.json
@@ -0,0 +1,13 @@
+{
+    "debug.onTaskErrors": "abort",
+    "json.schemas": [
+        {
+            "fileMatch": [
+                "/aad.*.json"
+            ],
+            "schema": {}
+        }
+    ],
+    "azureFunctions.stopFuncTaskPostDebug": false,
+    "azureFunctions.showProjectWarning": false,
+}
diff --git a/samples/da-repairs-oauth-validated/.vscode/tasks.json b/samples/da-repairs-oauth-validated/.vscode/tasks.json
@@ -0,0 +1,129 @@
+// This file is automatically generated by Teams Toolkit.
+// The teamsfx tasks defined in this file require Teams Toolkit version >= 5.0.0.
+// See https://aka.ms/teamsfx-tasks for details on how to customize each task.
+{
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Start Teams App Locally",
+            "dependsOn": [
+                "Validate prerequisites",
+                "Start local tunnel",
+                "Create resources",
+                "Build project",
+                "Start application"
+            ],
+            "dependsOrder": "sequence"
+        },
+        {
+            "label": "Validate prerequisites",
+            "type": "teamsfx",
+            "command": "debug-check-prerequisites",
+            "args": {
+                "prerequisites": [
+                    "nodejs",
+                    "m365Account",
+                    "portOccupancy"
+                ],
+                "portOccupancy": [
+                    7071,
+                    9229
+                ]
+            }
+        },
+        {
+            // Start the local tunnel service to forward public URL to local port and inspect traffic.
+            // See https://aka.ms/teamsfx-tasks/local-tunnel for the detailed args definitions.
+            "label": "Start local tunnel",
+            "type": "teamsfx",
+            "command": "debug-start-local-tunnel",
+            "args": {
+                "type": "dev-tunnel",
+                "ports": [
+                    {
+                        "portNumber": 7071,
+                        "protocol": "http",
+                        "access": "public",
+                        "writeToEnvironmentFile": {
+                            "endpoint": "OPENAPI_SERVER_URL", // output tunnel endpoint as OPENAPI_SERVER_URL
+                        }
+                    }
+                ],
+                "env": "local"
+            },
+            "isBackground": true,
+            "problemMatcher": "$teamsfx-local-tunnel-watch"
+        },
+        {
+            "label": "Create resources",
+            "type": "teamsfx",
+            "command": "provision",
+            "args": {
+                "env": "local"
+            }
+        },
+        {
+            "label": "Build project",
+            "type": "teamsfx",
+            "command": "deploy",
+            "args": {
+                "env": "local"
+            }
+        },
+        {
+            "label": "Start application",
+            "dependsOn": [
+                "Start backend"
+            ]
+        },        
+        {
+            "label": "Start backend",
+            "type": "shell",
+            "command": "npm run dev:teamsfx",
+            "isBackground": true,
+            "options": {
+                "cwd": "${workspaceFolder}",
+                "env": {
+                    "PATH": "${workspaceFolder}/devTools/func:${env:PATH}"
+                }
+            },
+            "windows": {
+                "options": {
+                    "env": {
+                        "PATH": "${workspaceFolder}/devTools/func;${env:PATH}"
+                    }
+                }
+            },
+            "problemMatcher": {
+                "pattern": {
+                    "regexp": "^.*$",
+                    "file": 0,
+                    "location": 1,
+                    "message": 2
+                },
+                "background": {
+                    "activeOnStart": true,
+                    "beginsPattern": "^.*(Job host stopped|signaling restart).*$",
+                    "endsPattern": "^.*(Worker process started and initialized|Host lock lease acquired by instance ID).*$"
+                }
+            },
+            "presentation": {
+                "reveal": "silent"
+            },
+            "dependsOn": "Watch backend"
+        },
+        {
+            "label": "Watch backend",
+            "type": "shell",
+            "command": "npm run watch:teamsfx",
+            "isBackground": true,
+            "options": {
+                "cwd": "${workspaceFolder}"
+            },
+            "problemMatcher": "$tsc-watch",
+            "presentation": {
+                "reveal": "silent"
+            }
+        }
+    ]
+}
diff --git a/samples/da-repairs-oauth-validated/README.md b/samples/da-repairs-oauth-validated/README.md
@@ -0,0 +1,66 @@
+# Declarative Agent with an API plugin connected to an API secured with OAuth with validation
+
+## Summary
+
+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 secured with Entra ID. 
+
+![picture of the app in action](./assets/screenshot.gif)
+
+The project contains an Azure Function, but unlike the [da-repairs-oauth sample](../da-repairs-oauth/) relies on Azure App Services authentication ("Easy Auth") for authentication, this sample validates access tokens in code. Teams Toolkit currently uses Easy Auth as shown in this sample. Here are some advantages of validating the token in your code instead:
+
+ - 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. In this sample, 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 access 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 if the token is an app token
+
+ For these reasons, developers may choose to follow this approach, which is made possible by an open source library ([jwt-validate](https://www.npmjs.com/package/jwt-validate)) by [Waldek Mastykarz](https://github.com/waldekmastykarz). 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 this library since Microsoft does not currently provide a token validation library for NodeJS.
+
+
+## Prerequisites
+![drop](https://img.shields.io/badge/Teams&nbsp;Toolkit&nbsp;for&nbsp;VS&nbsp;Code-5.10-green.svg)
+
+ * Microsoft 365 tenant with Microsoft 365 Copilot
+ * [Visual Studio Code](https://code.visualstudio.com/) with [Teams Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) v5.10 or greater
+ * [NodeJS v18](https://nodejs.org/en/download/package-manager)
+ * [Azure Functions core tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local#install-the-azure-functions-core-tools)
+
+_Please list any portions of the toolchain required to build and use the sample, along with download links_
+
+## Version history
+
+Version|Date|Author|Comments
+-------|----|----|--------
+1.0|October 9, 2024|Bob German|Initial release
+
+## Disclaimer
+
+**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.**
+
+---
+
+## Minimal Path to Awesome
+
+* Clone this repository
+* Open the cloned copy of this folder with Visual Studio Code
+* Install required npm packages
+
+```shell
+  npm install
+```
+
+* Press F5 to run the application. A browser window should open offering to add your application to Microsoft Teams.
+
+
+## Features
+
+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 (Easy Auth)
+Using dev tunnels to test the API plugin locally
+
+<img src="https://m365-visitor-stats.azurewebsites.net/copilot-pro-dev-samples/samples/da-repairs-oauth-validated" />