KanBo Installation Guide (On-Premises)

Table of Contents

Overview

This is the installation guide for KanBo on SharePoint 2019 on-premises.

Prerequisites:

To create a new site collection from the team site template inside your SharePoint farm, you should choose the SharePoint web application where the most content (like documents) is stored. This will allow KanBo to reuse most of your existing information without duplicating content.

1. Registering a new app identifier in SharePoint

Create a new app registration in SharePoint by going to:
Your-SP-URL/_layouts/15/appregnew.aspx

  1. Next to the Cilent ID field, select Generate.
  2. Next to the Client Secret field, select Generate.
  3. Enter the title: KanBo.
  4. In App Domain field, enter the domain of your KanBo app (no https:// etc.).
  5. In Redirect URI field, enter the URL of your KanBo app.
  6. Select Create.

Please save the above confirmation message for later use.

2. Registering the self-signed certificate in SharePoint

A self-signed certificate is required to authenticate communication between KanBo and SharePoint. To create and register the certificate 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

Note that this command will create a .cer certificate in the current Powershell console path. Make sure to navigate out of System32 before running the command.

Running this command should produce the following output:

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

  • The thumbprint of the “kanbo-cert” certificate,
  • The ID of this certificate, which is found under the “DisplayName” variable.

These will be used in the next step.

3. Installing KanBo

  1. Unzip the KanBo files to the folder from which you want to host the website.
  2. Open appsettings.json because there is code that needs to be modified.
  3. Go to the connection string 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"
},
  1. Change the following values:
  • “IP” to the IP address of your SQL Server,
  • “NAME” to an SQL Server login,
  • “PASSWORD” to the password used for the login,
  • “DB-NAME” to the name you want your database to have (we recommend “KanBo”).
  1. Go to 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"
     		},
  1. Change the following values:
  • “CLIENT-ID” to the client ID of the SharePoint app registration,
  • “ISSUER-ID” to the ID shown in the certificate creation output,
  • “SP-URL” to the URL of your SharePoint site,
  • “THUMBPRINT” to the thumbprint of the created and registered certificate,
  • TEMPLATE-PATH to the path of the folder that will hold the temporary template files.

There are two important things to note here. First, the folder specified in the TEMPLATE-PATH should not be in the root folder of the KanBo app; it should be created outside of the root folder. Second, if you are familiar with SharePoint, you can create a SharePoint site to host your KanBo app. Then, use the URL of this site (http://contoso.com/sites/kanbo, for example) as the SP URL.

4. Setting up a website in IIS

  1. Open IIS.
  2. Go to Sites, and than select Add Website….
  1. Name the site KanBo and enter the rest of the information according to how your domain should be set up.
  2. After creating the site, double-click its name.
  3. On the ISS section, select Authentication.
  1. Make sure that both “Anonymous Authentication” and “Windows Authentication” are enabled.
  1. Go to Application Pools and select the application pool of your KanBo app.
  2. From the Actions panel, select Advanced Settings.
  1. In the dropdown menu, change Load User Profile to true.
  1. From the three-dot menu, select Identity.
  2. Change the identity to Custom account.
  1. Use the server administrator account’s login and password.
  1. All open windows must be saved by selecting OK.

5. Setting permissions on the KanBo installation directory

The KanBo app needs write access to the folder it hosts itself from. 

  1. Right-click the KanBo folder and select Properties.
  2. Select Edit.
  1. Select Add… to add a new permission.
  1. Select Locations… to change the location of your entire server.
  1. Enter “IIS AppPool\KanBo” as the object name.

Note that IIS AppPool\KanBo is case- and space-sensitive. Please write it out with all the spaces and correct case.

  1. After selecting Check Names, permissions will be granted to the application pool of your KanBo app on this folder.
  2. Grant all the permissions to the KanBo Application Pool and save the app.

6. Distributing the app in SharePoint

  1. Go to https://YOURKANBOURL/plugins/sharepoint-appfile/kanbo.app for the “kanbo.app” file.
  2. A kanbo.app file will download automatically.
  3. Open your SharePoint site.
  4. Go to your App Catalog site. In our case, it’s: contoso.com/sites/kanboapp
  5. Select Distribute apps for SharePoint.
  1. Upload the kanbo.app file.

7. Adding the app to SharePoint

After distributing the kanbo.app to SharePoint, you have to add it to your SharePoint site.

  1. Open your SharePoint Page, where you want to add KanBo (we use: portal.contoso.com).
  2. In the top right, select the gear icon and then select Add an app.
  1. You should see the KanBo app among the available applications, but it cannot be added at the moment. Select Find out why.
KanBo-Sharepoint-On-premise-Installation-21
  1. Select Request approval.
  1. In the pop-up window, select Request.
  1. The app request is pending approval.
  1. Open your app catalog, and on the left side, select App Request.
  2. Select KanBo.
  1. Select Approve.
  1. Go back to the app and select the Add an app menu.
  2. Select KanBo.
  1. Select Trust It.

8. Running KanBo Setup

Now run the KanBo Setup by opening the page: https://kanbo.kdomain12.local/setup 

→ Follow the setup instructions.

9. Configuring KanBo Search

Install and configure Elasticsearch. Then, establish a connection to it in KanBo.

10. Configuring KanBo Resource Management

A separate package is required to configure the Resource Management module for KanBo.

  1. Set up the Resource Management site in IIS the same way you did with the KanBo app.
  2. Find this section in the KanBo app’s settings.json file:
	/*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"
		 }
          ]
        ]
      },
  1. Replace all instances of “THUMBPRINT” with the certificate thumbprint that you used in the “auth.sharepoint” section.
  2. Replace “RM-URL” with the URL of your Resource Management app.
  3. After saving, restart the App Pool of the KanBo app.
  4. Go to YOURKANBOURL/auth/rmkanbo/newclient

You will be presented with a page that looks like this:

There are two parts. The “Client config” goes into the appsettings.json file of the KanBo app. The “OAuth2 config” goes into the appsettings.json file of the Resource Management app.

On the KanBo side, you can find this comment in the appsettings.json file.

/* client will go here */
  1. Replace it with a comma, and then paste the Client config.
  1. The “client” variable needs to be renamed “id.”
  2. The “url” value needs to be replaced with the URL of your Resource Management app.
  3. The “name” value needs to contain something identifiable (such as “My KanBo Resource Management”).
  4. As for the Resource Management appsettings.json file, you need to copy the connection string from your KanBo appsettings.json file to the Resource Management appsettings.json file.
  5. Scroll to the bottom of Resource Management’s appsettings.json and find the empty “ClientId” and “ClientSecret” variables.
  6. Paste the “OAuth2 config” client ID and client secret inside their quotation marks. Also, change the URLs to the URL of your KanBo app.
  7. Once all the appsettings.json files have been configured and saved, restart both apps, starting with Resource Management.
  8. Once both apps are up and running, go to the Setup page of your KanBo account.
  9. Go to Resource Management tab.
  1. You should see four checks passing and one failing: the Schema Validation check. If you experience different results, please check that you copied everything correctly.
  2. Next, select Initialize RM content database.

You have successfully connected the KanBo app to the Resource Management app if all the checks show as “PASSED.”

Was this article helpful?

Please, contact us if you have any additional questions.