authz

package
v1.29.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

README

pkg/authz

This package carries the authorization decisions made while serving a request, so later middleware can describe what happened without reconstructing it from the request's shape.

Intent

Audit records have to say which organization and project an operation affected. That fact used to be read out of the URL, because v1 APIs put it there:

/api/v1/organizations/{organizationID}/projects/{projectID}/networks/{networkID}

v2 APIs do not. Resources are addressed by ID alone, and tenancy is resolved from the resource's own labels during the request. There is nothing in the path to read, so anything deriving scope from the URL silently records nothing for every v2 operation.

The component that already knows is the authorizer. It cannot decide whether a caller may delete a network without first resolving which project that network belongs to. This package is how that answer is kept rather than discarded.

Core model

A Decision is one authorization check: the endpoint, the access required, the scope it was checked against, and the outcome. A Recorder accumulates them for one request and is carried in the request context.

One request commonly produces several. Updating a group checks that the caller may update groups, and then, for each role being added, that the caller may grant that role. Those are not separate events — the second kind are preconditions of the first, and are the evidence for why it was permitted.

So a request has exactly one decision describing it, the request decision, and any number of allowed preconditions. One record per request, whatever the outcome, is what an auditor needs; Request() returns that decision and how much is known about it:

  • Declared: the handler stated the request with Declare before anything could fail, and its own check never ran, as when the object was not found or a dependency was refused. The record still says what was attempted, with no scope, because none was checked.
  • Checked: the request's own check ran, allowed or refused.

The first statement of what the request is, a declaration or its own check, names the target. Later checks of it, such as the same check run again on a conflict retry, add only the scope and the outcome, and fill fields the declaration left empty: a create's check names no object, and must not erase one that was declared. A later check naming a different endpoint or action does not relabel the request; it is reported through Defects(), because the handler declared one thing and checked another.

A handler that fetches before it can check, because the scope lives on the object, declares first. One that checks first needs no declaration.

Target

A Target says what a check was about: the resource type, the operation, the resource acted on, and whether this is the operation the request is or a precondition of it.

Operation holds two facts rather than one, because they answer different questions. Access is the permission required, which is what RBAC matches against. Action is what actually happened, which is what an audit record needs. For plain CRUD they 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 recording a start as "update" says nothing about what occurred. Keeping them separate also forces a deliberate answer to what permission starting an instance should require, rather than reusing whichever check happened to be nearest.

Kind separates the operation a request is from the checks it had to pass first. Subordinate is the zero value deliberately: a decision whose kind was never stated must not be mistaken for the request's own operation, because that would silently relabel a precondition as the event. A request that succeeds without its own check ever running is a defect, and reporting that loudly is better than emitting a wrong record quietly.

Invariants

  • Scope comes from the authorizer, never from the request path. The path is not a reliable source in v2 and is only accidentally one in v1.
  • Identifiers are the typed ones from pkg/ids, not strings. The point of those types is that the compiler refuses to interchange them, and a record of what happened is the last place to give that up.
  • Record on a context with no recorder does nothing. Authorization also runs in controllers, tests and internal paths that never see the audit middleware, and a recording concern must never make those fail.
  • Decisions returns a copy. A consumer describing the record must not be able to alter it.
  • The recorder keeps decisions in the order they were first made and is safe to use concurrently, because a handler may make checks from several goroutines.
  • Only the request decision keeps a refusal. A refused precondition is never read, and keeping it would turn routine list filtering into noise, so a gate used as a list filter costs nothing.

Caveats

  • A request is assumed to have one subject. Nothing in identity, compute or region acts on several resources in one request today; one that does would need the recorder to hold more than one request decision.
  • A decision made through one of the gates that predate the explicit form names no object and no action, and counts as a precondition rather than the request's own operation. Migrating the call site is what fills those in.

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

Constants

This section is empty.

Variables

View Source
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

func Declare(ctx context.Context, target Target)

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

func Name(ctx context.Context, name string)

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

func NewContext(ctx context.Context, recorder *Recorder) context.Context

NewContext returns a context carrying the recorder.

func Record

func Record(ctx context.Context, decision Decision)

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.

func Primaries

func Primaries(decisions []Decision) []Decision

Primaries returns the decisions describing requests rather than their preconditions.

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.

func Action

func Action(access openapi.AclOperation, action string) Operation

Action names an operation that is not plain CRUD, such as starting an instance, and states the access it requires.

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

func FromContext(ctx context.Context) (*Recorder, bool)

FromContext returns the recorder, if one was installed.

func (*Recorder) Decisions

func (r *Recorder) Decisions() []Decision

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

func (r *Recorder) Declare(target Target)

Declare states what the request is before anything can fail. It does nothing when the request is already described.

func (*Recorder) Defects added in v1.26.0

func (r *Recorder) Defects() []string

Defects returns handler mistakes found while recording.

func (*Recorder) Name

func (r *Recorder) Name(name string)

Name sets the display name on the request decision. See the package level Name.

func (*Recorder) Record

func (r *Recorder) Record(decision Decision)

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

func (s Scope) Organization() bool

Organization reports whether the scope names an organization.

func (Scope) Project

func (s Scope) Project() bool

Project reports whether the scope names a project.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL