authzen

Documentation

Overview

Package authzen implements the AuthZEN Authorization API based on the OpenID AuthZEN specification.

AuthZEN defines a standard API for communication between Policy Enforcement Points (PEPs) and Policy Decision Points (PDPs), enabling fine-grained authorization decisions.

EXPERIMENTAL

This package implements a draft specification that is subject to change. The API may change in backwards-incompatible ways as the specification evolves.

Protocol Overview

AuthZEN provides a REST API for authorization decisions:

• Evaluation API: Single access decision requests
• Batch Evaluation: Multiple decisions in one request
• Subject/Resource/Action model with extensible properties

Basic flow:

1. PEP constructs evaluation request with subject, resource, action, context
2. PEP sends request to PDP via AuthZEN API
3. PDP evaluates policies (Cedar, OpenFGA, OPA, etc.)
4. PDP returns decision (PERMIT, DENY, INDETERMINATE)
5. PEP enforces the decision

Agent Integration

For AI agents, the subject typically includes:

• Agent identity (SPIFFE ID, agent ID)
• Delegating user (from ID-JAG "act" claim)
• Mission scope (from AAuth)

Example evaluation request for an agent:

{
  "subject": {
    "type": "agent",
    "id": "code-review-agent",
    "properties": {
      "workload_id": "spiffe://example.com/agent/code-review",
      "delegator": "user:alice",
      "capabilities": ["code-review", "security-scan"]
    }
  },
  "resource": {
    "type": "repository",
    "id": "acme/backend",
    "properties": {
      "visibility": "private"
    }
  },
  "action": {
    "name": "comment",
    "properties": {
      "pr_number": 123
    }
  },
  "context": {
    "time": "2024-01-15T10:30:00Z",
    "mission": "code-review:pr-123"
  }
}

References

• OpenID AuthZEN: https://openid.net/specs/openid-authzen-authorization-api-1_0.html
• Cedar: https://www.cedarpolicy.com/
• OpenFGA: https://openfga.dev/

Index

• type Action
  • func NewAction(name string, properties map[string]any) Action
• type BatchEvaluationRequest
• type BatchEvaluationResponse
• type Client
  • func NewClient(baseURL string, opts ...ClientOption) *Client
  • func (c *Client) BaseURL() string
  • func (c *Client) Evaluate(ctx context.Context, req *EvaluationRequest) (*EvaluationResponse, error)
  • func (c *Client) EvaluateBatch(ctx context.Context, req *BatchEvaluationRequest) (*BatchEvaluationResponse, error)
  • func (c *Client) IsAllowed(ctx context.Context, subject Subject, resource Resource, action Action) (bool, error)
  • func (c *Client) IsAllowedWithContext(ctx context.Context, subject Subject, resource Resource, action Action, ...) (bool, error)
• type ClientOption
  • func WithBearerToken(token string) ClientOption
  • func WithEvaluationPath(path string) ClientOption
  • func WithHTTPClient(client *http.Client) ClientOption
  • func WithHeader(key, value string) ClientOption
• type Context
  • func NewContext() Context
  • func (c Context) WithContextValue(key string, value any) Context
• type Decision
  • func (d Decision) IsAllowed() bool
  • func (d Decision) MarshalJSON() ([]byte, error)
  • func (d *Decision) UnmarshalJSON(data []byte) error
• type ErrorResponse
  • func (e *ErrorResponse) Error() string
• type EvaluationRequest
• type EvaluationResponse
• type Resource
  • func NewResource(resourceType, resourceID string, properties map[string]any) Resource
• type Subject
  • func AgentSubject(agentID string, opts ...SubjectOption) Subject
• type SubjectOption
  • func WithCapabilities(capabilities []string) SubjectOption
  • func WithDelegator(userID string) SubjectOption
  • func WithMission(mission string) SubjectOption
  • func WithWorkloadID(spiffeID string) SubjectOption

Types

type Action

type Action struct {
	// Name is the action name (e.g., "read", "write", "delete").
	Name string `json:"name"`

	// Properties contains additional action attributes.
	Properties map[string]any `json:"properties,omitempty"`
}

Action represents the requested action.

func NewAction

func NewAction(name string, properties map[string]any) Action

NewAction creates an Action with the given name.

type BatchEvaluationRequest

type BatchEvaluationRequest struct {
	// Evaluations is the list of individual requests.
	Evaluations []EvaluationRequest `json:"evaluations"`
}

BatchEvaluationRequest contains multiple evaluation requests.

type BatchEvaluationResponse

type BatchEvaluationResponse struct {
	// Evaluations is the list of individual responses.
	Evaluations []EvaluationResponse `json:"evaluations"`
}

BatchEvaluationResponse contains multiple evaluation responses.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an AuthZEN PDP client.

func NewClient

func NewClient(baseURL string, opts ...ClientOption) *Client

NewClient creates a new AuthZEN PDP client.

func (*Client) BaseURL

func (c *Client) BaseURL() string

BaseURL returns the configured base URL.

func (*Client) Evaluate

func (c *Client) Evaluate(ctx context.Context, req *EvaluationRequest) (*EvaluationResponse, error)

Evaluate sends an evaluation request to the PDP.

func (*Client) EvaluateBatch

func (c *Client) EvaluateBatch(ctx context.Context, req *BatchEvaluationRequest) (*BatchEvaluationResponse, error)

EvaluateBatch sends multiple evaluation requests to the PDP.

func (*Client) IsAllowed

func (c *Client) IsAllowed(ctx context.Context, subject Subject, resource Resource, action Action) (bool, error)

IsAllowed is a convenience method that evaluates and returns true if permitted.

func (*Client) IsAllowedWithContext

func (c *Client) IsAllowedWithContext(ctx context.Context, subject Subject, resource Resource, action Action, evalContext Context) (bool, error)

IsAllowedWithContext evaluates with additional context.

type ClientOption

type ClientOption func(*Client)

ClientOption configures the Client.

func WithBearerToken

func WithBearerToken(token string) ClientOption

WithBearerToken sets a bearer token for authentication.

func WithEvaluationPath

func WithEvaluationPath(path string) ClientOption

WithEvaluationPath sets a custom evaluation endpoint path.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient sets a custom HTTP client.

func WithHeader

func WithHeader(key, value string) ClientOption

WithHeader adds a custom header to all requests.

type Context

type Context map[string]any

Context contains request context and environment.

func NewContext

func NewContext() Context

NewContext creates a Context with common fields.

func (Context) WithContextValue

func (c Context) WithContextValue(key string, value any) Context

WithContextValue adds a value to the context.

type Decision

type Decision string

Decision represents an authorization decision from the PDP.

const (
	// DecisionPermit indicates the action is allowed.
	DecisionPermit Decision = "PERMIT"

	// DecisionDeny indicates the action is denied.
	DecisionDeny Decision = "DENY"

	// DecisionIndeterminate indicates the PDP could not make a decision.
	DecisionIndeterminate Decision = "INDETERMINATE"

	// DecisionNotApplicable indicates no policies apply to the request.
	DecisionNotApplicable Decision = "NOT_APPLICABLE"
)

Standard authorization decisions.

func (Decision) IsAllowed

func (d Decision) IsAllowed() bool

IsAllowed returns true if the decision permits the action.

func (Decision) MarshalJSON

func (d Decision) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for Decision.

func (*Decision) UnmarshalJSON

func (d *Decision) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for Decision.

type ErrorResponse

type ErrorResponse struct {
	// Code is the error code.
	Code string `json:"error"`

	// Description is a human-readable error description.
	Description string `json:"error_description,omitempty"`
}

ErrorResponse represents an error from the PDP.

func (*ErrorResponse) Error

func (e *ErrorResponse) Error() string

Error implements the error interface.

type EvaluationRequest

type EvaluationRequest struct {
	// Subject is the entity requesting access.
	Subject Subject `json:"subject"`

	// Resource is the protected resource.
	Resource Resource `json:"resource"`

	// Action is the requested action.
	Action Action `json:"action"`

	// Context contains additional request context.
	Context Context `json:"context,omitempty"`
}

EvaluationRequest is the request body for the evaluation API.

type EvaluationResponse

type EvaluationResponse struct {
	// Decision is the authorization decision.
	Decision Decision `json:"decision"`

	// Context contains additional response context from the PDP.
	Context map[string]any `json:"context,omitempty"`
}

EvaluationResponse is the response from the evaluation API.

type Resource

type Resource struct {
	// Type is the resource type (e.g., "repository", "document", "api").
	Type string `json:"type"`

	// ID is the unique identifier for the resource.
	ID string `json:"id"`

	// Properties contains additional resource attributes.
	Properties map[string]any `json:"properties,omitempty"`
}

Resource represents the protected resource.

func NewResource

func NewResource(resourceType, resourceID string, properties map[string]any) Resource

NewResource creates a Resource with the given type and ID.

type Subject

type Subject struct {
	// Type is the subject type (e.g., "user", "agent", "service").
	Type string `json:"type"`

	// ID is the unique identifier for the subject.
	ID string `json:"id"`

	// Properties contains additional subject attributes.
	Properties map[string]any `json:"properties,omitempty"`
}

Subject represents the entity requesting access.

func AgentSubject

func AgentSubject(agentID string, opts ...SubjectOption) Subject

AgentSubject creates a Subject for an AI agent.

type SubjectOption

type SubjectOption func(*Subject)

SubjectOption configures a Subject.

func WithCapabilities

func WithCapabilities(capabilities []string) SubjectOption

WithCapabilities adds agent capabilities to the subject.

func WithDelegator

func WithDelegator(userID string) SubjectOption

WithDelegator adds the delegating user to the subject.

func WithMission

func WithMission(mission string) SubjectOption

WithMission adds the current mission scope to the subject.

func WithWorkloadID

func WithWorkloadID(spiffeID string) SubjectOption

WithWorkloadID adds a SPIFFE workload ID to the subject.