Documentation
¶
Overview ¶
Package authz carries the authorization decisions made while serving a request, so that later middleware can describe what happened without having to reconstruct it from the request's shape. See the package README.
Index ¶
- Variables
- func Declare(ctx context.Context, target Target)
- func Name(ctx context.Context, name string)
- func NewContext(ctx context.Context, recorder *Recorder) context.Context
- func Record(ctx context.Context, decision Decision)
- type Decision
- type Kind
- type Operation
- type Recorder
- type RequestState
- type Scope
- type Target
Constants ¶
This section is empty.
Variables ¶
var ( Create = Operation{Access: openapi.Create, Action: "create"} Read = Operation{Access: openapi.Read, Action: "read"} Update = Operation{Access: openapi.Update, Action: "update"} Delete = Operation{Access: openapi.Delete, Action: "delete"} )
The CRUD operations, where the action is the access.
Functions ¶
func Declare ¶ added in v1.26.0
Declare states what the request is on the context's recorder, and does nothing when there is none. A handler that can fail before its own check, for example on fetching the object it checks, declares first so that the failure is still described. See the README.
func Name ¶
Name sets the display name on the decision describing the request.
A caller that only learns the name after authorizing uses this to supply it: a create names a resource that did not exist when it was authorized, and a resource whose name is not its metadata.name, such as a user named by its subject, is only known once it has been read.
It does nothing until the request is declared or checked, so a name known earlier is supplied in the declaration.
func NewContext ¶
NewContext returns a context carrying the recorder.
func Record ¶
Record adds a decision to the context's recorder, and does nothing when there is none.
Absence is normal rather than exceptional: authorization also runs in controllers, tests and internal paths that never pass through the audit middleware. Those must not be made to fail by a recording concern.
Types ¶
type Decision ¶
type Decision struct {
// Target is what was checked: the resource type, the operation, whether
// this describes the request or a precondition of it, and the resource
// acted on.
Target
// Scope is the tenancy the check was performed against.
Scope Scope
// Allowed is the outcome. Refusals are kept only for the request's own
// decision: a refused precondition is never read, and keeping it would
// turn routine list filtering into noise.
Allowed bool
}
Decision is one authorization check and its outcome.
type Kind ¶
type Kind int
Kind says whether a decision describes the request itself or one of its preconditions.
A request often makes several checks. Updating a group checks that the caller may update groups, and then, for each role being added, that the caller may grant that role. Only the first describes what happened; the others are the evidence for why it was permitted.
const ( // Subordinate is a precondition of the request. It is the zero value // deliberately: a decision whose kind was never stated must not be taken // for the request's own operation, because that would silently relabel a // precondition as the event. A mutating request that records no primary // decision is a defect, and a loud one is better than a wrong record. Subordinate Kind = iota // Primary is the operation the request is. Primary )
type Operation ¶
type Operation struct {
Access openapi.AclOperation
Action string
}
Operation is what was done, held as two facts because they answer different questions and conflating them loses one of them.
Access is the permission required, and is what RBAC matches against. Action is what actually happened, and is what an audit record needs. For plain CRUD the two agree. They part company on an action sub-resource: starting an instance and creating one are both POST, so the HTTP method cannot tell them apart, and describing a start as "update" tells a reader nothing about what occurred.
Keeping them separate also forces a deliberate answer to "what permission should starting an instance require?", which is a question an implementation can otherwise avoid by reusing whichever check was nearest.
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder accumulates the decisions made while serving one request.
A request has exactly one decision describing it, the request decision, and any number of allowed preconditions, such as checking the caller may grant each role they are adding to a group. The first statement of what the request is, a declaration or its own check, names the target; later checks of it only add the scope and the outcome. See the README.
func FromContext ¶
FromContext returns the recorder, if one was installed.
func (*Recorder) Decisions ¶
Decisions returns a copy of what has been recorded, so a consumer cannot alter the record it is describing.
func (*Recorder) Declare ¶ added in v1.26.0
Declare states what the request is before anything can fail. It does nothing when the request is already described.
func (*Recorder) Name ¶
Name sets the display name on the request decision. See the package level Name.
func (*Recorder) Record ¶
Record adds a decision. The request's own decision is merged into the one request decision, and a refused precondition is dropped.
func (*Recorder) Request ¶ added in v1.26.0
func (r *Recorder) Request() (Decision, RequestState)
Request returns the decision describing the request and how much is known.
type RequestState ¶ added in v1.26.0
type RequestState int
RequestState says how much is known about what the request is.
const ( // NotDescribed means nothing was declared or checked. NotDescribed RequestState = iota // Declared means the handler stated the request, but its own check has // not run, as when the object was not found or a dependency was refused. Declared // Checked means the request's own check ran, allowed or refused. Checked )
type Scope ¶
type Scope struct {
// OrganizationID is the zero value for a globally scoped decision.
OrganizationID ids.OrganizationID
// ProjectID is the zero value for an organization scoped decision.
ProjectID ids.ProjectID
}
Scope is the tenancy an operation was authorized within.
This is the fact that cannot be recovered from the URL. v1 APIs carried the organization and project in the path; v2 APIs address resources by ID alone and resolve tenancy from the resource's labels, so only the component that performed the check knows it.
func (Scope) Organization ¶
Organization reports whether the scope names an organization.
type Target ¶
type Target struct {
// Endpoint is the RBAC endpoint, which names the resource type.
Endpoint string
// Operation is the access required and the action performed.
Operation Operation
// Kind says whether this describes the request or a precondition of it.
Kind Kind
// ObjectName is the resource's display name, so a reader does not have to
// resolve an identifier to know what was touched, and can still tell after
// the resource is gone. Empty where the caller does not hold it.
ObjectName string
// ObjectID identifies the resource acted on. It is the zero value for a
// create, where the resource does not exist at the point it is authorized,
// and for operations that address no single resource.
//
// A bare UUID rather than one of the typed ids, because a resource here may
// belong to any service and this package cannot name their identifier types.
// Convert at the call site, which keeps the caller's own type checked.
ObjectID uuid.UUID
}
Target is what an authorization check was about.