Report a problem
Go to KanBo Website
EN

KanBo API for Developers

Table of Contents

Configuring KanBo

If you want to use KanBo API via KanBo.Client.dll you have to first configure your KanBo. 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 - 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.