Congratulations on your new Housecarl AuthZ service.
This guide assumes that you are are starting from scratch, just after the initial bootup or initial signup online.
If you are running a self-hosted Housecarl AuthZ service, start here. Otherwise, please move to Domain Configuration.
On a first bootup of an on-prem housecarl, you will have 3 tenants premade:
Root is for system operators. This is the root of trust for the entire system. Policies granting root tenant users authority are baked into the system. Plausibly someone might want to disable all API access to this tenant after initial setup.
The Lookaside tenant and its associated domain holds the policies for Housecarl users API access. Since users are not directly generated from tenants, their policies are standalone.
The Smoke tenant is designed for the housecarl-smoker continuous smoke
test runner. In a production deployment, the housecarl-smoker binary
should be deployed in order to continually validate at a slow rate of
operation that the API is operating correctly.
The first action should be to create a normal user (non-root). A user
is not homed or associated with any tenant initially. Let's call
that user operator for the purposes of this documentation.
Then, log into operator and get the system shaken out.
When logging in, a user can either log in homed with a tenant or not. When a user is homed with a tenant, requests are treated as originating with that tenant, and policies can be written against that possibility.
We recommend two tenants be created:
Each tenant, when created, will also have a domain created with it by the name of "root". The "root" domain holds the initial permissions for that specific tenant, including granting permissions for the creating user, along with permissions for the root tenant users to perform operations.
tl;dr
The housecarl-admin tool directly interacts with the PostgreSQL database and side-steps the API.
# housecarl-admin user set-password root random-password
# housecarl-admin user disable root
# housecarl-admin tenant disable root
Log in with operator to application-test. When you do housectl domain list-domains, you will see 1 domain, root. This is the
starter policy system.
let's look at the policies:
housectl domain show-policies --name root
# blerp
Let's say you want to add a policy:
policy.toml
# blerp
Let's add it-
housectl policy add-policy --domain root --file policy.toml
When housecarl changes policies, this is an atomic operation on the domain. The entire list of policies is modified in a single database transaction. For adding a policy as above, this is done in three steps:
name being the primary key