Overview
Aviate access control decides what each person, or each application, can do through the Aviate APIs and the Aviate UI. It is built on the Kill Bill security model rather than next to it:
-
A role is a regular Kill Bill role, created with the Kill Bill security APIs.
-
A role holds Kill Bill permissions (
account:create,entitlement:cancel, …) and Aviate permissions (aviate_quote:submit,aviate_revenue:close, …). There is a single place to define what a role can do. -
Each Aviate user has one role per organization. The role travels in the user’s Aviate token, and Kill Bill and Aviate both enforce it.
Roles are assigned to people from the Aviate UI (see Aviate Members). When your organization signs in with its own identity provider, new users get a default role (see Aviate Single Sign-On).
Key Concepts
Who Calls Aviate
| Caller | Authentication | Permissions come from |
|---|---|---|
The owner of the Aviate subscription |
Aviate token ( |
The |
A member of the organization |
Aviate token ( |
The role the owner gave the member ( |
A Kill Bill user, for example an application calling Aviate on behalf of your customers |
Kill Bill credentials ( |
The Kill Bill roles of that user, exactly as for the Kill Bill APIs |
The role of an Aviate user is carried in the aviate_role claim of the ID token. Kill Bill reads it through its Cognito realm, and looks up the permissions of that role in its own role definitions. Kill Bill users authenticated with Basic are unchanged: their roles come from the Kill Bill realms you already use (database users or shiro.ini).
How a Request Is Checked
Every Aviate endpoint declares the permissions it requires:
-
The Aviate permission for the action, for example
aviate_quote:submit. -
The Kill Bill permissions for the Kill Bill operations the action performs. Submitting a quote creates, changes and cancels subscriptions, so it also requires
entitlement:create,entitlement:change_planandentitlement:cancel.
The caller needs all of them. A role can therefore never do through Aviate what it could not do with the Kill Bill APIs directly. Aviate then calls Kill Bill as the caller, so Kill Bill applies its own checks as well.
A few more rules:
-
Default deny. A permission that is not granted is refused, and an endpoint that does not declare its permissions is refused for everyone.
-
Reads. Kill Bill has no read permissions: any authenticated user can read Kill Bill data. Reads of Aviate data are controlled by the
<area>:viewpermissions (aviate_quote:view,aviate_revenue:view, …). -
Background work. Some actions run later, in the background: scheduled contract changes, future cancellations, wallet top-offs, workflow steps. They are authorized when they are requested, and then run with the plugin’s own credentials.
Permission Names
Aviate permissions follow the Kill Bill <group>:<action> convention. Each group starts with aviate_, for example aviate_contract:activate. The full list is in Permission Reference.
Kill Bill wildcards apply on the action: aviate_quote:* grants every quote action. A wildcard on the group name (aviate_*) does not work: list each group instead. : grants everything, Kill Bill and Aviate.
Built-In Roles
Two role names have a fixed meaning in Aviate. They must exist on every Kill Bill deployment your organization uses.
| Role | Meaning |
|---|---|
|
The owner of the Aviate subscription always has this role, whether or not the organization uses single sign-on. It cannot be given to members. Define it with |
|
The default role of new members: every |
When access control is enabled (mode log or enforce, see Enabling Access Control), the Aviate plugin creates both roles on startup if they don’t exist on that Kill Bill. It never changes a role that already exists: you can adjust aviate_read to your needs.
For reference, this is how to create aviate_read yourself, with a Kill Bill user allowed to manage roles (for example the Kill Bill admin):
curl -v -X POST \
-u admin:password \
-H "Content-Type: application/json" \
-H "X-Killbill-CreatedBy: admin" \
-d '{
"role": "aviate_read",
"permissions": [
"aviate_ba:view", "aviate_quote:view", "aviate_quote_template:view",
"aviate_related_party:view", "aviate_order:view", "aviate_contract:view",
"aviate_catalog:view", "aviate_rating:view", "aviate_metering:view",
"aviate_coupon:view", "aviate_policy:view", "aviate_approval:view",
"aviate_intent:view", "aviate_workflow:view", "aviate_wallet:view",
"aviate_revenue:view", "aviate_bi:view", "aviate_health:view",
"invoice:dry_run"
]
}' \
http://127.0.0.1:8080/1.0/kb/security/roles
|
Note
|
If a member’s role is not defined on a deployment, the member gets no permissions there: they can still read Kill Bill data, but cannot read Aviate data or change anything. |
Your Own Roles
You decide which roles your organization needs. Each member has one role, and Kill Bill roles do not inherit from each other: a role that should also read everything repeats the aviate_read permissions.
The following roles are an example of how an organization could split the work. Aviate does not create them. Each person role below is aviate_read plus the listed permissions.
| Role | Aviate permissions | Kill Bill permissions |
|---|---|---|
|
|
|
|
Same as |
Same as |
|
|
|
|
|
|
|
|
|
|
|
|
An application that calls Kill Bill and Aviate on behalf of your customers (a signup flow, a storefront) is not a person: give it its own Kill Bill user, with Basic authentication and only the permissions it calls. For example:
curl -v -X POST \
-u admin:password \
-H "Content-Type: application/json" \
-H "X-Killbill-CreatedBy: admin" \
-d '{
"role": "storefront",
"permissions": [
"aviate_catalog:view", "aviate_ba:view", "aviate_ba:create",
"aviate_metering:view", "aviate_metering:record",
"account:create", "account:update", "account:add_emails",
"payment_method:*", "payment:trigger",
"entitlement:create", "entitlement:change_plan", "entitlement:pause_resume", "entitlement:cancel",
"usage:record", "invoice:dry_run"
]
}' \
http://127.0.0.1:8080/1.0/kb/security/roles
Permissions are tenant-wide: such a user can act on any account of the tenant. Making sure each of your customers only reaches their own account is the application’s job.
|
Note
|
Kill Bill permissions cannot express limits on amounts: a role with invoice:credit can credit any amount.
|
Enabling Access Control
Aviate access control is turned off by default: existing installations keep working unchanged. Enabling it takes three steps.
Step 1: Accept Aviate Tokens in Kill Bill
Kill Bill must validate Aviate ID tokens and read the role they carry. Enable the Cognito realm with the following Kill Bill properties:
killbill.server.cognito=true
org.killbill.security.cognito.issuer=<Aviate token issuer>
org.killbill.security.cognito.audiences=<Aviate client ids>
org.killbill.security.cognito.roleClaim=aviate_role
Contact the Aviate support team ([email protected]) for the issuer and audience values. Kill Bill deployments hosted by Aviate are already configured.
Refer to the Kill Bill Configuration Guide to know more about setting configuration properties.
Step 2: Define the Roles
On every Kill Bill deployment your organization uses, define the roles you give to members (see Your Own Roles). aviate_owner and aviate_read are created by the Aviate plugin in the next step (see Built-In Roles).
Step 3: Turn On the Checks
Set the com.killbill.billing.plugin.aviate.auth.permissions.mode property of the Aviate plugin:
| Mode | Behavior |
|---|---|
|
No permission checks. Aviate calls Kill Bill with the plugin’s own credentials. |
|
Requests that would be refused are logged with the missing permission, but are not blocked. Aviate still calls Kill Bill with the plugin’s own credentials. |
|
Requests without the required permissions are refused with |
We recommend running in log mode first, then switching to enforce once the logs show that your roles match how your teams work.
The plugin caches role definitions for 60 seconds (com.killbill.billing.plugin.aviate.auth.permissions.roleCacheTtlSeconds). A change to a role’s permissions applies within that delay. A change to a member’s role applies the next time the member’s session is refreshed.
Error Responses
A caller without the required permissions gets 403 Forbidden. With Accept: application/problem+json, the response body is:
{
"status": 403,
"detail": "Missing Aviate permission"
}
The Aviate plugin log names the missing Aviate or Kill Bill permission.
A request without valid credentials gets 401 Unauthorized. In enforce mode, Aviate never falls back to its own credentials for a caller Kill Bill could not authenticate.
Permission Reference
Paths are relative to /plugins/aviate-plugin. The Kill Bill column lists the Kill Bill permissions the endpoint also requires.
The following endpoints need no permission: POST /v1/auth (issues the token) and GET /healthcheck (any authenticated caller).
Billing Accounts
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
Quotes
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Quote Template
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
Related Parties
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
Orders
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
Contracts
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Catalog, Pricing and Tax
Applies to /v1/catalog/**: plans, products, input data, product specifications, offerings and prices.
| Endpoint | Aviate | Kill Bill |
|---|---|---|
Every |
|
|
|
|
|
|
|
|
Usage Rating
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Metering
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
|
Coupons
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
Discount and Approval Policies
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
Approvals
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
Intents
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
Workflows
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
The Kill Bill permissions of the workflow’s steps |
Wallets
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Revenue Recognition
| Endpoint | Aviate | Kill Bill |
|---|---|---|
Every |
|
|
|
|
|
|
|
|
|
|
BI Reports
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
Health
| Endpoint | Aviate | Kill Bill |
|---|---|---|
|
|
|
|
|
|
|
|
|
Summary
| Group | Actions |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Related
-
Aviate Members — invite members and give them a role
-
Aviate Single Sign-On — sign in with your organization’s identity provider
-
Aviate Authentication — obtain an ID token
-
Kill Bill Security APIs — create and update roles