proxy

Documentation

Overview

Package proxy accepts externally asserted identities only from explicitly trusted requests. Trusted network placement alone is insufficient if the upstream forwards spoofed headers.

Index

• func IsWildcardCIDRs(cidrs []string) bool
• type Authenticator
  • func New[User any](cfg Config, issuer string, resolve Resolver[User]) (Authenticator[User], error)
  • func (a Authenticator[User]) Authenticate(r *http.Request) (User, error)
  • func (a Authenticator[User]) Validate() error
• type Config
  • func Defaults() Config
  • func Resolve(options Options) (Config, error)
  • func (cfg Config) Validate() error
• type Layer
• type Options
• type Resolver
• type TrustFunc
  • func TrustCIDRs(cidrs []string) (TrustFunc, error)

Functions

func IsWildcardCIDRs

func IsWildcardCIDRs(cidrs []string) bool

IsWildcardCIDRs reports whether all immediate TCP peers are explicitly trusted. The wildcard must be the sole list entry; other combinations are invalid.

Types

type Authenticator

type Authenticator[User any] struct {
	// Trust validates the immediate upstream. Nil denies all requests.
	Trust TrustFunc
	// Resolve maps the external identity into a local user.
	Resolve Resolver[User]
	// UsernameHeaders are tried in order until a nonempty value is found.
	UsernameHeaders []string
	// EmailHeaders are optional email-identity header names.
	EmailHeaders []string
	// DisplayNameHeaders are optional human-readable name headers.
	DisplayNameHeaders []string
	// GroupHeaders contain optional comma-separated group names.
	GroupHeaders []string
	// Issuer is a stable deployment-specific namespace for asserted users.
	Issuer string
}

Authenticator enforces an ingress trust boundary before reading identity headers.

func New

func New[User any](cfg Config, issuer string, resolve Resolver[User]) (Authenticator[User], error)

New builds an authenticator from a resolved configuration and an application-owned resolver. It does not choose an issuer or user provisioning policy on the application's behalf.

func (Authenticator[User]) Authenticate

func (a Authenticator[User]) Authenticate(r *http.Request) (User, error)

Authenticate converts trusted headers into a verified external identity.

func (Authenticator[User]) Validate

func (a Authenticator[User]) Validate() error

Validate checks that ingress trust and identity resolution are explicitly configured.

type Config

type Config struct {
	// TrustedCIDRs contains immediate-peer networks, or a sole * for explicitly unrestricted peers.
	TrustedCIDRs []string
	// UsernameHeaders are checked in order for an asserted username.
	UsernameHeaders []string
	// EmailHeaders are checked in order for an asserted email address.
	EmailHeaders []string
	// DisplayNameHeaders are checked in order for an optional display name.
	DisplayNameHeaders []string
	// GroupHeaders are checked in order for optional group membership.
	GroupHeaders []string
}

Config contains the effective identity headers and ingress trust boundary. Obtain it through Resolve rather than replicating framework defaults in an application.

func Defaults

func Defaults() Config

Defaults returns independent copies of the standard identity header lists. No network peers are trusted by default.

func Resolve

func Resolve(options Options) (Config, error)

Resolve applies defaults, persisted settings and explicit deployment overrides in that order, then validates the effective proxy authentication configuration.

func (Config) Validate

func (cfg Config) Validate() error

Validate checks trusted-peer networks and HTTP identity header configuration.

type Layer

type Layer struct {
	// TrustedCIDRs overrides the immediate-peer allowlist when non-nil.
	TrustedCIDRs *[]string
	// UsernameHeaders overrides username header priority when non-nil.
	UsernameHeaders *[]string
	// EmailHeaders overrides email header priority when non-nil.
	EmailHeaders *[]string
	// DisplayNameHeaders overrides display-name header priority when non-nil.
	DisplayNameHeaders *[]string
	// GroupHeaders overrides group header priority when non-nil.
	GroupHeaders *[]string
}

Layer describes explicitly present settings; nil means inherit, while a pointer to an empty slice intentionally clears an inherited setting.

type Options

type Options struct {
	// Persisted contains application-managed settings, distinct from absent values.
	Persisted Layer
	// Overrides contains explicit CLI or environment settings and takes precedence.
	Overrides Layer
}

Options defines persisted settings and higher-priority deployment overrides.

type Resolver

type Resolver[User any] func(context.Context, auth.ExternalIdentity) (User, error)

Resolver maps a verified external identity into an application-owned user.

type TrustFunc

type TrustFunc func(*http.Request) bool

TrustFunc returns true only when a request came through a verified ingress. The ingress must strip client-supplied identity headers and set its own.

func TrustCIDRs

func TrustCIDRs(cidrs []string) (TrustFunc, error)

TrustCIDRs checks the immediate TCP peer against configured networks, or all valid peers when the sole entry is "*". It never trusts forwarded IP headers. The ingress must strip and replace any client-supplied identity headers.