The Housecarl AuthZ algorithm is a robust and flexible authorization system designed to handle complex access control scenarios. This section explains the key components and concepts of the algorithm in a somewhat formal way; it assumes some background with authenication, authorization and some mathematical fluency for the set theoretic treatment. See the Dev cookbook for a less vertical flightpath for developers, and the Policy cookbook for policy work.
A Resource represents a hierarchical resource identifier with three main components:
Example: hc://domain/segment1/segment2
A Request encapsulates the context of an access attempt, including:
A Policy defines rules for access control. It consists of:
A Domain represents a logical grouping of resources and policies. It contains:
Request Initialization:
Request objectDomain Resolution:
Policy Collection:
Policy Evaluation:
Authorization Decision:
The algorithm supports various evaluation engines:
Domains can inherit policies from superior domains, allowing for hierarchical policy structures.
The system can consider various contextual factors beyond just subject, action, and object, such as time, location, device type, etc.
Policies can be set to explicitly deny access or invert their evaluation result, providing fine-grained control.
Role-Based Access Control (RBAC): <
let rbac_policy = Policy {
name: "RBAC Policy",
engine: EvaluationEngine::RegEx,
statements: vec![
[("role", "admin"), ("action", ".*"), ("object", "hc://.*")].into_iter().collect(),
[("role", "user"), ("action", "read"), ("object", "hc://public/.*")].into_iter().collect(),
],
deny: false,
invert: false,
};
Time-Based Access:
let time_policy = Policy {
name: "Working Hours Policy",
engine: EvaluationEngine::RegEx,
statements: vec![
[("action", ".*"), ("time", "^(0[9-9]|1[0-7]):[0-5][0-9]$")].into_iter().collect(), <!-- TZ? -->
],
deny: false,
invert: false,
};
Geolocation Restrictions:
let geo_policy = Policy {
name: "Geo Policy",
engine: EvaluationEngine::RegEx,
statements: vec![
[("action", ".*"), ("country_code", "^(US|CA)$")].into_iter().collect(),
],
deny: false,
invert: false,
};
The Housecarl AuthZ algorithm provides a powerful and flexible framework for implementing complex authorization scenarios. By combining structured resources, context-rich requests, and multi-faceted policies, it can address a wide range of access control requirements in modern applications.
This appendix provides a formal mathematical and set theoretic representation of the Housecarl AuthZ algorithm.
Let:
A Resource r ∈ R is defined as a tuple:
r = (prefix, noun, segments)
where:
A Request q is defined as:
q = (s, a, r, c)
where:
A Policy p ∈ P is defined as:
p = (name, E, Σ, δ, ι)
where:
A Domain d ∈ D is defined as:
d = (id, name, S, P, t)
where:
Let eval be the evaluation function:
eval: P × Q → {true, false}
where Q is the set of all possible Requests.
For a policy p and request q:
eval(p, q) = E(Σ, q) ⊕ ι
where ⊕ is the XOR operation, and E is the policy's evaluation engine function.
For a domain d and request q, the domain evaluation function D is:
D(d, q) = ⋀_{p ∈ P_d} eval(p, q)
where P_d is the set of all policies associated with d and its superior domains.
The final authorization decision for a request q in domain d is given by:
Auth(d, q) = D(d, q) ∧ ¬(⋁_{p ∈ P_d | p.δ = true} eval(p, q))
This formula states that authorization is granted if all non-deny policies evaluate to true AND no deny policy evaluates to true.
For a domain d, its effective policy set P_eff(d) is defined recursively as:
P_eff(d) = P_d ∪ (⋃_{s ∈ S_d} P_eff(s))
where P_d is the set of policies directly associated with d, and S_d is the set of superior domains of d.
For a Resource r and a pattern ρ, the matching function M is defined as:
M(r, ρ) = E_ρ(r.prefix ++ r.noun ++ r.segments, ρ)
where E_ρ is the pattern matching function (e.g., regex, prefix, or exact matching), and ++ denotes string concatenation.
This mathematical and set theoretic framing provides a formal basis for understanding and analyzing the Housecarl AuthZ algorithm. It defines the core components as mathematical objects and expresses the key operations as functions and set operations.
When a superior domain is removed from a domain's hierarchy, it affects the policy inheritance and potentially the authorization decisions. Let's formalize this process:
Let d ∈ D be a domain, and s ∈ S_d be a superior domain that is to be removed.
The new set of superior domains S'_d for domain d after removal of s is defined as:
S'_d = S_d \ {s}
where \ denotes set difference.
The updated effective policy set P'_eff(d) for domain d after removal of s is defined recursively as:
P'eff(d) = P_d ∪ (⋃{s' ∈ S'_d} P'_eff(s'))
This means that the policies from the removed superior domain s and its superiors (unless they are also superiors of other remaining superior domains) are no longer included in the effective policy set of d.
The impact on authorization decisions can be expressed as the difference between the old and new authorization functions:
ΔAuth(d, q) = Auth(d, q) - Auth'(d, q)
where Auth(d, q) is the original authorization decision function and Auth'(d, q) is the authorization decision function after the removal of the superior domain.
If ΔAuth(d, q) ≠ 0 for any q, then the removal of the superior domain has changed the authorization behavior for domain d.
To preserve consistency in the authorization system after removing a superior domain, the following condition should hold for all requests q:
∀q ∈ Q, Auth'(d, q) ⊆ Auth(d, q)
This condition ensures that removing a superior domain does not grant any new permissions that weren't previously allowed.
After the removal of a superior domain, all cached or pre-computed policy decisions for the affected domain d and its subordinate domains should be invalidated and reevaluated using the updated effective policy set P'_eff(d).
In practice, this means:
This formal treatment of superior domain removal ensures that the impact of such an operation is well-defined and its effects on the authorization system are clearly understood. It provides a basis for implementing this operation in a way that maintains the integrity and consistency of the authorization system.