KanBo Installation for On-Premise SharePoint 2019

Table of Contents

This post is also available in: Deutsch

1. Prerequisites

Important:

You can see the prerequisites which need to be fulfilled for the KanBo On-Premise installation in the following article.
Please request the latest KanBo Installation Files at support@kanboapp.com

You should choose the SharePoint Web Application where the most content (like Documents) is stored within your SharePoint Farm to create a new Site Collection from the Team Site Template inside of it. That way KanBo will be able to reuse most of your existing information without duplicating content.

2. Register a new App Identifier in SharePoint

Create a new app registration in Sharepoint by heading to Your-SP-URL/_layouts/15/appregnew.aspx

Click on Generate Client id
Click on Generate Client secret
Title – KanBo
App Domain – domain of Your KanBo app (no https:// etc.)
Redirect URI – the URL of Your KanBo App
Click on “Create”

Please make sure You save the above confirmation message for later usage.

3. Register the (Self-Signed) Certificate in SharePoint

A self signed certificate is required for authenticating the KanBo-Sharepoint communication. To create the certificate and register it in Sharepoint, run the following command in Powershell as an administrator

$cert = New-SelfSignedCertificate -DnsName "kanbo-cert" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(20)
[System.Convert]::ToBase64String($cert.Export("cert")) > test.cer
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2(Resolve-Path test.cer)
$realm = Get-SPAuthenticationRealm
New-SPTrustedSecurityTokenIssuer -cert $cert -name kanbo-hightrust -RegisteredIssuerName "kanbo-hightrust@$realm" -IsTrustBroker
New-SPTrustedRootAuthority -Name 'kanbo-cert' -Certificate $cert

It's important to note that this command will create a .cer certificate in the path You are on in the Powershell console. Please make sure to navigate out of system32 first before running the command.

Running this command should give You this output:

There are important outputs here that need to be saved. Those are:

The thumprint of the “kanbo-cert” certificate
The ID of this certificate (present under the “DisplayName” variable)

They will be used in the next step

4. Install KanBo

Unzip the KanBo files to the folder which You want to host the website from. After doing so, open appsettings.json, as there will be code to modify. First, let’s change the connection string that is present at the top:

"ConnectionStrings": {
"KanBo": "Data Source=IP,1433;Database=DB-NAME;User ID=USERNAME;Password=PASSWORD;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;TrustServerCertificate=true;MultipleActiveResultSets=True"
},

You need to:

Change “IP” to the IP address of Your SQL Server
Change “NAME” to an SQL Server login
Change “PASSWORD” to the password of the used Login
Change “DB-NAME” to the name You wish for Your database to have (“KanBo” is recommended)

After that, let’s start with modifying the “plugins” section:

	"load-packages",
		{
		 "type": "auth-by-login",
		 "issuer": "sp"
		},
		{
        	 "type": "package",
        	 "name": "kanbo"
      		},
		"identity-source",
		{
		 "type": "auth.sharepoint",
		 "client-id": "CLIENT-ID",
		 "issuer-id": "ISSUER-ID",
		 "sp-host-url": "SP-URL",
		 "signer": {
		  "key": "thumbprint",
		  "store-location": "localmachine",
		  "store-name": "my",
		  "type": "x509-store",
		  "valid-only": false,
		  "value": "THUMBPRINT"
		 }
		},
		"sp-web",
		{
		 "type": "security-group-sync-target.sharepoint",
		 "attach-on-group-create": true
		},
		"security-group-sync-target.sharepoint-external-site-collection",
		{
		 "type": "docsource.sharepoint",
		 "event-listener": {
		  "type": "soap11"
		 }
		},
		"doc-template-source.sharepoint",
		"add-sharepoint-login-to-public-board",
		{
		 "type": "users-source.sharepoint",
		 "sid-source": {
		  "type": "ad"
		 }
		},
		"setup-permissions.sharepoint",
		"website-search.sharepoint",
		{
		 "type": "sp-app",
		 "url": "sharepoint-appfile"
		},
		"require-user-account",
		"sp-subsite",
		"board-installer.sharepoint",
		{
        	 "type": "template-files",
        	 "path": "TEMPLATE-PATH"
     		},

List of values to be changed in this section:

CLIENT-ID – client-id of the Sharepoint App Registration
ISSUER-ID – needs to be changed to the ID that’s shown in the output of certificate creation
SP-URL – The URL of Your Sharepoint Site
THUMBPRINT – the thumbprint of the created and registered certificate
TEMPLATE-PATH – a path to a folder that will hold temporary template files

Two important things need to be noted here. First, the folder specified in the TEMPLATE-PATH should not be in the root folder of the KanBo app and should be created outside of it. Secondly, if You are proficient with Sharepoint, You can create a Sharepoint site to host Your KanBo App from and then using the URL of this site (http://contoso.com/sites/kanbo for example) as SP-URL.

5. Set up a website in IIS

Begin by opening IIS, going to Sites and clicking on “Add website…”

Name the site “KanBo” and fill out the rest of the information in accordance with how Your domain should be set up.

After You’ve created the site, double click it’s name.

Head to Authentication

Make sure both the “Anonymous Authentication” and “Windows Authentication” are enabled.

Next, head to Application Pools and find the Application Pool of Your KanBo app

Select it and click on “Advanced Settings”

Change “Load User Profile” to true from the dropdown menu, then click on the three dot menu for “Identity”

Change the identity to “Custom account” then use the login and password of the server administrator account.

Press OK to all the opened windows to save

6. Set Permissions on the KanBo Installation directory

The KanBo app needs write access to the folder it hosts itself from. To do that, right click the KanBo folder and go into properties

Click on “Edit”

Now we will be adding a new permission

Click on “Locations” and change the location to Your whole server

Type “IIS AppPool\KanBo” as Your object name. After clicking “Check Names”, the application pool of Your KanBo app will be eligible to have permissions granted on this folder.

IIS AppPool\KanBo is both case and space sensitive. Please write it out with all the spaces and with correct letter cases

Grant the KanBo Application Pool all the permissions and save the app.

7. Distribute the app in SharePoint

First, You will need to get the “kanbo.app” file. Head to https://YOURKANBOURL/plugins/sharepoint-appfile/kanbo.app

This will download a kanbo.app file automatically

Next, distribute kanbo.app on Your Sharepoint site. Head to Your App Catalog site (in our case it’s contoso.com/sites/kanboapp)

Click on “Distribute app for Sharepoint” and upload the kanbo.app file

8. Add the app to SharePoint

After distributing the kanbo.app to Sharepoint You have to add it to Your Sharepoint site. Open your SharePoint Page, where you want to add KanBo (we use: portal.contoso.com) and click on the gear icon in the top right and select “Add an app”

Among the available applications You should see the KanBo app, which can not be added at the moment.

Click on Find out why.

Click on Request approval.

In the pop-up window click the Request button.

The App request is now pending and needs to be approved

Open your app catalog click “App Request” on the left side

Click on “KanBo” and approve the app

The KanBo App is now approved.

Head back to the app to the “Add an app” menu, click on the “KanBo” app and click “trust it”

9. Run KanBo Setup

Now we can run the KanBo Setup by opening the page: https://kanbo.kdomain12.local/setup and follow the steps from the setup instructions.

10. Configure KanBo Search

Install and configure Elastic Search, after which You will be establishing connection to it in KanBo.
Installation and configuration manual on Windows:
https://help.kanboapp.com/en/devops/installing-and-configuring-elastic-search-on-windows/
Installation and configuration manual on Linu (Debian):
https://help.kanboapp.com/en/devops/installing-and-configuring-elastic-search-on-debian/

11. Configuring KanBo Resource Management

To configure the Resource Management module for KanBo, a separate package for Resource Management is required.

First, You need to set up the Resource Management site in IIS in the same fashion as the KanBo app. After doing so, find this section in the KanBo appsettings.json:

	/*RESOURCE MANAGEMENT*/
   
    {
         "type": "auth.oauth",
         "issuer": "rmkanbo",
         "children": [
           [
             "cert",
             {
		  "key": "thumbprint",
		  "store-location": "localmachine",
		  "store-name": "my",
		  "type": "x509-store",
		  "valid-only": false,
		  "value": "THUMBPRINT"
		 }
           ]/* client will go here */
         ]
       },
	  {
        "type": "resource-mgmt",
        "issuer": "rmkanbo",
        "rm-uri": "https://RM-URL/api",
        "children": [
          [
            "cert",
            {
		  "key": "thumbprint",
		  "store-location": "localmachine",
		  "store-name": "my",
		  "type": "x509-store",
		  "valid-only": false,
		  "value": "THUMBPRINT"
		 }
          ]
        ]
      },

Replace every “THUMBPRINT” with the same certificate thumbprint You used in the “auth.sharepoint” section. Replace “RM-URL” with the URL of Your Resource Management app.

After saving, restart the App Pool of the KanBo app, then go to YOURKANBOURL/auth/rmkanbo/newclient

You will be presented with a page that looks like this

There are two parts here. The “Client config” part that goes into the appsettings.json of the KanBo App, and the “OAuth2 config” which goes into the appsettings.json of the Resource Management app.

For the KanBo side, You can find this comment in the appsettings.json:

/* client will go here */

Replace it with a comma, and then paste the Client config.

Couple of things to note, the “client” variable needs to have it’s name changed to “id”, the “url” value has to have the url of Your Resource Management app, and the “name” value needs to have something indentifiable written in it (like “My KanBo Resource Management”)

As for Resource Management’s appsettings.json, You need to copy the connection string from Your KanBo appsettings.json to the Resource Management appsettings.json. After doing so scroll to the bottom of the Resource Management’s appsettings.json and find the empty “ClientId” and “ClientSecret” variables. Paste the “OAuth2 config” Client Id and Client Secret inside of their quotation marks. Also make sure to change the URLS to the URL of Your KanBo app.

After all the appsettings.json files have been configured and saved, restart both apps, starting with the resource management app first

After both apps are up and running, go to the setup page of Your KanBo. You will find a new “Resource Management” tab there

You should be presented with 4 checks passing and one check failing, being the Schema Validation check. If You experience any other results, please check if You pasted everything correctly

Next, click on “Initialize RM content database”.

If every check shows as “PASSED”, You have now succesfuly connected the KanBo App to the Resource Management App!

Was this article helpful?

Please, contact us if you have any additional questions.