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
- Variables
- func CertSpkiHash(cert *x509.Certificate) string
- func PEMToCert(pemData []byte) (*x509.Certificate, error)
- func PeerCertFromRequest(r *http.Request) *x509.Certificate
- func SetAICJWTResolver(fn func(string, *http.Request) (*AuthResult, error))
- func SetTokenResolver(fn func(string) (*AuthResult, error))
- type AICJWTIdentity
- type AICJWTProvisioner
- type AICOption
- type AuthResult
- type CertIdentity
- type CompositeOption
- type KeyTypeOption
- type MTLSProvisioner
- type OIDCConfig
- type OIDCProvisioner
- type PrincipalAuthOption
- type ProfileOption
- type Provisioner
- type Registry
- type SANOption
- type SignOption
- type SignOptionFunc
- type TokenProvisioner
- type ValidityOption
Constants ¶
const ( ErrInvalidName = provisionerError("provisioner: invalid name") ErrDuplicate = provisionerError("provisioner: duplicate name") ErrNotFound = provisionerError("provisioner: not found") )
const AICJWTName = "aic-jwt"
AICJWTName is the registry name of the AIC-JWT bearer provisioner.
const MTLSName = "mtls"
MTLSName is the built-in mTLS provisioner name.
const (
// OIDCName is the built-in OIDC provisioner name.
OIDCName = "oidc"
)
const TokenName = "token"
TokenName is the built-in token provisioner name.
Variables ¶
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.
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.
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.
var TokenResolver func(token string) (*AuthResult, error)
TokenResolver resolves a token/credential to an AuthResult. Set by the Server.
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.
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 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 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 ¶
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 ¶
Authenticate tries each provisioner in insertion order. Returns the first non-nil result, or nil if none match.
func (*Registry) Register ¶
func (r *Registry) Register(p Provisioner) 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