Report a problem
Go to KanBo Website
EN

KanBo API for Developers

Table of Contents

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  you have to register X509 certificate that will be used for authentication (you can even generate it by yourself using makecert, IIS, or a PowerShell commandlet).

Download KanBo API files.

Download KanBo API methods.

Provider types for certificates

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

  • “Login” – 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|user@exampledomain.onmicrosoft.com` `user@exampledomain.onmicrosoft.com`

  • “User” – 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.
  • “Service” – when using this provider type your service will be seen as Service. KanBo will treat this like a fictional user with name taken from the configuration. This user doesn’t have any permissions until he doesn’t get a “service” role in a token.
  • “Email” – there we use an email taken from the user profile in KanBo.

Here are the roles:

  • “*” – this field can be added to every mapper. It allows tokens to add all possible token roles.
  • “alarm-reminder“, “profiles-sync“, “security-group-sync-source” – roles for services
  • “templates” – role for templates
  • “security-groups-super” – role allowing to change every group
  •  “service” – this role allows everything, despite the permissions
  •  “security:aad“, “security:sp“, “security:{issuer}” – role allowing using authentication tokens of each type which are located in SQL database, you shouldn’t use it for mapping “service”
  • “external-services” – tole allowing to work as an app in SharePoint, gives access to files etc.

Example:

<auth.app issuer="some-issuer">
<signature algo="rs256">
<cert type="x509-file" file="D:\home\site\certs\some-cert.cer" />
</signature>
<mapper type="service" name="some-name" roles="service" />
<mapper type="user" />
<mapper type="email" roles="service" />
<mapper type="login" />
</auth.app>

Signer

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

– **x509-file** – 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).

<auth.app issuer="issuer">
<signature algo="rs256">
<cert type="x509-file" file="D:\home\site\certs\cert.cer" />
</signature>
<mapper type="service" name="some-name" roles="service" />
<mapper type="user" />
<mapper type="email" roles="issuer" />
<mapper type="login" />
</auth.app>

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

<auth.app issuer="issuer">
<signature algo="rs256">
<cert type="x509-store"
store-name="my"
store-location="currentuser"
key="thumbprint"
value="thumprint-value"
valid-only="false"
/>
</signature>
<mapper type="service" name="some-name" roles="service" />
<mapper type="user" />
<mapper type="email" roles="issuer" />
<mapper type="login" />
</auth.app>

Parameters required for KanBo authorizatio

var kanboUrl = "https://my-new-kanbo.azurewebsites.net"; //url of kanbo app - required for all security tokens
var userId = 1; //user id - usually same as myBoard id
var loginName = "i:0#.f|membership|my-user@mynewkanbo.com";// i:0#.w|developer\\administrator"; //login of kanbo user - required for login type security token

/* Getting same certificate that is registered in KanBo web.config */

var cert = new X509Certificate2(_userCertPath, _userCertPassword); //(path, password) to generated certificate

Creating API object

Generating wanted token service and/or user type
var userToken = new JwtTokenSource(new LoginToken.Transformer(loginName,"SP").WithRoles("external-services"), TimeSpan.FromMinutes(10),
Generating token for login scope
new KanBo.Jwt.Serializers.RS256AlgorithmSerializer(cert, "some-cert"));
Generating service
var serviceToken = new ServiceToken("some-cert", TimeSpan.FromMinutes(10), cert);
Generating token for user scope
var idToken = new JwtTokenSource(new UserToken.Transformer(userId).WithRoles("external-services"), TimeSpan.FromMinutes(10),
new KanBo.Jwt.Serializers.RS256AlgorithmSerializer(cert, "some-cert"));
Create http client and set credentials if required
var hc = new HttpClient();
Creating requester
var jsonRequester = new JsonApiRequester(serviceToken, kanboUrl, hc);
Creating Api object
var api = new Api(jsonRequester);

Calling methods

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

Get default home layout
var layout = await api.GetData(KanBoGetDataMethods.List, new { Id = 3222});
var jLayout = JObject.Parse(layout);
Add new board
var newBoard = await api.Action(KanBoActionMethods.AddBoard, new
{
Name = "TestApi2",
Color = 1,
});
var jNewBoard = JObject.Parse(newBoard);
Get board permission groups
var boardGroups = await api.GetData(KanBoGetDataMethods.GroupsInBoard, new { BoardId = (int)jNewBoard["Id"] });
var jBoardGroups = JObject.Parse(boardGroups);
Find user
var foundUser = await api.GetData(KanBoGetDataMethods.Users, new { Keyword = "my-user" });
var jFoundUser = JObject.Parse(foundUser);

Available methods

There are 2 types of KanBo API methods:

  • GetData methods
  • Actions methods

Was this article helpful?

Please, contact us if you have any additional questions.