Merge pull request #5369 from NishkalankBezawada/feature/New-Sample-S…

…harePoint-CustomCoPilot-Webpart

samples/react-copilot-chatbubble-with-sso/.devcontainer/devcontainer.json

@@ -0,0 +1,38 @@
+{
+  "name": "SPFx 1.20.0",
+  "image": "docker.io/m365pnp/spfx:1.20.0",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "editorconfig.editorconfig",
+        "dbaeumer.vscode-eslint"
+      ]
+    }
+  },
+  "forwardPorts": [
+    4321,
+    35729,
+    5432
+  ],
+  "portsAttributes": {
+    "4321": {
+      "protocol": "https",
+      "label": "Manifest",
+      "onAutoForward": "silent",
+      "requireLocalPort": true
+    },
+    "5432": {
+      "protocol": "https",
+      "label": "Workbench",
+      "onAutoForward": "silent"
+    },
+    "35729": {
+      "protocol": "https",
+      "label": "LiveReload",
+      "onAutoForward": "silent",
+      "requireLocalPort": true
+    }
+  },
+  "postCreateCommand": "bash .devcontainer/spfx-startup.sh",
+  "remoteUser": "node"
+}

samples/react-copilot-chatbubble-with-sso/.devcontainer/spfx-startup.sh

@@ -0,0 +1,33 @@
+echo
+echo -e "\e[1;94mInstalling Node dependencies\e[0m"
+npm install
+
+## commands to create dev certificate and copy it to the root folder of the project
+echo
+echo -e "\e[1;94mGenerating dev certificate\e[0m"
+gulp trust-dev-cert
+
+# Convert the generated PEM certificate to a  CER certificate
+openssl x509 -inform PEM -in ~/.rushstack/rushstack-serve.pem -outform DER -out ./spfx-dev-cert.cer
+
+# Copy the PEM ecrtificate for non-Windows hosts
+cp ~/.rushstack/rushstack-serve.pem ./spfx-dev-cert.pem
+
+## add *.cer to .gitignore to prevent certificates from being saved in repo
+if ! grep -Fxq '*.cer' ./.gitignore
+  then
+    echo "# .CER Certificates" >> .gitignore
+    echo "*.cer" >> .gitignore
+fi
+
+## add *.pem to .gitignore to prevent certificates from being saved in repo
+if ! grep -Fxq '*.pem' ./.gitignore
+  then
+    echo "# .PEM Certificates" >> .gitignore
+    echo "*.pem" >> .gitignore
+fi
+
+echo
+echo -e "\e[1;92mReady!\e[0m"
+
+echo -e "\n\e[1;94m**********\nOptional: if you plan on using gulp serve, don't forget to add the container certificate to your local machine. Please visit https://aka.ms/spfx-devcontainer for more information\n**********"

samples/react-copilot-chatbubble-with-sso/.gitignore

@@ -0,0 +1,34 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Dependency directories
+node_modules
+
+# Build generated files
+dist
+lib
+release
+solution
+temp
+*.sppkg
+.heft
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# OSX
+.DS_Store
+
+# Visual Studio files
+.ntvs_analysis.dat
+.vs
+bin
+obj
+
+# Resx Generated Code
+*.resx.ts
+
+# Styles Generated Code
+*.scss.ts

samples/react-copilot-chatbubble-with-sso/.npmignore

@@ -0,0 +1,16 @@
+!dist
+config
+
+gulpfile.js
+
+release
+src
+temp
+
+tsconfig.json
+tslint.json
+
+*.log
+
+.yo-rc.json
+.vscode

samples/react-copilot-chatbubble-with-sso/.nvmrc

@@ -0,0 +1 @@
+v18.18.2

samples/react-copilot-chatbubble-with-sso/.yo-rc.json

@@ -0,0 +1,21 @@
+{
+  "@microsoft/generator-sharepoint": {
+    "plusBeta": false,
+    "isCreatingSolution": true,
+    "nodeVersion": "18.18.2",
+    "sdksVersions": {
+      "@microsoft/microsoft-graph-client": "3.0.2",
+      "@microsoft/teams-js": "2.24.0"
+    },
+    "version": "1.20.0",
+    "libraryName": "react-chatbubble-copilot",
+    "libraryId": "58424e7a-fc64-4330-ba0f-8f309aab34f2",
+    "environment": "spo",
+    "packageManager": "npm",
+    "solutionName": "react-chatbubble-copilot",
+    "solutionShortDescription": "React-CoPilot-With-SSO description",
+    "skipFeatureDeployment": true,
+    "isDomainIsolated": false,
+    "componentType": "webpart"
+  }
+}

samples/react-copilot-chatbubble-with-sso/README.md

@@ -0,0 +1,122 @@
+# Copilot Chat Bubble - With SSO which summarizes sessions at ESPC 2024
+
+## Summary
+
+This web part integrates the Microsoft Copilot Agent, built via Copilot Studio, into SharePoint Online featuring Single Sign-on and a chat interface.  
+
+For sample purpose, I have built a CoPilot agent which will summarize sessions at ESPC 2024, and Provides a concise summary of all sessions and topics covered at ESPC 2024, including key take aways and speakers insights.
+
+![Webpart UI](images/SPFxUI.png)
+
+![Example1](images/Example1.gif)
+
+![Example2](images/Example2.gif)
+
+The webpart uses Cache management to store the webpart properties, which is fetched from the list. 
+
+![Webpart Properties](images/Cache.png)
+
+### Webpart properties
+
+This webpart reads the configuration from a configuration list as CopilotAgentConfig.
+- Create the "CopilotAgentConfig" list with below columns
+
+
+|Property Name|Column type|Explanation|Mandatory?|
+| :- | :- | :- | :- |
+|BotName|Single line of text|Name of the Bot|No|
+|BotURL|Single line of text|The token endpoint for MCS. This can be found in the CoPilot studio, under Settings -> Channels -> Mobile App (Screenshot below)|Yes|
+|BotAvatarImage|Single line of text|Direct link for the avatar image|No|
+|BotAvatarInitials|Single line of text|bot initials used when no image present|No|
+|Greet|Yes/No|Should the copilot greet users at the beginning of the conversation|No|
+|CustomScope|Single line of text|<p>The scope defined for the custom API in the copilot app registration (Step 1). For example:</p><p></p><p>api://35337616-eee1-4049-9d37-a78b24c3bef2/SPO.Read</p>|Yes|
+|ClientID|Single line of text|The Application ID from the Canvas app registration configured in step 2|Yes|
+|Authority|Single line of text|<p>The login URL for your tenant. For example:<br>https://login.microsoftonline.com/mytenant.onmicrosoft.com|Yes|
+|ErrorRetryAttempts|Single line of text|Number of retry attempts made to get the properties from the List|Yes|No|
+
+
+
+![BotURL](images/BotURL.png)
+
+
+## Compatibility
+
+| :warning: Important          |
+|:---------------------------|
+| Every SPFx version is optimally compatible with specific versions of Node.js. In order to be able to build this sample, you need to ensure that the version of Node on your workstation matches one of the versions listed in this section. This sample will not work on a different version of Node.|
+|Refer to <https://aka.ms/spfx-matrix> for more information on SPFx compatibility.   |
+
+This sample is optimally compatible with the following environment configuration:
+
+![SPFx 1.20.2](https://img.shields.io/badge/SPFx-1.20.2-green.svg)
+![Node.js v18](https://img.shields.io/badge/Node.js-v18-green.svg)
+![Compatible with SharePoint Online](https://img.shields.io/badge/SharePoint%20Online-Compatible-green.svg)
+![Does not work with SharePoint 2019](https://img.shields.io/badge/SharePoint%20Server%202019-Incompatible-red.svg "SharePoint Server 2019 requires SPFx 1.4.1 or lower")
+![Does not work with SharePoint 2016 (Feature Pack 2)](https://img.shields.io/badge/SharePoint%20Server%202016%20(Feature%20Pack%202)-Incompatible-red.svg "SharePoint Server 2016 Feature Pack 2 requires SPFx 1.1")
+![Local Workbench Unsupported](https://img.shields.io/badge/Local%20Workbench-Unsupported-red.svg "Local workbench is no longer available as of SPFx 1.13 and above")
+![Hosted Workbench Compatible](https://img.shields.io/badge/Hosted%20Workbench-Compatible-green.svg)
+![Compatible with Remote Containers](https://img.shields.io/badge/Remote%20Containers-Compatible-green.svg)
+
+
+## Applies to
+
+- [SharePoint Framework](https://aka.ms/spfx)
+- [Microsoft 365 tenant](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-developer-tenant)
+
+> Get your own free development tenant by subscribing to [Microsoft 365 developer program](http://aka.ms/o365devprogram)
+
+
+## Contributors
+
+- [Nishkalank Bezawada](https://github.com/NishkalankBezawada)
+
+## Version history
+
+| Version | Date             | Comments        |
+| ------- | ---------------- | --------------- |
+| 1.0     | January 10, 2025 | Initial release |
+
+
+## Minimal path to awesome
+
+For details setup instructions, please refer to the [Setup.md](Setup.md) file.
+
+## Features
+
+This sample illustrates the following concepts:
+
+- Microsoft CoPilot Integration
+- Chat Interface
+- Single Sign-On (SSO)
+- Customizable according to organizational needs
+- Secure
+
+
+## References
+
+- [Copilot Studio - Building SharePoint SSO Component](https://github.com/microsoft/CopilotStudioSamples/tree/master/SharePointSSOComponent?wt.mc_id=MVP_331342) 
+
+
+## Help
+
+
+We do not support samples, but this community is always willing to help, and we want to improve these samples. We use GitHub to track issues, which makes it easy for  community members to volunteer their time and help resolve issues.
+
+If you're having issues building the solution, please run [spfx doctor](https://pnp.github.io/cli-microsoft365/cmd/spfx/spfx-doctor/) from within the solution folder to diagnose incompatibility issues with your environment.
+
+You can try looking at [issues related to this sample](https://github.com/pnp/sp-dev-fx-webparts/issues?q=label%3A%22sample%3A%20react-copilot-chatbubble-with-sso%22) to see if anybody else is having the same issues.
+
+You can also try looking at [discussions related to this sample](https://github.com/pnp/sp-dev-fx-webparts/discussions?discussions_q=react-copilot-chatbubble-with-sso) and see what the community is saying.
+
+If you encounter any issues using this sample, [create a new issue](https://github.com/pnp/sp-dev-fx-webparts/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Abug-suspected%2Csample%3A%20react-copilot-chatbubble-with-sso&template=bug-report.yml&sample=react-copilot-chatbubble-with-sso&authors=@NishkalankBezawada&title=react-copilot-chatbubble-with-sso%20-%20).
+
+For questions regarding this sample, [create a new question](https://github.com/pnp/sp-dev-fx-webparts/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Aquestion%2Csample%3A%20react-copilot-chatbubble-with-sso&template=question.yml&sample=react-copilot-chatbubble-with-sso&authors=@NishkalankBezawada&title=react-copilot-chatbubble-with-sso%20-%20).
+
+Finally, if you have an idea for improvement, [make a suggestion](https://github.com/pnp/sp-dev-fx-webparts/issues/new?assignees=&labels=Needs%3A+Triage+%3Amag%3A%2Ctype%3Aenhancement%2Csample%3A%20react-copilot-chatbubble-with-sso&template=suggestion.yml&sample=react-copilot-chatbubble-with-sso&authors=@NishkalankBezawada&title=react-copilot-chatbubble-with-sso%20-%20).
+
+## 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.**
+
+<img src="https://m365-visitor-stats.azurewebsites.net/sp-dev-fx-webparts/samples/react-copilot-chatbubble-with-sso" />
+

samples/react-copilot-chatbubble-with-sso/Setup.md

@@ -0,0 +1,119 @@
+# Deploy a Microsoft Copilot Studio copilot as a SharePoint component with single sign-on (SSO) enabled
+
+To follow through the end-to-end setup process, you would need to:
+
+1. Configure Microsoft Entra ID authentication for your copilot.
+2. Register your SharePoint site as a canvas app – an application that will host your copilot and handle the single sign-on flow.
+3. Build the SharePoint component and configure its properties based on values from step (2).
+4. Upload the component to SharePoint and add the component to your site.
+
+## Step 1 - Configure Microsoft Entra ID authentication for your copilot
+
+This step can be completed mostly by following the instructions here: [Configure user authentication with Microsoft Entra ID](https://learn.microsoft.com/en-us/power-virtual-agents/configuration-authentication-azure-ad), with some added configuration which is specified below.
+
+1. **Optional – add scopes for SharePoint and OneDrive**. For your copilot to use the Generative Answers capability over a SharePoint or OneDrive data source, you would need to configure additional scopes for the API permissions assigned to your app. Please refer to [Generative answers with Search and summarize: Authentication](https://learn.microsoft.com/en-us/power-virtual-agents/nlu-boost-node#authentication).
+
+<p align="center">
+  <img src="./images/APIPermissions.png" alt="API Permissions">
+  <br>
+  <em>API Permissions of the copilot app registration</em>
+</p>
+
+2. **Mandatory – populate the token exchange URL in the copilot’s authentication settings.** Your copilot will send this URL to any custom application hosting it, instructing the custom application it should sign users in by acquiring a token matching this custom scope. The value for “token exchange URL” is the full URI for the custom scope you have added when configuring a custom API.
+
+<p align="center">
+  <img src="./images/customScope.png" alt="Custom Scope">
+  <br>
+  <em>The custom scope for the copilot app registration</em>
+</p>
+<br/>
+<p align="center">
+  <img src="./images/tokenExchange.png" alt="Authentication Settings">
+  <br>
+  <em>Authentication configuration of the copilot, including token exchange URL</em>
+</p>
+
+Once all the steps under [Configure user authentication with Microsoft Entra ID](https://learn.microsoft.com/en-us/power-virtual-agents/configuration-authentication-azure-ad) have been completed and the optional additional scopes have been specified, you should be able to use Generative Answers over a SharePoint or OneDrive data source from the Microsoft Copilot Studio authoring experience. Please refer to [Use content on SharePoint or OneDrive for Business for generative answers](https://learn.microsoft.com/en-us/power-virtual-agents/nlu-generative-answers-sharepoint-onedrive) for instructions on add a SharePoint or OneDrive data source for your Copilot Generative Answers node.
+
+Before moving to Step 2, make sure the Copilot Studio authoring canvas can successfully sign you in. If "Require users to sign in" is selected in the authentication settings, the canvas will try to sign in you in as soon as the conversation starts. Otherwise, the-sign in topic will have to be triggered by a specific event in the conversation. In case Generative Answers is configured over SharePoint or OneDrive, please make sure your copilot responds to questions as expected.
+
+**Important:** For now, the copilot canvas will use a validation code to sign you in, but once the setup is complete, users will be signed-in seamlessly.
+
+## Step 2 - Register your SharePoint site as a custom canvas
+
+A custom canvas is a custom application that hosts your copilot. In our case, it is also the application that will be responsible for a seamless sign-in experience.
+
+In order to configure your SharePoint site as a canvas application with single sign-on enabled, follow the steps specified in [Configure single sign-on with Microsoft Entra ID](https://learn.microsoft.com/en-us/power-virtual-agents/configure-sso?tabs=webApp#create-app-registrations-for-your-custom-website).
+
+When configuring the canvas app registration, pay attention to the following details:
+
+1. When adding a platform to the canvas app registration, select “Single-page application” and not “Web”. Web redirect URIs only support the implicit grant flow for authentication, which is considered less secure and cannot be used with MSAL.js 2.x, which is the authentication library included in the code sample provided here. For a discussion about the differences between Web and SPA redirects, please refer to: [https://github.com/MicrosoftDocs/azure-docs/issues/70484#issuecomment-791077654](https://github.com/MicrosoftDocs/azure-docs/issues/70484#issuecomment-791077654)
+
+2. The redirect URI should be the same as the URL for your SharePoint site that will host the copilot. For example, if you plan to deploy the copilot on <https://mytenant.sharepoint.com/sites/MySite>, set this as your redirect URI.
+
+   **Important:** Users can reach your SharePoint site via addresses that include trailing slashes. Since redirect URIs are sensitive to this variation, consider creating two redirect URIs representing the same site, with and without a trailing slash (for example: <https://mytenant.sharepoint.com/sites/MySite> and <https://mytenant.sharepoint.com/sites/MySite/>)
+
+3. The canvas app registration will need permissions for the custom API that was configured in *Step 1*. To add this permission, select an API from “APIs my organization uses” and search for the name you have given your copilot app registration in *Step 1*. For example, if your copilot app registration is called “SharePoint Bot Authentication” search for that name in the list of APIs, and select your custom scope (a name for your custom scope has been selected while configuring a custom API for your copilot app registration)
+
+<p align="center">
+  <img src="./images/apisMyOrganization.png" alt="APIs my organization uses">
+  <br>
+  <em>The API can be found under “APIs my organization uses”</em>
+</p>
+<br/>
+<p align="center">
+  <img src="./images/scopePermissions.png" alt="Permissions for the custom scope">
+  <br>
+  <em>Selecting the scope for the API</em>
+</p>
+
+4. After registering your canvas app, you will not have to use the code sample the page refers to. The code sample provided is a standalone web page implementing SSO for Microsoft Copilot Studio which can be used for testing purposes, but it is not a SharePoint component.
+
+   However, you will need to document the Application (client) ID for the SharePoint component configuration in the next step.
+
+<p align="center">
+  <img src="./images/clientID.png" alt="Document the Client ID">
+  <br>
+  <em>The Application (client) ID</em>
+</p>
+
+## Step 3 - Download and configure the SharePoint SPFx web part
+
+Make sure your development environment includes the following tools and libraries:
+
+   1. VS Code (or a similar code editor)
+   2. A version of Node.JS which is [supported by the SPFx framework](https://learn.microsoft.com/en-us/sharepoint/dev/spfx/compatibility#spfx-development-environment-compatibility) (for this sample, use v18)
+   3. A [Git](https://git-scm.com/downloads)  client for your OS
+   4. Clone this repo
+   5. Run the following commands to package the solution
+      1. `npm install`
+      2. `gulp bundle --shp`
+      3. `gulp package-solution --ship`
+
+### Webpart properties
+
+This webpart reads the configuration from a configuration list as CopilotAgentConfig.
+- Create the "CopilotAgentConfig" list with below columns
+
+
+|Property Name|Column type|Explanation|Mandatory?|
+| :- | :- | :- | :- |
+|BotName|Single line of text|Name of the Bot|No|
+|BotURL|Single line of text|The token endpoint for MCS. This can be found in the CoPilot studio, under Settings -> Channels -> Mobile App (Screenshot below)|Yes|
+|BotAvatarImage|Single line of text|Direct link for the avatar image|No|
+|BotAvatarInitials|Single line of text|bot initials used when no image present|No|
+|Greet|Yes/No|Should the copilot greet users at the beginning of the conversation|No|
+|CustomScope|Single line of text|<p>The scope defined for the custom API in the copilot app registration (Step 1). For example:</p><p></p><p>api://35337616-eee1-4049-9d37-a78b24c3bef2/SPO.Read</p>|Yes|
+|ClientID|Single line of text|The Application ID from the Canvas app registration configured in step 2|Yes|
+|Authority|Single line of text|<p>The login URL for your tenant. For example:<br>https://login.microsoftonline.com/mytenant.onmicrosoft.com|Yes|
+|ErrorRetryAttempts|Single line of text|Number of retry attempts made to get the properties from the List|Yes|No|
+
+
+
+After adding the web part on the page and configure with required properties, you will see the chat canvas for your copilot. Based on the logic of your copilot, users will be signed in automatically at the beginning of the conversation, or when a specific event occurs.
+
+![Webpart UI](images/SPFxUI.png)
+
+![Example1](images/Example1.gif)
+
+![Example2](images/Example2.gif)