SPFx MSAL Bot Extension
When to use this pattern?
This sample is suitable when you want to create a bot using the web chat channel only, for instance to integrate a bot assistant in your SharePoint intranet portal. However, if you need to access protected APIs in your bot but also want mutliple channels (like, Microsoft Teams, Skype, etc.), you might use the OAuth2 authorization grant flow implementation for Node.js instead. You can refer to this sample https://github.com/FranckyC/SharePointBot to get started.
Used SharePoint Framework Version
|react-bot-msal||Franck Cornu (aequos) - Twitter @FranckCornu|
|1.0||January 8, 2018||Initial release|
|1.1||August 4th, 2018||Updated bot logic + bug fixes|
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
- Setup the environment as described below
- In the command line run:
- Upload the generated package to the SharePoint app catalog
- Install the PnP - Graph Bot app in your site
- In the command line run:
gulp serve --nobrowser
- Play with the bot!
1- Setup the Azure AD application
To access the Microsoft Graph API, you will need to register a new app in the Azure Active Directory behind your Office 365 tenant using the new registration portal for Azure AD v2:
- Go to https://apps.dev.microsoft.com. Log in with an administrator account of the tenant you want to give access to and create a new application.
- Add a new "Web" platform and make sure the option "Allow Implicit Flow" is checked. In the "Redirect URLs" option, specify the URL of the root site of the site collection you want to deploy this sample. You can add multiple redirect URLs if you want to use your bot on multiple SharePoint sites.
- Keep the permissions as is. They will determined at the runtime by the application. Refer to the GraphBot.tsx file to modifiy them according to your Microsoft graph queries.
2- Create the LUIS Model
Go to the LUIS portal https://www.luis.ai.
Import a new application by reusing the ./bot/luis_sample_model.json file. It will import intents and utterances automatically for this specific example. In the solution, intents are matched to specific graph queries. This is a very basic example so you can use your own intent/query combinations based on your requirements (use the Microsoft Graph Explorer to see samples):
LUIS Intent Graph Query GetMyGroups https://graph.microsoft.com/v1.0/me/memberOf GetMyManager https://graph.microsoft.com/v1.0/me/manager <your_intent> <your_graph_query>
Train and publish the application to the production slot. You can use the LUIS starter key to get started.
3- Create the bot in Azure
- In an Azure tenant (can be different from your Office 365 account), create a new "Web App Bot" (you can use a "Functions Bot" as well with few refactoring steps depending your requirements).
- In the bot template, select a basic Node.js bot.
- In the bot "Build" setting, open the online code editor:
- Replace the app.js code by the one of this sample contained in the app.js file.
- Same thing for the package.json file.
- Open the console and type the following command line:
In the application settings, add the following key/value pairs for the LUIS application:
- LuisAppId: you can get this value directly in the URL on your LUIS application
- LuisAPIKey: you can get this value in the publish settings.
In the "Channels" options, add a new "Direct Line" channel and generate a new secret key.
4- Store your environement settings in the tenant property bag
The SharePoint extension does not store any settings directly in the code. They are fetched from the tenant property bag using the REST APIs. Once read, they are stored in the browser local storage to improve performances.
In the solution, modifiy the Set-TenantProperties.ps1 PowerShell script to add your own values as follow:
Setting Value Client Id The Azure Active Directory application id retrievable from the https://apps.dev.microsoft.com portal. See prerequisites. Bot Id The bot application identifier. You can get this value in the "Settings" option from the bot Azure resource (the "Microsoft App ID" value). Direct Line Secret The bot Direct Line channel secret. You can get this value in the "Channels" option from the bot Azure resource. Tenant Id The Office 365 tenant id. You can get this value in the Azure AD portal.
Execute the script targeting your Office 365 tenant. Make sure the latest PnP Cmdlets are installed on your machine.
Debug your bot locally
Debug the SPFx extension
To debug the SPFx code, you will need to package (
gulp bundle and
gulp package-solution) and deploy the application in your Office 365 environment first and then host your code locally (by running
gulp serve --nobrowser).
You could also debug using the SharePoint hosted workbench but, in this scenario, you would update the redirect URL of your Azure AD App pointing to the workbench.aspx page in your SharePoin site.
For convenience, you can also use the SPFx debug configuration for Visual Studio code.
Debug the bot logic
To debug the bot logic, you will need to use the ngrok third party tool to create a gateway pointing to your local machine.
In a Node.js console, run
ngrok http 3978and copy the generated URL (the https one)
Start your Node.js server (i.e your bot). In Visual Studio Code, simply press F5.
In the bot settings from your Azure portal, change the messaging endpoint by the generated ngrok URL:
Send messages through the SPFx extension. Messages will now be redirected to your local machine.
Important: in this mode, your bot won't be able to send messages back to your SPFx extension so won't see them.
This Web Part illustrates the following concepts on top of the SharePoint Framework and Bot Framework:
- SharePoint Framework concepts
- Use the new MicroSoft Authentication Library library (instead of ADAL) to access Azure AD protected APIs (ex: Microsoft Graph API) using the OAuth2 implicit grant flow.
- Store and read settings in the tenant property bag using REST
- Integrate and configure the Bot Framework Web Chat React control with the Direct Line channel.
- Retrieve the bot conversation history for the current user
- Bot Framework concepts