Documentation
ΒΆ
Overview ΒΆ
Package stewardauthz is Steward's access engine, evaluated in-process by the services that need an access decision. It has two parts.
The permission catalog (Permission, Role, RolePermissions) names every permission and the roles that grant it. Authorize decides one permission for a Subject on a Resource: the capability gate, then category scope for the scoped permissions (a grant on a category covers every category below it), then, for a read, per-document overrides, break glass and sensitivity.
The category rule engine (CategoryRuleset, Compile, Resolve) decides the four governed actions, read, acknowledge, approve and author, from a category's ordered rules and those of its ancestors. The first rule with an opinion on the action wins, and anything no rule decides is denied. Read gates the other actions. Owners and site admins have the fixed rights listed on Compile.
Both parts run on github.com/Bugs5382/go-authz, and the errors the package returns carry go-apperr codes (see Entries). The package does no I/O.
Index ΒΆ
- Constants
- Variables
- func Entries() []apperr.Entry
- func HasCapability(s Subject, p Permission) bool
- type Action
- type CategoryRuleset
- type Decision
- type Effect
- type Evaluator
- type Grant
- type Option
- type Override
- type Permission
- type Reason
- type Resource
- type Result
- type Role
- type Rule
- type RuleDecision
- type RuleRef
- type RuleSubject
- type ScopedGrant
- type Subject
- type SubjectKind
Examples ΒΆ
Constants ΒΆ
const ( CodeDenied = 9001 CodeInvalidRule = 9002 CodeUnknownPermission = 9003 CodeUnknownRole = 9004 )
The codes this library attaches to the errors it returns.
const CodeBand = 9
CodeBand is the leading digit of every code this library emits, so its codes stay apart from the services' own bands.
Variables ΒΆ
var ( ErrDenied = errors.New("authz: access denied") ErrInvalidRule = errors.New("authz: invalid access rule") ErrUnknownPermission = errors.New("authz: unknown permission") ErrUnknownRole = errors.New("authz: unknown role") )
Sentinel errors, matched with errors.Is. Each one reaches a caller wrapped in its code (see Entries).
Functions ΒΆ
func Entries ΒΆ
Entries returns the go-apperr entries for this library's codes. A service adds them to the registry it builds at startup, so a coded error from here presents with the right category, symbol and user-safe message.
func HasCapability ΒΆ
func HasCapability(s Subject, p Permission) bool
HasCapability reports whether the subject could be allowed p in at least one scope: through a role, the individual read-sensitive grant, or, for a scoped permission, any scoped grant whose role confers it. It is the coarse check for work that spans categories; Authorize makes the per-resource decision.
Types ΒΆ
type Action ΒΆ
type Action string
Action is one of the four governed actions on a category's documents.
type CategoryRuleset ΒΆ
type CategoryRuleset struct {
Name string
// Owners are user IDs. An owner reads, approves and authors in this
// category and every category below it, ahead of any rule.
Owners []string
Rules []Rule
}
CategoryRuleset is one category's owners and its ordered rules.
func (CategoryRuleset) Validate ΒΆ
func (c CategoryRuleset) Validate() error
Validate checks a ruleset read from outside (storage, the admin editor). The error is coded CodeInvalidRule, matches ErrInvalidRule, and carries the category, the 1-based rule number and the problem as wire metadata.
type Decision ΒΆ
Decision is the outcome of Authorize.
func Authorize ΒΆ
func Authorize(s Subject, p Permission, r *Resource) Decision
Authorize decides p for the subject on r. r is nil for an action that is not aimed at one resource. A sensitive document is read only by its assigned authors and approvers and by explicit grants (the individual read-sensitive grant, an override allow, break glass); no role reads it.
Example ΒΆ
package main
import (
"fmt"
authz "github.com/Steward-GRC/steward-authz"
)
func main() {
bob := authz.Subject{
UserID: "bob",
Roles: []authz.Role{authz.RoleAuthor},
ScopedGrants: []authz.ScopedGrant{{Role: authz.RoleAuthor, Category: "Workplace"}},
}
doc := &authz.Resource{ID: "POL-FACILITIES-000001", Category: "Facilities", CategoryLineage: []string{"Facilities", "Workplace"}}
fmt.Println(authz.Authorize(bob, authz.PolicySubmit, doc).Effect)
fmt.Println(authz.Authorize(bob, authz.PolicyApprove, doc).Reason)
}
Output: allow missing_capability
type Evaluator ΒΆ
type Evaluator struct {
// contains filtered or unexported fields
}
Evaluator is a compiled category chain. It is read-only once built and safe to share between goroutines.
func Compile ΒΆ
func Compile(chain []CategoryRuleset, opts ...Option) *Evaluator
Compile builds an Evaluator for chain: the target category first, then its ancestors up to the root. For each action the order is: site admin and root read; owners anywhere in the chain read, approve and author; then every rule top-down, target category first. The first rule with a non-blank cell for the action decides, and anything left is denied.
Compile is also the access simulator: pass a draft chain to preview unsaved rules.
Example ΒΆ
package main
import (
"context"
"fmt"
authz "github.com/Steward-GRC/steward-authz"
)
func main() {
chain := []authz.CategoryRuleset{
{Name: "Facilities", Rules: []authz.Rule{
{Subject: authz.RuleSubject{Kind: authz.SubjectGroup, Name: "Facilities team"},
Grants: map[authz.Action]authz.Grant{authz.ActionAuthor: authz.GrantAllow}},
}},
{Name: "Workplace", Owners: []string{"dave"}, Rules: []authz.Rule{
{Subject: authz.RuleSubject{Kind: authz.SubjectEveryone},
Grants: map[authz.Action]authz.Grant{authz.ActionRead: authz.GrantAllow, authz.ActionAcknowledge: authz.GrantAllow}},
}},
}
ev := authz.Compile(chain)
erin := authz.Subject{UserID: "erin", Groups: []string{"All staff"}}
r := ev.Resolve(context.Background(), erin)
fmt.Println(r.Read.Allowed, r.Read)
fmt.Println(r.Acknowledge.Allowed, r.Author)
}
Output: true β³ Workplace #1 allow everyone true no rule β default deny
func (*Evaluator) Acknowledgement ΒΆ
func (e *Evaluator) Acknowledgement(ctx context.Context, s Subject) RuleDecision
Acknowledgement is the acknowledge decision without the read gate, for a caller that settles read some other way, such as a per-document override. Owners, site admins and root are never asked to acknowledge automatically.
type Option ΒΆ
type Option func(*options)
Option configures Compile.
func WithLogger ΒΆ
WithLogger logs every decision at debug level through l.
type Override ΒΆ
Override pins one resource for one subject: GrantAllow always shows it, GrantDeny excludes it.
type Permission ΒΆ
type Permission string
Permission is one entry of the catalog, written "<resource>.<verb>".
const ( PolicyRead Permission = "policy.read" PolicyReadSensitive Permission = "policy.read_sensitive" PolicyAuthor Permission = "policy.author" PolicySubmit Permission = "policy.submit" PolicyApprove Permission = "policy.approve" TemplateManage Permission = "template.manage" WorkflowManage Permission = "workflow.manage" GroupManage Permission = "group.manage" UserManage Permission = "user.manage" RoleManage Permission = "role.manage" AuditRead Permission = "audit.read" ComplianceManage Permission = "compliance.manage" ComplianceReport Permission = "compliance.report" SettingsManage Permission = "settings.manage" DeliveryManage Permission = "delivery.manage" SessionManage Permission = "session.manage" )
The permission catalog.
func ParsePermission ΒΆ
func ParsePermission(s string) (Permission, error)
ParsePermission checks a permission name read from outside (storage, a token, an admin form) against the catalog.
func Permissions ΒΆ
func Permissions() []Permission
Permissions returns the whole catalog, in a stable order.
func RolePermissions ΒΆ
func RolePermissions(rs ...Role) []Permission
RolePermissions returns the catalog permissions the given roles grant together, in catalog order. The reader baseline is always included, and an unknown role adds nothing.
func (Permission) Resource ΒΆ
func (p Permission) Resource() string
Resource is the part before the first dot ("policy" in "policy.read").
func (Permission) Scoped ΒΆ
func (p Permission) Scoped() bool
Scoped reports whether the permission only takes effect inside the categories a subject holds a scoped grant for.
func (Permission) Verb ΒΆ
func (p Permission) Verb() string
Verb is the part after the first dot ("read" in "policy.read").
type Reason ΒΆ
type Reason string
Reason is a stable, machine-readable code for why a decision came out as it did, for decision logs and the access simulator.
const ( ReasonGranted Reason = "granted" ReasonMissingCapability Reason = "missing_capability" ReasonOutOfScope Reason = "out_of_category_scope" ReasonOverrideAllow Reason = "override_allow" ReasonBreakGlass Reason = "break_glass" ReasonExcluded Reason = "excluded" ReasonSensitive Reason = "sensitive" ReasonAssigned Reason = "assigned" )
The reasons Authorize returns.
const ( ReasonSiteAdminRead Reason = "site_admin_read" ReasonOwner Reason = "owner" ReasonRuleAllow Reason = "rule_allow" ReasonRuleDeny Reason = "rule_deny" ReasonDefaultDeny Reason = "default_deny" ReasonAuthorImpliesRead Reason = "author_implies_read" ReasonApproverImpliesRead Reason = "approver_implies_read" ReasonRequiresRead Reason = "requires_read" )
The reasons the rule engine returns.
type Resource ΒΆ
type Resource struct {
ID string
Category string
// CategoryLineage is the category names from this resource's category up
// to the root. When it is empty, Category alone is used.
CategoryLineage []string
Sensitive bool
// Authors and Approvers are the user IDs assigned to this document. On a
// sensitive document they are the only subjects, besides explicit grants,
// who may read it.
Authors []string
Approvers []string
}
Resource is what an action is aimed at.
type Result ΒΆ
type Result struct {
Read RuleDecision
Acknowledge RuleDecision
Approve RuleDecision
Author RuleDecision
}
Result is the decision for each of the four actions.
func Resolve ΒΆ
func Resolve(ctx context.Context, s Subject, chain []CategoryRuleset) Result
Resolve compiles chain and resolves it for s. Compile once and reuse the Evaluator when deciding for many subjects.
func (Result) Get ΒΆ
func (r Result) Get(a Action) RuleDecision
Get returns the decision for one action.
type Role ΒΆ
type Role string
Role is a named bundle of permissions.
const ( RoleReader Role = "reader" RoleAuthor Role = "author" RoleApprover Role = "approver" RoleTemplateAdmin Role = "template-admin" RoleComplianceAdmin Role = "compliance-admin" RoleSiteAdmin Role = "site-admin" )
The roles. Every signed-in subject is a reader implicitly; the role is never stored.
type Rule ΒΆ
type Rule struct {
Subject RuleSubject
Grants map[Action]Grant
}
Rule is one ordered row of a category's rule list: a subject with a grant per action. A missing action means GrantBlank.
type RuleDecision ΒΆ
RuleDecision is the outcome for one action. Rule is set when a rule decided, and nil for the built-in outcomes.
func Acknowledgement ΒΆ
func Acknowledgement(ctx context.Context, s Subject, chain []CategoryRuleset) RuleDecision
Acknowledgement compiles chain and returns the ungated acknowledge decision.
func (RuleDecision) String ΒΆ
func (d RuleDecision) String() string
String explains the decision in the words the access simulator shows.
type RuleRef ΒΆ
type RuleRef struct {
Category string
Depth int
Index int
Subject RuleSubject
}
RuleRef points at the rule that decided: Depth 0 is the target category, 1 its parent, and so on; Index is 0-based within that category.
type RuleSubject ΒΆ
type RuleSubject struct {
Kind SubjectKind
Name string
}
RuleSubject is who a rule targets. Name is a group name or a user ID, and empty for SubjectEveryone.
type ScopedGrant ΒΆ
ScopedGrant gives a role inside one category and, through the category lineage, every category below it.
type Subject ΒΆ
type Subject struct {
UserID string
Roles []Role
// Groups are directory group names; rule subjects match them ignoring case.
Groups []string
ScopedGrants []ScopedGrant
Overrides []Override
ReadSensitive bool
Root bool
// BreakGlass holds the resource IDs the subject has an active break-glass
// grant for.
BreakGlass map[string]bool
}
Subject is the signed-in person a decision is made for.
type SubjectKind ΒΆ
type SubjectKind string
SubjectKind says what a rule targets.
const ( SubjectEveryone SubjectKind = "everyone" SubjectGroup SubjectKind = "group" SubjectUser SubjectKind = "user" )
The subject kinds.