honeymoose
/
sp-dev-fx-webparts
mirror of https://github.com/pnp/sp-dev-fx-webparts.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated readme

This commit is contained in:
Hugo Bernier 2020-11-07 15:32:11 -05:00
parent 725020797e
commit f35585bcc8
3 changed files with 43 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
samples/react-bot-framework-sso/README.md
View File

@ -1,4 +1,4 @@
# Sharepoint webpart sample with SSO # SharePoint webpart sample with SSO
## Summary ## Summary
@ -20,7 +20,7 @@ This demo does not include any threat models and is designed for educational pur
## Used SharePoint Framework Version ## 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/version-1.10.0-green.svg)
## Applies to ## Applies to
@ -70,15 +70,22 @@ Version|Date|Comments
- Clone the repository - Clone the repository
```bash ```bash
git clone [Placeholder] git clone https://github.com/pnp/sp-dev-fx-webparts.git
``` ```
### [Setup bot with Direct Line](./bot/README.md) ### [Setup bot with Direct Line](./bot/README.md)
- In a terminal, navigate to `[Placeholder]` - In a terminal, navigate to `sp-dev-fx-webparts`
```bash ```bash
cd [Placeholder] cd sp-dev-fx-webparts
```
- Navigate to the folder for this solution:
```base
cd samples
cd react-bot-framework-sso
``` ```
- Install modules - Install modules
@ -87,11 +94,11 @@ Version|Date|Comments
npm install 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 also. - 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` also.
- [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 `DirectLineSecret` to an `.env` config file under `./bot`
```bash ```bash
MicrosoftAppId=YOUR_APP_ID MicrosoftAppId=YOUR_APP_ID
@ -108,7 +115,7 @@ application setup for use in Azure Bot Service.
- Open your bot's application registration - Open your bot's application registration
- Save the tenant ID - Save the tenant ID
- Select the "Overview" blade - 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 - Update Authentication
- Select the "Authentication" blade - Select the "Authentication" blade
- Click "Add a platform" to add web if Web is not added - Click "Add a platform" to add web if Web is not added
@ -120,7 +127,7 @@ application setup for use in Azure Bot Service.
- Select the "Expose an API" blade - Select the "Expose an API" blade
- Click the "Add a scope" button under "Scopes defined by this API" - Click the "Add a scope" button under "Scopes defined by this API"
- Click "Save and continue" - 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" - Set "Who can consent?" to "Admins and users"
- Add an admin consent display name - Add an admin consent display name
- Add an admin consent description - Add an admin consent description
@ -129,12 +136,12 @@ application setup for use in Azure Bot Service.
- api://123a45b6-789c-01de-f23g-h4ij5k67a8bc/<YOUR_AAD_SCOPE_NAME> - api://123a45b6-789c-01de-f23g-h4ij5k67a8bc/<YOUR_AAD_SCOPE_NAME>
- Select API permissions - Select API permissions
- Click "API Permissions", select"Add a permission" - 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. Otherwise the non-admin user cannot use SSO.
### Setup Authentication via Azure Bot Services for the Bot ### Setup Authentication via Azure Bot Services for the Bot
[Check here](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-tutorial-authentication?view=azure-bot-service-3.0&tabs=aadv1) for more information about adding authentication to your bot. Check the [Add authentication to your bot via Azure Bot Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-tutorial-authentication?view=azure-bot-service-3.0&tabs=aadv1) article for more information about adding authentication to your bot.
- Add OAuth Connection for the bot to the Bot Channel Registration - Add OAuth Connection for the bot to the Bot Channel Registration
- In the Bot Channel Registration open the settings blade - In the Bot Channel Registration open the settings blade
@ -142,14 +149,14 @@ application setup for use in Azure Bot Service.
- Add new Connection Setting - Add new Connection Setting
- Set the connection "Name" - Set the connection "Name"
- Set the "Service Provider" to "Azure Active Directory 2" - Set the "Service Provider" to "Azure Active Directory 2"
- Add the Client ID as YOUR_APP_ID, Client secret as YOUR_APP_PSW, and Tenant ID as YOUR_APP_TENANT - Add the Client ID as `YOUR_APP_ID`, Client secret as `YOUR_APP_PSW`, and Tenant ID as `YOUR_APP_TENANT`
- Set the "Token Exchange URL" to the scope URL that was created in the previous section - Set the "Token Exchange URL" to the scope URL that was created in the previous section
- api://123a45b6-789c-01de-f23g-h4ij5k67a8bc/<YOUR_AAD_SCOPE_NAME> - api://123a45b6-789c-01de-f23g-h4ij5k67a8bc/<YOUR_AAD_SCOPE_NAME>
- Set the "Scopes" field to the scopes you want the bot to have permission to access (ie. user.read) - Set the "Scopes" field to the scopes you want the bot to have permission to access (ie. `user.read`)
### Republish bot ### Republish bot
- Update `.env` with ConnectionName to .env config file under ./bot - Update `.env` with `ConnectionName` to `.env` config file under `./bot`
```bash ```bash
ConnectionName=YOUR_CONNECTION_NAME ConnectionName=YOUR_CONNECTION_NAME
@ -163,13 +170,13 @@ application setup for use in Azure Bot Service.
### [Setup web parts](./webpart/README.md) ### [Setup web parts](./webpart/README.md)
- Edit "BotSignInToast.tsx" file to set your AAD scope uri(`scopeUri`) with `api://YOUR_APP_ID` directly like `api://123a45b6-789c-01de-f23g-h4ij5k67a8bc`: - Edit `BotSignInToast.tsx` to set your AAD scope uri(`scopeUri`) with `api://YOUR_APP_ID` directly like `api://123a45b6-789c-01de-f23g-h4ij5k67a8bc`:
```ts ```ts
return tokenProvider.getToken(scopeUri, true).then((token: string) => { return tokenProvider.getToken(scopeUri, true).then((token: string) => {
``` ```
- Add the following config to ./config/package-solution.json: - Add the following config to `./config/package-solution.json`:
```diff ```diff
"webApiPermissionRequests": [ "webApiPermissionRequests": [
@ -183,11 +190,11 @@ 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 - [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
- Refer [Connect to Azure AD-secured APIs](https://docs.microsoft.com/en-us/sharepoint/api-access) to publish and approve permissions from admin site - 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 - Go to SharePoint admin center
- Find "API Access", approve "<YOUR_APP_Name>" - Find "API Access", approve "<YOUR_APP_Name>"
- (Opt. for hosted bot service) Config CORS \ - (Opt. for hosted bot service) 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: [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 configuration:
1. Go to your azure portal 1. Go to your azure portal
2. Navigate to your bot app service, search for CORS settings 2. Navigate to your bot app service, search for CORS settings
3. Add https://localhost:4321 and https://<YOUR_SITE>.sharepoint.com to CORS origins 3. Add https://localhost:4321 and https://<YOUR_SITE>.sharepoint.com to CORS origins
@ -203,7 +210,7 @@ application setup for use in Azure Bot Service.
Now web parts is running locally. Now web parts is running locally.
- Open online test page with user account: https://<YOUR_SITE>.sharepoint.com/_layouts/15/Workbench.aspx - Open online test page with user account: https://<YOUR_SITE>.sharepoint.com/_layouts/15/Workbench.aspx
- Config bot endpoint \ - Config bot endpoint \
Add the web parts, set bot endpoint to https://YOUR_BOT.azurewebsites.net, refresh this page, then you can successfully connet bot with SharePoint. Add the web parts, set bot endpoint to https://YOUR_BOT.azurewebsites.net, refresh this page, then you can successfully connect bot with SharePoint.
### Setup OAuth via Azure Active Directory for the SharePoint ### Setup OAuth via Azure Active Directory for the SharePoint
@ -223,7 +230,7 @@ The following operations will need an admin account.
- Open your bot's application registration - Open your bot's application registration
- Select the "Expose an API" blade - Select the "Expose an API" blade
- Click the "Add a client application" under "Authorized client applications" - 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" - Check the box next to the scope we added in the previous step under "Authorized scopes"
- Click "Add application" - Click "Add application"
@ -320,7 +327,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: 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.
## Further reading ## Further reading

23
samples/react-bot-framework-sso/bot/README.md
View File

@ -23,18 +23,6 @@ application setup for use in Azure Bot Service. The [scopes](https://developer.m
## To try this sample ## To try this sample
- Clone the repository
```bash
git clone [Placeholder]
```
- In a terminal, navigate to `[Placeholder]`
```bash
cd [Placeholder]
```
- Install modules - Install modules
```bash ```bash
@ -51,7 +39,7 @@ application setup for use in Azure Bot Service. The [scopes](https://developer.m
[Microsoft Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel. [Microsoft Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.
- Install the Bot Framework Emulator from [here](https://github.com/microsoft/botframework-emulator/releases) - Install the [Bot Framework Emulator](https://github.com/microsoft/botframework-emulator/releases)
- In Bot Framework Emulator Settings, enable `Use a sign-in verification code for OAuthCards` to receive the magic code - In Bot Framework Emulator Settings, enable `Use a sign-in verification code for OAuthCards` to receive the magic code
### Connect to bot using Bot Framework Emulator ### Connect to bot using Bot Framework Emulator
@ -86,25 +74,32 @@ This error may confusingly present itself if either of the following are true:
- Your OAuth AAD tenant is `microsoft.onmicrosoft.com`. - Your OAuth AAD tenant is `microsoft.onmicrosoft.com`.
## Testing Direct Line token generation ## Testing Direct Line token generation
- [Connect to Direct Line](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-directline?view=azure-bot-service-4.0) - [Connect to Direct Line](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-connect-directline?view=azure-bot-service-4.0)
- Add ‘Direct Line Secret’ to `.env` - Add ‘Direct Line Secret’ to `.env`
```bash ```bash
DirectLineSecret=YOUR_DIRECT_LINE_SECRET DirectLineSecret=YOUR_DIRECT_LINE_SECRET
``` ```
- Start the bot - Start the bot
```bash ```bash
npm start npm start
``` ```
- Open [PostMan](https://www.postman.com/) and setup a post request to http://localhost:3978/directline/token - Open [PostMan](https://www.postman.com/) and setup a post request to http://localhost:3978/directline/token
with the following json request body: with the following json request body:
``` ```
{ {
"user": "USER_ID" "user": "USER_ID"
} }
``` ```
Then you can see the Direct Line token generated with YOUR_DIRECT_LINE_SECRET and USER_ID: Then you can see the Direct Line token generated with YOUR_DIRECT_LINE_SECRET and USER_ID:
``` ```
{ {
"conversationId": "XXXXX", "conversationId": "XXXXX",
@ -129,3 +124,5 @@ This error may confusingly present itself if either of the following are true:
- [Channels and Bot Connector Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-concepts?view=azure-bot-service-4.0) - [Channels and Bot Connector Service](https://docs.microsoft.com/en-us/azure/bot-service/bot-concepts?view=azure-bot-service-4.0)
- [Restify](https://www.npmjs.com/package/restify) - [Restify](https://www.npmjs.com/package/restify)
- [dotenv](https://www.npmjs.com/package/dotenv) - [dotenv](https://www.npmjs.com/package/dotenv)
<img src="https://telemetry.sharepointpnp.com/sp-dev-fx-webparts/samples/react-bot-framework-sso/bot" />

8
samples/react-bot-framework-sso/webpart/README.md
View File

@ -8,7 +8,7 @@ An web parts sample that uses the [botframework-webchat module](https://www.npmj
## Used SharePoint Framework Version ## Used SharePoint Framework Version
![1.0](https://img.shields.io/badge/drop-1.0-green.svg) ![SPFx 1.10.0](https://img.shields.io/badge/drop-1.10.0-green.svg)
## Applies to ## Applies to
@ -32,7 +32,7 @@ An web parts sample that uses the [botframework-webchat module](https://www.npmj
- Clone this repository - Clone this repository
- Edit "BotSignInToast.tsx" file to set your AAD scope uri(`scopeUri`) with `api://YOUR_APP_ID` directly like `api://123a45b6-789c-01de-f23g-h4ij5k67a8bc`: - Edit `BotSignInToast.tsx` file to set your AAD scope uri(`scopeUri`) with `api://YOUR_APP_ID` directly like `api://123a45b6-789c-01de-f23g-h4ij5k67a8bc`:
```ts ```ts
return tokenProvider.getToken(scopeUri, true).then((token: string) => { return tokenProvider.getToken(scopeUri, true).then((token: string) => {
@ -65,7 +65,7 @@ An web parts sample that uses the [botframework-webchat module](https://www.npmj
## Deploy ## Deploy
If you want to deploy it follow the steps [here](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn) If you want to deploy it follow [these steps](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/web-parts/get-started/hosting-webpart-from-office-365-cdn)
## Features ## Features
@ -76,3 +76,5 @@ This Web Part illustrates the following concepts on top of the SharePoint Framew
- Office UI Fabric - Office UI Fabric
- React - React
- Demo single sign-on for on behalf of authentication using OAuth - Demo single sign-on for on behalf of authentication using OAuth
<img src="https://telemetry.sharepointpnp.com/sp-dev-fx-webparts/samples/react-bot-framework-sso/webpart" />