Mindbreeze InSpire Insight Applications in Microsoft SharePoint Online

Introduction

This document describes the integration of Mindbreeze InSpire Insight Applications with Microsoft SharePoint Online.

Both classic sites and modern sites are supported in SharePoint Online, but there are different Mindbreeze InSpire integrations for them. See the official Microsoft documentation for more information on classic and modern sites:

https://support.microsoft.com/en-us/office/sharepoint-classic-and-modern-experiences-5725c103-505d-4a6e-9350-300d3ec7d73f

You can also replace the standard SharePoint Online search with Mindbreeze InSpire search. Please read the chapter "Classic / Modern Sites: Changing the search results page".

Software Prerequisites

The descriptions and instructions contained in this document are based on Microsoft SharePoint Online.

Classic Sites: Embedding an Insight Application

If you want to embed a Mindbreeze InSpire Insight App in a classic site, this chapter provides the necessary configuration steps.

Mindbreeze InSpire Insight Apps are stored as text documents in Microsoft SharePoint and embedded in pages with the “Content Editor” Web Part. Thus, an insight application can be used on multiple pages and still remain easy to maintain.

Saving an Insight Application in a text document

Copy the snippet from the Mindbreeze InSpire Designer into a text document. Click here for more information: Development of Insight Apps.

Uploading the text document

Upload the document to a document library:

Important Note:

The “Application” object in (searchapp.txt) must include the query parameters “K” of Microsoft SharePoint online:

<script>

Mindbreeze.require(["client/application"], function(Application) {    

window.appmb = new Application({ queryURLParameter: "k" });

});

</script>

Copy the address of the document to the clipboard:

Note: The above link is the URL of the document preview page.

Change the URL to the following and copy it:

       https://<your-tenant>.sharepoint.com/sites/<your-site>/Shared%20Documents/searchapp.txt

Note: Replace the brackets with your tenant name and site name. Copy the adjusted URL in a new bowser tab and make sure that it is working.

Creating a new Web Part page

Navigate to “Site Contents” > “Site Pages“:

Create a new “Web Part Page”:

Choose a name and design. Create the page:

Add a new “Content Editor” Web Part:

Note: The “Content Editor” web part is not supported for modern pages (or Sites) according to Microsoft’s official documentation.

To create a classic site, please refer to the following link:

https://docs.microsoft.com/en-us/sharepoint/create-site-collection#create-a-classic-site

Edit the Web Part settings:

Insert the address (adjusted URL) of the text document in “Content Link”, then click “Apply”:

Click “Stop Editing” to finish editing a page: Click

Modern Sites: Embedding an Insight Application

To redirect the search results to a modern site, you will need to add and configure a script editor web part. Please follow these steps:

Step 1: Download and deploy the “App” to your tenant

1. First, download “Mindbreeze Microsoft SharePoint Online Search Extension Plugin.zip” from the Mindbreeze update center.
2. Then, go to your tenant's app catalog: https://<tenant>.sharepoint.com/sites/AppCatalog/AppCatalog

Note: In case the App Catalog is not yet created, please follow this link to create a new one:

https://docs.microsoft.com/en-us/sharepoint/dev/spfx/set-up-your-developer-tenant#create-app-catalog-site

1. From the left menu click “Apps for SharePoint” library. Then, upload the sppkg or drag and drop.
2. 
   
   
3. Click “Deploy” from the popup window.
4. 
   
   
5. Make sure the package is deployed without errors.
6. 
   

Step 2: Install the “App” into your modern site

1. From the site “Home” page, Click “+New” > “App”.
2. 
   
   
3. From “Apps you can add” section, click on “Modern Script Editor web part” to install it.
4. 
5. Note: Please wait for a minute until the app is installed and not grayed out in the “Site Contents” list.
6. You may need to refresh the page if it is still grayed out.
7. 
   

Step 3: Create a new result landing page

1. From the site’s “Home” page, click “+New” then choose “Page”.
2. 
   1. Choose “Blank” and click “Create page”.
   2. 
      
   3. Type a name for your page and click “Publish”.

Step 4: Add and configure the “Modern Script Editor” web part

1. From the top right of the page, click on “Edit”. Then click on the plus icon to add a new web part.

1. Type “script” in the search box and choose “Modern Script Editor”

1. Click on “Edit Markup”. The configuration pane is opened on the right. Click on “Edit HTML code”.

1. Copy and paste the content of your insight app (exported from the Mindbreeze InSpire Designer) into the shown code editor.

Step 5: Important changes needed inside the code snippet

Change the queryURLParameter and export to the window object

At the last <script> tag of the copy/pasted html code snippet, you have to change the following:

Before:

<script>Mindbreeze.require(["client/application"], function(Application) {  

   var application = new Application({

     rootEL: document.getElementById("mb-custom-searchapp-wrapper")

   });

  });

</script>

After:

<script>Mindbreeze.require(["client/application"], function(Application) {  

   window.appmb = new Application({

     rootEL: document.getElementById("mb-custom-searchapp-wrapper"),

      queryURLParameter: "k"

   });

});

</script>

Add a listener to Microsoft search box events:

Additionally, in the same <script> tag, we have to add the following listener to reuse the search box and to redirect the search queries:

Before:

<script>Mindbreeze.require(["client/application"], function(Application) {  

   window.appmb = new Application({

     rootEL: document.getElementById("mb-custom-searchapp-wrapper"),

      queryURLParameter: "k"

   });

  });

</script>

After:

<script>Mindbreeze.require(["client/application"], function(Application) {  

   window.appmb = new Application({

     rootEL: document.getElementById("mb-custom-searchapp-wrapper"),

      queryURLParameter: "k"

   });

  });

  window.O365Shell.Search.OnSubmitSearch(function(query) {

      window.appmb.setUnparsedUserQuery(query);

  });

</script>

Resolve the styling conflicts

To resolve the styling conflicts between SharePoint Online and Mindbreeze, you have to edit the <link> tag exists at the top (first line) of the insight app snippet:

Before:

<link href="https://<your-inspire>/apps/designer/../css/adapted.css" rel="stylesheet">

After:

<link href="https://<your-inspire>/apps/designer/../css/v2/minimal-prefixed-adapted.css" rel="stylesheet">

1. Finally, click on “Save”.
   

1. And then click on “Republish” to make the changes effective.

Step 6: Activate Single Sign-On (optional, recommended)

If you configure Single Sign-On (SSO), the user logged into SharePoint Online is automatically logged into the embedded Mindbreeze InSpire Insight App (via OAuth 2 and JWT). Otherwise, the user must additionally log in again using the authentication method configured on the appliance.

When you configure SSO, authentication works as follows (see also chart below):

1. Login to SharePoint Online (if user is not already logged in):
   1. User logs into SharePoint Online via Microsoft Azure by entering username / password
   2. Azure responds with a JWT (OAuth 2 Access Token)
2. Search via Mindbreeze InSpire Insight App Integration:
   1. A JWT is requested for the Mindbreeze InSpire API app during the first search.
   2. In the search request to the Mindbreeze InSpire Client Service, this JWT is sent along. This is validated at the client service (signature check, claim validation) and the UPN (user principal name) is extracted.
   3. The most relevant documents for the searching user are fetched from the Mindbreeze InSpire index to display them in the results list.

Please perform the following steps to configure SSO:

Azure app registration and permissions

Register a new app in the Azure portal by clicking “+ New registration”: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps

Then assign the name “Mindbreeze InSpire API”. If you want to support accounts coming from another Azure AD directory, select “Accounts in any organizational directory”. Redirect URI is not required and can therefore be left empty. Confirm your entries with the “Register” button.

Next, click “Expose an API” in the menu and then click “+ Add a scope”. If no Application ID has been created for this app yet, you will be prompted to define one (default value: api://<Client ID>). The default value is perfectly sufficient. Confirm your entries with the “Save and continue” button.

Assign the value "Search" as the "Scope name", fill in the other mandatory fields and confirm your selection with “Add scope”.

Add the scope you just created as a permission. To do this, go to "API permissions" and then "Add a permission". Then, in the "My APIs" tab, select the app you created (not shown in the screenshot). Select the permission and confirm your selection by clicking the "Add permissions" button.

Agree to the permission by clicking "Grant admin consent for <Tenant>".

The next step is to add a permission for the “SharePoint Online Client Extensibility Web Application Principle”. To do this, go back to the section “Home” at the top left and click on “App registrations”. Switch to the tab “All applications” and search for “SharePoint”. The SharePoint Online Client Extensibility Web Application Principal should be suggested as an application.

In the SharePoint Online Client Extensibility Web Application Principal, click on the menu item “API permissions”. Click on “Add a permission” to add a permission.

Switch to the tab “My APIs” and select the API you want to use. In this case it is “Mindbreeze InSpire API”.

Select the permission you want to use by ticking the box next to the permission. Then click on “Add permissions”.

Finally, the consent of the admin must be granted. Click on ”Grant admin consent for <Tenant>”.

Confirm this by clicking on “Yes”.

The desired permission for the SharePoint Online Client Extensibility Web Application Principal is now configured and you can use the Mindbreeze InSpire API.

Client Service configuration

In order for JWTs issued by the created AAD App to be validated in Mindbreeze InSpire and for the UPN of the logged-in user to be read, JWT Authentication must be enabled and configured in Mindbreeze InSpire.

To do this, go to Configuration in the Mindbreeze Management Center. Then switch to the Client Services tab and activate Advanced Settings. Then scroll to the JWT Authentication Settings section and configure the settings as follows:

• Enable JWT Authentication: yes
• Optional JWT Authentication: yes (so that e.g. SAML can be used as fallback)
• JWK JSON: open https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys in a browser (replace <tenant-id> with the Azure tenant, not to be confused with the client ID; the tenant ID can be found, for example, in the Azure Portal in the created app under Overview with the name Directory (tenant) ID). Then copy the JSON.
• Configure Required Claims Patterns (+ Add Property)
  • Required Claims Patterns[1]
    • Claim Name: aud
    • Claim Pattern: the application ID of the created app, can be found in the Azure portal in the app under Expose to API, e.g. api://<uuid>
  • Required Claims Patterns[2]
    • Claim Name: iss
    • Claim Pattern: https://sts.windows.net/<tenant-id>/ (replace <tenant-id> with the Azure tenant)
  • Required Claims Patterns[3]
    • Claim Name: scp
    • Claim Pattern: Search
• JWT Identity Claim Name: upn

Adapting the Insight App

The bearer token (JWT) is required for every request sent to the Mindbreeze appliance. Therefore, you need to configure the JavaScript Application object so that it gets the token from the mindbreezeAPITokenProvider and then adds it to the Authorization headers.

This can be done in the following way:

Before:

<script >
  Mindbreeze.require(["client/application"], function(Application) {
    var application = new Application({
      rootEL: document.getElementById("mb-custom-searchapp-wrapper")
    });
  });
</script>

After:

<script>Mindbreeze.require(["client/application"], function(Application) {

        var appliaction = new Application({

            queryURLParameter: "k",

            ajaxOptions: {

                requestHeadersAsync: function(url, callback) {

                    getToken(callback);

               }

            },

            rootEl: document.getElementById("mb-custom-searchapp-wrapper")

        });

    });

    window.O365Shell.Search.OnSubmitSearch( function(query) {

    window.appmb.setUnparsedUserQuery(query);

    });

    function getToken(callback) {

        window.mindbreezeAPITokenProvider.getToken(<APP_ID_URI>)

        .then((accessToken) => {

            callback( null, {'Authorization':  'Bearer ' + accessToken});

        }).catch((error) => {

            callback( 'Unable to get the token');

        });

    }

</script>

NOTE: You have to pass to the function mindbreezeAPITOkenProvider.getToken(…)the APP ID URI of the registered App in Azure AD.

This can be seen in the overview page of the registered app, for e.g.:

Classic / Modern Sites: Change the search results page

In order to use Mindbreeze InSpire search instead of the standard SharePoint Online search on a site (classic site or modern site), additional configuration steps are required.

Click on the gear icon “Site Contents”

Click on “Site Settings”

Go to the search section, then click on the “Search Settings” link.

Then we will get into the “Search Settings” configuration page.

Under “Which search results page should queries be sent to?”:

• Select the radio button “Send queries to a custom results page URL”
• Enter the custom search result page in “Result Page URL”.

Click on the OK button – then wait for a minute to get the changes affected.

Now, search for something in the top search box and hit enter – you should be redirected to the configured results page.

Troubleshooting

Cross-origin resource sharing (CORS)

For security reasons, browsers restrict cross-origin HTTP requests initiated from scripts. In this case, when you open https://{mytenant}.sharepoint.com in a browser, a script from your appliance’s web server is loaded. This script then initiates XHR requests to your appliance, which is not allowed by the CORS policies by default. To allow requests from your SharePoint tenant to your appliance, you need to add your SharePoint tenant in the allowed origins of the CORS settings of your appliance. Configure the following in the Mindbreeze Management Center:

Configuration > Client Services > Advanced Settings

You can find further information in Documentation – Mindbreeze InSpire – CORS Header.

Please note that changing the “Allowed Origins Pattern” option manually will overwrite the default values, see also Documentation – Mindbreeze InSpire – Default values.