provisioner

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Oct 3, 2026 License: AGPL-3.0 Imports: 23 Imported by: 0

Documentation

Overview

Package provisioner implements the Provisioner + SignOption pattern inspired by step-ca. Each Provisioner authenticates a request and returns SignOptions that control certificate issuance parameters.

Adding a new authentication method = adding a new Provisioner implementation.

Index

Constants

View Source
const (
	ErrInvalidName = provisionerError("provisioner: invalid name")
	ErrDuplicate   = provisionerError("provisioner: duplicate name")
	ErrNotFound    = provisionerError("provisioner: not found")
)
View Source
const AICJWTName = "aic-jwt"

AICJWTName is the registry name of the AIC-JWT bearer provisioner.

View Source
const MTLSName = "mtls"

MTLSName is the built-in mTLS provisioner name.

View Source
const (
	// OIDCName is the built-in OIDC provisioner name.
	OIDCName = "oidc"
)
View Source
const TokenName = "token"

TokenName is the built-in token provisioner name.

Variables

View Source
var AICJWTResolver func(token string, r *http.Request) (*AuthResult, error)

AICJWTResolver resolves a bearer token to an AuthResult. It receives the request so strict dual-carrier binding (mTLS certificate vs cnf.jkt) can be enforced. Set by the Server.

View Source
var AgentSessionMaxTTL time.Duration = 24 * time.Hour

AgentSessionMaxTTL caps how far into the future an X-Agent-TTL header may reach for delegated-agent certificates. Zero rejects delegated sessions entirely. Set at startup from Serve.AgentSessionMaxTTL.

View Source
var CertResolver func(issuerDN, serial string) (status, principalUid string, err error)

CertResolver looks up a client certificate forwarded by a trusted gateway (X-Client-Cert-DER passthrough) by (issuer DN, serial) and returns its status and principal_uid. Set by the Server to avoid circular imports.

View Source
var TokenResolver func(token string) (*AuthResult, error)

TokenResolver resolves a token/credential to an AuthResult. Set by the Server.

View Source
var TrustedGatewayOUs []string

TrustedGatewayOUs lists the OUs whose mTLS certs are trusted to assert delegated identities (X-Client-Cert-DER passthrough; legacy X-Agent-User username delegation also gated on this). Empty rejects gateway-asserted delegation entirely. Set at startup from Serve.TrustedGatewayOUs.

View Source
var UserResolver func(username string) (role string, perms []string, err error)

UserResolver looks up a username and returns the role and permission grants. Set by the Server to avoid circular imports.

Functions

func CertSpkiHash

func CertSpkiHash(cert *x509.Certificate) string

CertSpkiHash computes the certificate public key fingerprint (SHA-256 of SubjectPublicKeyInfo, hex).

func PEMToCert

func PEMToCert(pemData []byte) (*x509.Certificate, error)

func PeerCertFromRequest

func PeerCertFromRequest(r *http.Request) *x509.Certificate

func SetAICJWTResolver

func SetAICJWTResolver(fn func(string, *http.Request) (*AuthResult, error))

SetAICJWTResolver atomically installs the resolver (M23 fix: hot-reload writes no longer race with concurrent handler reads of the plain global).

func SetTokenResolver

func SetTokenResolver(fn func(string) (*AuthResult, error))

SetTokenResolver atomically installs the resolver (M23 fix: hot-reload writes no longer race with concurrent handler reads of the plain global).

Types

type AICJWTIdentity

type AICJWTIdentity struct {
	Principal    aicjwt.Principal
	Issuer       string
	TokenID      string
	Capabilities []string // FullID ("scheme:id") forms, acceptable to MatchCapability
}

AICJWTIdentity is the validated AIC-JWT principal identity handed to RBAC authorization. Capabilities are expressed as full identifiers (scheme:id), the same representation the certificate PA path uses.

type AICJWTProvisioner

type AICJWTProvisioner struct{}

AICJWTProvisioner authenticates requests via an AIC-JWT bearer token (draft-ietf-oauth-aic) issued by a local CA. Validation is delegated to the AICJWTResolver installed by the server, which anchors verification to the same trust root as X.509 (issuer keys are the configured CAs).

func NewAICJWTProvisioner

func NewAICJWTProvisioner() *AICJWTProvisioner

NewAICJWTProvisioner returns a stateless AIC-JWT provisioner.

func (*AICJWTProvisioner) Authenticate

func (p *AICJWTProvisioner) Authenticate(r *http.Request) (*AuthResult, error)

Authenticate checks for a Bearer AIC-JWT and delegates to the resolver. Non-Bearer requests and requests without a resolver are left for other provisioners (nil, nil).

func (*AICJWTProvisioner) Name

func (p *AICJWTProvisioner) Name() string

Name returns the provisioner name ("aic-jwt").

func (*AICJWTProvisioner) Type

func (p *AICJWTProvisioner) Type() string

Type returns the provisioner type.

type AICOption

type AICOption struct {
	Config ca.AICConfig
}

AICOption adds Agent Identity Certificate configuration.

func (*AICOption) Apply

func (o *AICOption) Apply(sc *ca.SignConfig) error

type AuthResult

type AuthResult struct {
	Username    string
	Role        string
	Permissions []string // grant patterns (e.g. "ca:*", "cert:issue")
	// CAScopes carries the effective CA scopes bound to the authentication.
	// For cert-first mTLS this is extracted from the client certificate
	// (SAN urn:pki:ca:* URIs + OID scope extension). Without it, enterprise
	// permission-mode checks have no scope to authorize against.
	CAScopes []string
	Options  []SignOption
	// CertIdentity records the client certificate identity snapshot bound to this authentication.
	// nil means no certificate (e.g. token/Basic login). Sourced from the same origin as mTLS
	// direct connection, ensuring Web sessions and certificate identity are not disconnected.
	CertIdentity *CertIdentity
	// AICJWT is set when the request authenticated via a validated AIC-JWT
	// bearer token (draft-ietf-oauth-aic). The RBAC layer intersects its
	// capabilities with route rules; nil means no AIC-JWT carrier.
	AICJWT *AICJWTIdentity
}

AuthResult is returned by Provisioner.Authenticate().

type CertIdentity

type CertIdentity struct {
	Serial       string    // Certificate serial number (%040X hex)
	Issuer       string    // Issuer DN
	CN           string    // Subject CN
	SpkiHash     string    // SHA-256(SubjectPublicKeyInfo) hex
	PrincipalUid string    // AIC PrincipalUid (empty for non-AIC certificates)
	AgentId      string    // AIC AgentId (empty for non-AIC certificates)
	NotAfter     time.Time // Certificate expiry time
}

CertIdentity is a session-bound client certificate identity snapshot for Web user detection and audit display.

func NewCertIdentityFromCert

func NewCertIdentityFromCert(cert *x509.Certificate) *CertIdentity

NewCertIdentityFromCert extracts an identity snapshot from a client certificate, populating principal/agent_id when the AIC extension is present.

type CompositeOption

type CompositeOption struct {
	Options []SignOption
}

CompositeOption applies multiple SignOptions in sequence.

func (*CompositeOption) Apply

func (o *CompositeOption) Apply(sc *ca.SignConfig) error

type KeyTypeOption

type KeyTypeOption struct {
	KeyType string
}

KeyTypeOption sets the key type for certificate issuance.

func (*KeyTypeOption) Apply

func (o *KeyTypeOption) Apply(sc *ca.SignConfig) error

type MTLSProvisioner

type MTLSProvisioner struct{}

MTLSProvisioner authenticates via mTLS client certificate. Uses the AIC extension first, then falls back to OU mapping.

func NewMTLSProvisioner

func NewMTLSProvisioner() *MTLSProvisioner

func (*MTLSProvisioner) Authenticate

func (p *MTLSProvisioner) Authenticate(r *http.Request) (*AuthResult, error)

func (*MTLSProvisioner) Name

func (p *MTLSProvisioner) Name() string

func (*MTLSProvisioner) Type

func (p *MTLSProvisioner) Type() string

type OIDCConfig

type OIDCConfig struct {
	IssuerURL    string `json:"issuer_url"`
	ClientID     string `json:"client_id"`
	JWKSEndpoint string `json:"jwks_endpoint,omitempty"` // defaults to IssuerURL + "/.well-known/jwks.json"
	ClaimMapping struct {
		Subject string `json:"subject,omitempty"` // JWT claim to use as username (default "email")
		Role    string `json:"role,omitempty"`    // JWT claim to use as role (default "sub")
	} `json:"claim_mapping,omitempty"`
	RoleOverride string `json:"role_override,omitempty"` // static role if set (e.g. "operator")
}

OIDCConfig configures the OIDC provisioner.

type OIDCProvisioner

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

OIDCProvisioner validates JWT tokens from an OIDC provider.

func NewOIDCProvisioner

func NewOIDCProvisioner(cfg OIDCConfig) *OIDCProvisioner

NewOIDCProvisioner creates an OIDC provisioner.

func (*OIDCProvisioner) Authenticate

func (p *OIDCProvisioner) Authenticate(r *http.Request) (*AuthResult, error)

func (*OIDCProvisioner) Name

func (p *OIDCProvisioner) Name() string

func (*OIDCProvisioner) Type

func (p *OIDCProvisioner) Type() string

type PrincipalAuthOption

type PrincipalAuthOption struct {
	Config ca.PrincipalAuthorizationConfig
}

PrincipalAuthOption adds PrincipalAuthorization configuration.

func (*PrincipalAuthOption) Apply

func (o *PrincipalAuthOption) Apply(sc *ca.SignConfig) error

type ProfileOption

type ProfileOption struct {
	Profile ca.Profile
}

ProfileOption sets the certificate profile and applies profile-specific config. This replaces the direct switch on sc.Profile in applyProfile().

func (*ProfileOption) Apply

func (o *ProfileOption) Apply(sc *ca.SignConfig) error

type Provisioner

type Provisioner interface {
	Name() string
	Type() string
	Authenticate(r *http.Request) (*AuthResult, error)
}

Provisioner authenticates an HTTP request and returns signing options.

type Registry

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

Registry holds all registered provisioners.

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Authenticate

func (r *Registry) Authenticate(req *http.Request) (*AuthResult, string, error)

Authenticate tries each provisioner in insertion order. Returns the first non-nil result, or nil if none match.

func (*Registry) Find

func (r *Registry) Find(name string) (Provisioner, error)

func (*Registry) Len

func (r *Registry) Len() int

func (*Registry) Names

func (r *Registry) Names() []string

func (*Registry) Register

func (r *Registry) Register(p Provisioner) error

type SANOption

type SANOption struct {
	DNSNames []string
	IPs      []string
	URIs     []string
	Emails   []string
}

SANOption adds Subject Alternative Names to the SignConfig.

func (*SANOption) Apply

func (o *SANOption) Apply(sc *ca.SignConfig) error

type SignOption

type SignOption interface {
	Apply(sc *ca.SignConfig) error
}

SignOption modifies or validates a SignConfig before signing. Inspired by step-ca's SignOption interface (CertificateModifier/Validator/Enforcer).

func SignOptionFromFunc

func SignOptionFromFunc(fn func(sc *ca.SignConfig) error) SignOption

SignOptionFromFunc wraps a function as a SignOption.

type SignOptionFunc

type SignOptionFunc func(sc *ca.SignConfig) error

SignOptionFunc is a function adapter for SignOption.

func (SignOptionFunc) Apply

func (f SignOptionFunc) Apply(sc *ca.SignConfig) error

type TokenProvisioner

type TokenProvisioner struct{}

TokenProvisioner authenticates via X-Auth-Token or Authorization header. It delegates token validation to TokenResolver (set by Server).

func NewTokenProvisioner

func NewTokenProvisioner() *TokenProvisioner

func (*TokenProvisioner) Authenticate

func (p *TokenProvisioner) Authenticate(r *http.Request) (*AuthResult, error)

func (*TokenProvisioner) Name

func (p *TokenProvisioner) Name() string

func (*TokenProvisioner) Type

func (p *TokenProvisioner) Type() string

type ValidityOption

type ValidityOption struct {
	Validity int // in hours; 0 means use default
}

ValidityOption sets the certificate validity duration.

func (*ValidityOption) Apply

func (o *ValidityOption) Apply(sc *ca.SignConfig) error

Jump to

Keyboard shortcuts

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