Users, Roles and Permissions Management

Each api request to Kill Bill requires authentication. The authentication phase verifies that the user exists in the system and that its credentials are correct. Once the credentials have been validated, the roles associated to the user are then extracted, and then the set of permissions associated to each role are also retrieved. The full list of available permissions can be found here.

The credentials are passed in the request using http basic authentication mechanism and Kill Bill relies on shiro for the backend implementation. Shiro supports multiple backend implementations, and we integrated a few of them including:

For simple deployments where only few static users/roles need to be assigned, the shiro.ini file is the simplest and the best option. By default both Kill Bill (shiro.ini) and Kaui ship with an admin user (and its password password) that has all the permissions. One can immediatly log-in to Kaui using such user, and start configuring tenants as needed.

Changing such user (e.g to use superadmin) or its password to something else than password would require editing shiro.ini configuration file on the Kill Bill side to make sure this initial user can log-in to Kaui (see below).

For production deployments, we recommend not using the default admin (and its default password password).

Note that the authentication/authorization is orthogonal to the tenant access: The set of permissions associated to a given user is the same for all tenants (for which he has the keys). So, a potential superuser with all the permissions and with access to the api_key/api_secret for all tenants would have full control of the entire system. It is common practice to create a cross-tenant admin with the ability to only manage tenants and nothing else, and then have one superadmin per tenant.

This documentation is only specific to users, roles and associated permissions, which are cross tenants configurations.

The shiro.ini file will look like the following:

You can use the property org.killbill.security.shiroResourcePath to specify the location of this file. When using Docker, you can bind mount the file, e.g. specify -v /path/to/shiro.ini:/var/lib/killbill/shiro.ini -e KILLBILL_SECURITY_SHIRO_RESOURCE_PATH=file:/var/lib/killbill/shiro.ini.

Let’s create a new role customer_support:

Let’s create a cs username that will have only one role customer_support:

Let’s assume we want to add more permissions to that user. We could create another role customer_support_manager (same step as before with the desired set of permissions), and then update our user to now have this new role:

Since we did not give access for all the tenant management to our new CS account, let’s have our superadmin create a first tenant:

Assuming our cs user knows about the api_key and api_secret of the tenant, he should now be able to make any api calls against that tenant (with the limitation of his permission set).

So for instance, creating a new account in that tenant would work because his role customer_support includes the permission account:create:

But the following curl to refund a payment would fail because his role customer_support does not include the permission payment:refund:

To integrate Auth0 with Kill Bill:

Configure Kill Bill as such:

The following System Property should also be set:

Notes:

Kill Bill can also support authentication and authorization via JWT (useful to integrate with https://github.com/oauth2-proxy/oauth2-proxy for instance).

By default, the subject is decoded from the JWT and permissions looked up in Auth0. However, if the Add Permissions in the Access Token setting is turned on in Auth0, the JWT will contain the permissions, and Kill Bill will trust these without calling Auth0.

The username in Kill Bill maps to the sub claim by default. You can change this by setting org.killbill.security.auth0.usernameClaim (e.g. you could set it to email for instance, if the email is a claim in the token).

If you are changing this, make sure to update the matching setting in Kaui (-Dkaui.jwt.username_claim System Property or KAUI_USERNAME_CLAIM environment variable).

To configure users allowed to use Kaui, go to /admin_allowed_users:

Fields to populate will depend on which back-end realm is configured.

Kaui needs to be told about the relationship between user and tenants (this mapping is specific to the UI). The idea, is that a super admin would first configure the allowed users for each specific tenant on the KAUI side, in such a way that later on, when a specific user logs in, he only sees the tenants he has access to.

This mapping can be configured by going to each user page (e.g. /admin_allowed_users/1).

As far as tenant configuration goes, it is possible to create tenants directly from Kaui. If you already have created a tenant in Kill Bill using APIs, you can safely re-create it from Kaui, which will discover it on the server side and simply sync it locally.

Kaui has the concept of a super user (root) for critical, cross-tenants, operations. By default, it assumes that the admin user is the super user, but you can change this by setting the system property kaui.root_username (KAUI_ROOT_USERNAME Docker environment variable). The password doesn’t need to be specified as it is stored on the server side (shiro.ini, etc.).