Configuring KanBo app

If you want to use KanBo API via KanBo.Client.dll you have to first configure your KanBo app. Inside web.config file in section <kanbo><authentication> you have to register X509 certificate that will be used for authentication (you can even generate it by yourself using makecert, see CreateCert.ps1 in Api Sample) .

Download KanBo API samples here:

Download KanBo API samples.

Use the sample for 2.7 version.

As shown above, there are different provider types for certificates:

• “AppSingedLogin” – when using this provider type your service will be seen as user which login you provide and will have exactly same permissions as that user.

On-prem login will look like this: `i:0#.w|domain\user` `domain\user` O365 login will look like this `i:0#.f|membership|[email protected]` `[email protected]`

XML:

<provider id="login" type="AppSignedLogin">{signer}</provider>

• “AppSignedUser” – when using this provider type your service will be seen as user defined by you in code and will have exactly same permissions as that user.

 XML:

<provider id="user" type="AppSignedUser">{signer}</provider>

• “AppSignedService” – when using this provider type your service will be seen as Service and will have permissions defined by KanBo - full access to everything on KanBo.

XML:

<provider id="app" type="AppSignedService" name="Test service">`{signer}</provider> 

The `signer` declares which certificate will be used to validate the signature of given token, possible types are:

- **X509SignerFromFile** - contains a public or private key read from a file by specified path (you can use either .cer or .pfx here, pfx file will need a key).

XML:   

 `<signer type="X509SignerFromFile" file="c:\.ssl\kanbo_id.pfx" key="MyKanBo" />`
`<signer type="X509SignerFromFile" file="c:\.ssl\kanbo_id.cer" />`
  

- **X509SignerFromStore** - contains a public or private key read from a certificate in given certificate store by specified property.

XML:  

`<signer type="X509SignerFromStore" storeName="My" storeLocation="CurrentUser" key="Thumbprint" value="A89369E6705C2B3E446AF5DD5A2A1B559F913152" />`
  
`<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="Thumbprint" value="a89369e6705c2b3e446af5dd5a2a1b559f913152" />`
  
`<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="Thumbprint" value="a8 93 69 e6 70 5c 2b 3e 44 6a f5 dd 5a 2a 1b 55 9f 91 31 52" />`
  
`<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="SerialNumber" value="a89369e6705c2b3e446af5dd5a2a1b559f913152" />` 
 `<signer type="X509SignerFromStore" storeName="My" storeLocation="LocalMachine" key="SubjectName" value="MyFancyApp" />`

Example:

Parameters required for KanBo API object creation:

• kanboUrl – base url of KanBo web (example: "https://kanboapp.developer.local")
• instanceId – id of an KanBo instance (only for KanBo versions lower than 2.7)
• userId – id of a user our service will impersonate (only for userToken). Example: 1
• loginName= login of kanbo user  - required for login type security token. Example: "i:0#.w|developer\\administrator"
• certificatePath – path for the certificate that was registered in KanBo web.config
• certificatePassword – password to certificate mentioned above
• duration- it will define for how long the token is valid (after that it's re-issued)   - it's suggested to use the default value, however if your clocks are synchronized, if not, you may consider using [special tokens that synchronize your client with server](https://bitbucket.org/objectconnect/kanbo-additionaltokens)
  • UserToken – if we want our app to work as signed user (AppSignedUser provider)
  • ServiceToken – if we want our app to work as signed service (AppSignedService provider)
  • LoginToken – if we want our app to work as signed user (AppSignedLogin provider)
  • MobileToken  

Creating API object

To create our KanBo API object first we need to create security token. There are several types of tokens:

 

Here are examples on how to create all token types:

• Generating token for user scope

var loginToken = new LoginToken(KanBoIssuers.Login, loginName, TimeSpan.FromMinutes(10), userCer);

• Generating token for user scope

var userToken = new UserToken(KanBoIssuers.User, userId, TimeSpan.FromMinutes(10), userCer);

• Generating token for service scope

var serviceToken = new ServiceToken(KanBoIssuers.Service, TimeSpan.FromMinutes(10), userCer);

• Generating mobile token

var mobileToken = new MobileTokenSource("administrator", "adminpassword", "https://kanboapp.developer.local");

Next there is need to create requester object for our api.

Example:

var jsonRequester = new JsonApiRequester(mobileToken, kanboUrl, httpClient);

Last step is to create API object with use of a chosen requester:

• Creating API object

var api = new Api(jsonRequester);

• creating uploader object for file upload

var uploader = new Uploader(kanboUrl, jsonRequester);  

Calling methods

All methods in our API can be called in the following manner:

• Get Groups in a Board

var groups = await api.GetData(KanBoGetDataMethods.GroupsInBoard, new { BoardId = 2 });

• Get information about this kanbo api method argumets

var info = await api.GetMethodInfo(KanBoGetDataMethods.Board);    

• Get current user

var usr = await api.GetData(KanBoGetDataMethods.CurrentUser, new { }); 

• Getting board

 var board = await api.GetData(KanBoGetDataMethods.Board, new { Id = 2 });  

• Uploading file to Board and attaching it to card    

 await Upload(145, uploader, api); 

Available methods

There are 2 types of KanBo API methods:

- GetData methods

- Actions methods

You can download a document containing a whole list of KanBo API methods by clicking here.