From 9a8de9c628eed5c103ea230b0339d88f57ee6724 Mon Sep 17 00:00:00 2001 From: Qiong Wu Date: Wed, 16 Dec 2020 12:02:17 +0800 Subject: [PATCH] fix doc --- samples/react-bot-framework-secure/README.md | 39 ++++----- .../extension/README.md | 8 +- samples/react-bot-framework-sso/README.md | 87 +++++++++++-------- .../extension/config/package-solution.json | 2 +- 4 files changed, 74 insertions(+), 62 deletions(-) diff --git a/samples/react-bot-framework-secure/README.md b/samples/react-bot-framework-secure/README.md index 50d12ad62..d4ff35683 100644 --- a/samples/react-bot-framework-secure/README.md +++ b/samples/react-bot-framework-secure/README.md @@ -20,7 +20,7 @@ This demo does not include any threat models and is designed for educational pur ## Used SharePoint Framework Version -![1.0](https://img.shields.io/badge/version-1.0-green.svg) +![SPFx 1.10.0](https://img.shields.io/badge/drop-1.10.0-green.svg) ## Applies to @@ -41,8 +41,8 @@ This demo does not include any threat models and is designed for educational pur Solution|Author(s) --------|--------- -webpart | STCA BF Channel and ABS (stcabfchannel@microsoft.com)
Stephan Bisser (@stephanbisser, bisser.io) -bot | STCA BF Channel and ABS (stcabfchannel@microsoft.com) +extension | Bot Framework Discussions (msbots@service.microsoft.com)
Stephan Bisser (@stephanbisser, bisser.io) +bot | Bot Framework Discussions (msbots@service.microsoft.com) ## Version history @@ -63,24 +63,33 @@ Version|Date|Comments - Clone the repository ```bash - git clone [Placeholder] + git clone https://github.com/pnp/sp-dev-fx-extensions ``` -- In a terminal, navigate to `[Placeholder]` +- In a terminal, navigate to `sp-dev-fx-extensions` ```bash - cd [Placeholder] + cd sp-dev-fx-extensions + ``` + +- Navigate to the folder containing this sample + + ```bash + cd samples + cd react-bot-framework-secure ``` ### [Setup bot](./bot/README.md) +- Go to `./bot` + - Install modules ```bash npm install ``` -- Register Connections. You can get it done by [deploy your bot to Azure](https://aka.ms/azuredeployment). Save your bot service endpoint like: "https://YOUR_BOT.azurewebsites.net". Save your AAD Id as YOUR_APP_ID and secret as YOUR_APP_PSW. +- Register Connections. You can get it done by [deploy your bot to Azure](https://aka.ms/azuredeployment). Save your bot service endpoint like: "https://YOUR_BOT.azurewebsites.net". Save your AAD Id as `YOUR_APP_ID` and secret as `YOUR_APP_PSW`. - [Connect to direct line](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-directline?view=azure-bot-service-4.0), copy one of the Secret Key values as YOUR_DIRECT_LINE_SECRET and store this for later usage. This is your ‘Direct Line Secret’. @@ -96,28 +105,18 @@ Version|Date|Comments ### [Setup extension](./extension/README.md) -- Install modules - - ```bash - npm install - ``` - - Edit "BotFrameworkChatPopupApplicationChat.tsx" file to set your bot endpoint (`props.botEndpoint`) directly like `https://YOUR_BOT.azurewebsites.net` for testing purpose (instead of setting it in the Tenant Wide Extensions list): ```ts - generateToken(props.botEndpoint, md5(userId)).then((token: string) => { //change props.botEndpoint to the endpoint directly if you want to test it - if (token) { - setDirectLine(createDirectLine({ token })); - } - }); + const token = await this.generateToken(this.props.botEndpoint, md5(userId)); ``` - Config CORS \ [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) must be set on bot app service to enable SharePoint client to get resource from bot service. Follow these steps to add your workbench to bot app service CORS configration: 1. Go to your azure portal - 1. Navigate to your bot app service, search for CORS settings - 1. Add https://localhost:4321 and https://.sharepoint.com to CORS origins + 2. Navigate to your bot app service, search for CORS settings + 3. Add https://localhost:4321 and https://.sharepoint.com to CORS origins - In the command line run diff --git a/samples/react-bot-framework-secure/extension/README.md b/samples/react-bot-framework-secure/extension/README.md index aae74124c..acb41adb7 100644 --- a/samples/react-bot-framework-secure/extension/README.md +++ b/samples/react-bot-framework-secure/extension/README.md @@ -31,11 +31,7 @@ An extension sample that uses the [botframework-webchat module](https://www.npmj - Edit "BotFrameworkChatPopupApplicationChat.tsx" file to set your bot endpoint (`props.botEndpoint`) directly like `https://YOUR_BOT.azurewebsites.net` for testing purpose (instead of setting it in the Tenant Wide Extensions list): ```ts - generateToken(props.botEndpoint, md5(userId)).then((token: string) => { //change props.botEndpoint to the endpoint directly if you want to test it - if (token) { - setDirectLine(createDirectLine({ token })); - } - }); + const token = await this.generateToken(this.props.botEndpoint, md5(userId)); ``` - In the command line run @@ -67,3 +63,5 @@ This Extension illustrates the following concepts on top of the SharePoint Frame - Using the Bot Framework webchat React component as some kind of flyout element in modern pages - Adding a bot to modern pages and let users interact with a bot hosted in the Azure Bot Service + + \ No newline at end of file diff --git a/samples/react-bot-framework-sso/README.md b/samples/react-bot-framework-sso/README.md index e1737f601..3515dc04d 100644 --- a/samples/react-bot-framework-sso/README.md +++ b/samples/react-bot-framework-sso/README.md @@ -1,4 +1,4 @@ -# Sharepoint extension sample with SSO +# SharePoint extension sample with SSO ## Summary @@ -20,7 +20,7 @@ This demo does not include any threat models and is designed for educational pur ## Used SharePoint Framework Version -![SPFx 1.10](https://img.shields.io/badge/version-1.10-green.svg) +![SPFx 1.10.0](https://img.shields.io/badge/drop-1.10.0-green.svg) ## Applies to @@ -48,8 +48,8 @@ This demo does not include any threat models and is designed for educational pur Solution|Author(s) --------|--------- -webpart | STCA BF Channel and ABS (stcabfchannel@microsoft.com)
Stephan Bisser (@stephanbisser, bisser.io) -bot | STCA BF Channel and ABS (stcabfchannel@microsoft.com) +extension | Bot Framework Discussions (msbots@service.microsoft.com)
Stephan Bisser (@stephanbisser, bisser.io) +bot | Bot Framework Discussions (msbots@service.microsoft.com) ## Version history @@ -70,30 +70,37 @@ Version|Date|Comments - Clone the repository ```bash - git clone [Placeholder] + git clone https://github.com/pnp/sp-dev-fx-extensions ``` -### [Setup bot with Direct Line](./bot/README.md) +- In a terminal, navigate to `sp-dev-fx-extensions` -This part is the same as [the extension web chat sample](Placeholder). + ```bash + cd sp-dev-fx-extensions + ``` -- In a terminal, navigate to `[Placeholder]` +- Navigate to the folder containing this sample ```bash - cd [Placeholder] + cd samples + cd react-bot-framework-sso ``` +### [Setup bot with Direct Line](./bot/README.md) + +- Go to `./bot` + - Install modules ```bash npm install ``` -- Register connections. You can get it done by [deploy your bot to Azure](https://aka.ms/azuredeployment). Save your bot service endpoint like: "https://YOUR_BOT.azurewebsites.net". Save your AAD Id as YOUR_APP_ID, AAD Name as YOUR_APP_Name and secret as YOUR_APP_PSW. +- Register connections. You can get it done by [deploy your bot to Azure](https://aka.ms/azuredeployment). Save your bot service endpoint like: "https://YOUR_BOT.azurewebsites.net". Save your AAD Id as `YOUR_APP_ID`, AAD Name as `YOUR_APP_Name` and secret as `YOUR_APP_PSW`. -- [Connect to direct line](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-directline?view=azure-bot-service-4.0), copy one of the Secret Key values as YOUR_DIRECT_LINE_SECRET and store this for later. This is your ‘Direct Line Secret’. +- [Connect to direct line](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-directline?view=azure-bot-service-4.0), copy one of the Secret Key values as `YOUR_DIRECT_LINE_SECRET` and store this for later. This is your `Direct Line Secret`. -- Add ‘Direct Line Secret’ to an .env config file under ./bot +- Add `Direct Line Secret` to an .env config file under ./bot ```bash MicrosoftAppId=YOUR_APP_ID @@ -110,7 +117,7 @@ application setup for use in Azure Bot Service. - Open your bot's application registration - Save the tenant ID - Select the "Overview" blade - - On the main pane, copy the content of "Directory (tenant) ID" as YOUR_APP_TENANT and store this for later + - On the main pane, copy the content of "Directory (tenant) ID" as `YOUR_APP_TENANT` and store this for later - Update Authentication - Select the "Authentication" blade - Click "Add a platform" to add web if Web is not added @@ -122,7 +129,7 @@ application setup for use in Azure Bot Service. - Select the "Expose an API" blade - Click the "Add a scope" button under "Scopes defined by this API" - Click "Save and continue" - - Add a scope named YOUR_AAD_SCOPE_NAME + - Add a scope named `YOUR_AAD_SCOPE_NAME` - Set "Who can consent?" to "Admins and users" - Add an admin consent display name - Add an admin consent description @@ -131,7 +138,7 @@ application setup for use in Azure Bot Service. - api://123a45b6-789c-01de-f23g-h4ij5k67a8bc/ - Select API permissions - Click "API Permissions", select"Add a permission" - - Select "My APIs", YOUR_APP_ID, and enable YOUR_AAD_SCOPE_NAME scope \ + - Select "My APIs", `YOUR_APP_ID`, and enable `YOUR_AAD_SCOPE_NAME` scope \ Otherwise the non-admin user cannot use SSO. ### Setup Authentication via Azure Bot Services for the Bot @@ -192,10 +199,19 @@ application setup for use in Azure Bot Service. ], ``` -- [Publish and host webpart](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn), prepare for approving permissions +- Install modules + + ```bash + cd ../extension + npm install + ``` + +- [Publish and host extension](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/extensions/get-started/hosting-extension-from-office365-cdn), prepare for approving permissions - Refer [Connect to Azure AD-secured APIs](https://docs.microsoft.com/en-us/sharepoint/api-access) to publish and approve permissions from admin site - - Go to sharepoint admin center + - Please ensure your service principal had been enabled for your AAD account. + - Check "Managed application in local directory" in your AAD overview blade in Azure Portal + - Go to SharePoint admin center - Find "API Access", approve "" - (Opt. for hosted bot service) Config CORS \ @@ -204,22 +220,6 @@ application setup for use in Azure Bot Service. 2. Navigate to your bot app service, search for CORS settings 3. Add https://localhost:4321 and https://.sharepoint.com to CORS origins -- In the command line run - - ```bash - cd ../extension - npm install - gulp serve --nobrowser - ``` - -- Open up a SharePoint modern page and add the following string to your URL: - - ```url - ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"f50b07b5-76a5-4e80-9cab-b4ee9a591bf6":{"location":"ClientSideExtension.ApplicationCustomizer"}} - ``` - - If you want to deploy it follow the steps [here](./extension/README.md#deploy). - ### Setup OAuth via Azure Active Directory for the SharePoint The following operations will need an admin account. @@ -228,7 +228,7 @@ The following operations will need an admin account. - Open "App registrations", find "SharePoint Online Client Extensibility Web Application Principal" - Save the client ID - Select the "Overview" blade - - On the main pane, copy the content of "Application ID" as YOUR_SHAREPOINT_ID and store this for later usage + - On the main pane, copy the content of "Application ID" as `YOUR_SHAREPOINT_ID` and store this for later usage - Update App Registration Manifest - Select the "Manifest" blade - Set `accessTokenAcceptedVersion` to `2` @@ -238,10 +238,25 @@ The following operations will need an admin account. - Open your bot's application registration - Select the "Expose an API" blade - Click the "Add a client application" under "Authorized client applications" - - Set the client id to the YOUR_SHAREPOINT_ID + - Set the client id to the `YOUR_SHAREPOINT_ID` - Check the box next to the scope we added in the previous step under "Authorized scopes" - Click "Add application" +### Test extension +- Go to `extension` folder, in the command line run + + ```bash + gulp serve --nobrowser + ``` + +- Open up a SharePoint modern page and add the following string to your URL: + + ```url + ?loadSPFX=true&debugManifestsFile=https://localhost:4321/temp/manifests.js&customActions={"f50b07b5-76a5-4e80-9cab-b4ee9a591bf6":{"location":"ClientSideExtension.ApplicationCustomizer"}} + ``` + + If you want to deploy it follow the steps [here](./extension/README.md#deploy). + ## Features **Web Chat integration with SSO** @@ -335,7 +350,7 @@ const handleClick = useCallback(() => { Note: The first time users try SSO, users may be presented with an OAuth card to log in. This is because users have not yet given consent to the bot's Azure AD app. To avoid this, users can grant admin consent for any graph permissions requested by the Azure AD app. -Note: due to a SDK bug [here](https://github.com/microsoft/botbuilder-js/issues/3006), the consent card could not be shown properly yet. Granting admin consent may be necessary to workaround this. +Note: due to a [SDK bug](https://github.com/microsoft/botbuilder-js/issues/3006), the consent card could not be shown properly yet. Granting admin consent may be necessary to workaround this. ## Debug URL for testing diff --git a/samples/react-bot-framework-sso/extension/config/package-solution.json b/samples/react-bot-framework-sso/extension/config/package-solution.json index 10574b7c4..1f2b87b98 100644 --- a/samples/react-bot-framework-sso/extension/config/package-solution.json +++ b/samples/react-bot-framework-sso/extension/config/package-solution.json @@ -9,7 +9,7 @@ "isDomainIsolated": false, "webApiPermissionRequests": [ { - "resource": "", + "resource": "", "scope": "" } ],