Getting started
Running Kaui locally
You can run Kaui locally by using the test/dummy app provided:
> bundle install
> cd test/dummy
> export RAILS_ENV=development
> bundle install
> rake kaui:install:migrations
> rake db:migrate
> rails server
Mounting Kaui into your own Rails app
The Kaui gem comes with a kaui
script to mount it in your existing Rails app.
Kaui expects the container app to define the current_user method, which returns the name of the logged-in user. This is used by Kill Bill for auditing purposes.
Finally, a Kill Bill server needs to be running for Kaui to fetch its information (see the Configuration section below). The default login credentials are admin/password. Users, Credentials, Roles and Permissions are passed through to Kill Bill. It uses Basic Auth by default, but the backend is pluggable (LDAP, ActiveDirectory, etc.).
Configuration
Specify your Kill Bill server url, api key and secret in config/initializers/killbill_client.rb
:
KillBillClient.url = 'http://127.0.0.1:8080/'
KillBillClient.api_key = 'bob'
KillBillClient.api_secret = 'lazar'
Sharing a Kaui instance across multiple tenants is not supported yet (you need to spawn one instance per tenant).
Running tests
Go into 'test/dummy':
cd test/dummy/
Run migrations:
export RAILS_ENV=test rake kaui:install:migrations rake db:migrate
Run the tests: (Move back to top level)
cd ../.. rake test
Note: functional and integration tests require an instance of Kill Bill to test against.
Development
Working with the kaui script
In order to generate the Rubygems-friendly kaui
script, you need to build the gem
and install it locally.
First, build the gem in the pkg
directory:
rake build
Then, install and run it from a local directory:
mkdir foo
gem install pkg/kaui-*.gem -i foo
GEM_PATH=$PWD/foo:$GEM_PATH ./foo/bin/kaui /path/to/rails/app --path=$PWD --skip-bundle
Alternatively, you can run the kaui
script under bin
by setting your loadpath correctly:
ruby -Ilib bin/kaui /path/to/rails/app --path=$PWD --skip-bundle
Multi-Tenancy
KAUI has been enhanced to support multi-tenancy. In order to benefit from that mode, remove the properties KillBillClient.api_key
and KillBillClient.api_secret
from the config/initializers directory.
Admin User Roles
In multi-tenancy mode, there are two kinds of users:
- The multi-tenant admin user, which has the rights to configure the tenant information (creation of tenant, add allowed users for specific tenant, upload catalog, ...)
- The per-tenant admin user, which operates just a given tenant
Those roles and permissions are defined the same way other permissions are defined: The Shiro configuration (static config file, LDAP) in Kill Bill, will determine for each user its associated role, and the roles will have a set of available permissions. The new permissions have been created:
- TENANT_CAN_VIEW
- TENANT_CAN_CREATE
- OVERDUE_CAN_UPLOAD
- CATALOG_CAN_UPLOAD
The enforcement in KAUI is based on the CanCan gem.
Multi-tenancy screens
KAUI has been enriched with new models and new screens to manage the multi-tenancy, and those are available for the multi-tenant admin user:
- The
kaui_tenants
table will list the available tenants (from KAUI point of view); note that this is redundant with the Kill Billtenants
table, and the reason is that theapi_secret
needs to be maintained in KAUI as well, so listing the existing tenants from Kill Bill would not work since that key is encrypted and cannot be returned. A new screen mounted on/admin_tenants
allows to configure new tenants. The view allows to create the new tenant in Kill Bill or simply updates the local KAUI config if the tenant already exists. - The
kaui_allowed_users
table along with the join tablekaui_allowed_user_tenants
will list all the users in the system that can access specific tenants. The join table is required since a given user could access multiple tenants (e.g multi-tenant admin user), and at the same time many users could access the same tenant. A new screen mounted on/admin_allowed_users
allows to configure the set of allowed users associated to specific tenants.