authenticator

package
v0.3.1 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package authenticator provides a modular plugin interface for providing authentication mechanisms to the caddy-oidc plugin. Including a built-in set of authenticators for working with most authentication sources from HTTP requests.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidAuthMethod = errors.New("not a valid AuthMethod")
View Source 
var ErrInvalidSameSite = errors.New("not a valid SameSite")
View Source 
var ErrNoAuthentication = errors.New("no valid authentication credentials provided")

ErrNoAuthentication is returned when no valid authentication could be found in the request.

View Source 
var ErrNoIDToken = errors.New("authentication server did not return an ID token")

ErrNoIDToken is returned when an OAuth2 code exchange response does not contain an ID token.

Functions

func GetAuthenticator 

func GetAuthenticator[T RequestAuthenticator](set *Set) (T, bool)

GetAuthenticator returns the first RequestAuthenticator in the set equal to the requested type.

Types

type AuthMethod 

type AuthMethod string

AuthMethod represents one of the supported authentication methods. ENUM(none, bearer, cookie, header, query) 

const (
	// AuthMethodNone is a AuthMethod of type none.
	AuthMethodNone AuthMethod = "none"
	// AuthMethodBearer is a AuthMethod of type bearer.
	AuthMethodBearer AuthMethod = "bearer"
	// AuthMethodCookie is a AuthMethod of type cookie.
	AuthMethodCookie AuthMethod = "cookie"
	// AuthMethodHeader is a AuthMethod of type header.
	AuthMethodHeader AuthMethod = "header"
	// AuthMethodQuery is a AuthMethod of type query.
	AuthMethodQuery AuthMethod = "query"
)

func ParseAuthMethod 

func ParseAuthMethod(name string) (AuthMethod, error)

ParseAuthMethod attempts to convert a string to a AuthMethod.

func (*AuthMethod) AppendText 

func (x *AuthMethod) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (AuthMethod) IsValid 

func (x AuthMethod) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (AuthMethod) MarshalText 

func (x AuthMethod) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (AuthMethod) String 

func (x AuthMethod) String() string

String implements the Stringer interface.

func (*AuthMethod) UnmarshalText 

func (x *AuthMethod) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type BearerAuthenticator 

type BearerAuthenticator struct {
}

BearerAuthenticator authenticates the request from a JWT found in the "Authorization" header.

func (*BearerAuthenticator) AuthenticateRequest 

func (*BearerAuthenticator) AuthenticateRequest(cfg OIDCConfiguration, r *http.Request) (*session.Session, error)

func (*BearerAuthenticator) CaddyModule 

func (*BearerAuthenticator) CaddyModule() caddy.ModuleInfo

func (*BearerAuthenticator) Method 

func (*BearerAuthenticator) Method() AuthMethod

func (*BearerAuthenticator) StripRequest 

func (*BearerAuthenticator) StripRequest(r *http.Request)

func (*BearerAuthenticator) UnmarshalCaddyfile 

func (*BearerAuthenticator) UnmarshalCaddyfile(_ *caddyfile.Dispenser) error

type CSRFToken 

type CSRFToken struct {
	PKCEVerifier string `json:"v"`
	RedirectURI  string `json:"r"`
}

CSRFToken is the CSRF cookie payload when perform an OAuth2 Authorization Flow.

type HeaderAuthenticator 

type HeaderAuthenticator struct {
	Header string `json:"header,omitempty"`
}

HeaderAuthenticator authenticates a request from a JWT found in a named HTTP request header.

func (*HeaderAuthenticator) AuthenticateRequest 

func (au *HeaderAuthenticator) AuthenticateRequest(cfg OIDCConfiguration, r *http.Request) (*session.Session, error)

func (*HeaderAuthenticator) CaddyModule 

func (*HeaderAuthenticator) CaddyModule() caddy.ModuleInfo

func (*HeaderAuthenticator) Method 

func (*HeaderAuthenticator) Method() AuthMethod

func (*HeaderAuthenticator) StripRequest 

func (au *HeaderAuthenticator) StripRequest(r *http.Request)

func (*HeaderAuthenticator) UnmarshalCaddyfile 

func (au *HeaderAuthenticator) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (*HeaderAuthenticator) Validate 

func (au *HeaderAuthenticator) Validate() error

type OAuthAuthorizationFlowConfiguration 

type OAuthAuthorizationFlowConfiguration interface {
	OIDCConfiguration

	AuthCodeURL(ctx context.Context, state string, opts ...oauth2.AuthCodeOption) (string, error)
	Exchange(ctx context.Context, code string, opts ...oauth2.AuthCodeOption) (*oauth2.Token, error)
	UserInfo(ctx context.Context, tokenSource oauth2.TokenSource) (*oidc.UserInfo, error)
}

OAuthAuthorizationFlowConfiguration represents the configuration required to implement an OAuth2 Authorization Code Flow.

type OIDCConfiguration 

type OIDCConfiguration interface {
	// Now returns the current time according to the OIDC configuration clock.
	Now() time.Time
	// GetVerifier returns the ID token verifier configured for the OIDC provider.
	GetVerifier(ctx context.Context) (*oidc.IDTokenVerifier, error)
	// GetUsernameClaim returns the claim name used to extract the username from the ID token.
	GetUsernameClaim() string
}

OIDCConfiguration represents the configuration required to authenticate incoming requests using configuration from an OIDC provider.

type QueryAuthenticator 

type QueryAuthenticator struct {
	Query string `json:"query,omitempty"`
}

QueryAuthenticator authenticates a request from a JWT found in an HTTP query parameter.

func (*QueryAuthenticator) AuthenticateRequest 

func (au *QueryAuthenticator) AuthenticateRequest(cfg OIDCConfiguration, r *http.Request) (*session.Session, error)

func (*QueryAuthenticator) CaddyModule 

func (*QueryAuthenticator) CaddyModule() caddy.ModuleInfo

func (*QueryAuthenticator) Method 

func (*QueryAuthenticator) Method() AuthMethod

func (*QueryAuthenticator) StripRequest 

func (au *QueryAuthenticator) StripRequest(r *http.Request)

func (*QueryAuthenticator) UnmarshalCaddyfile 

func (au *QueryAuthenticator) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (*QueryAuthenticator) Validate 

func (au *QueryAuthenticator) Validate() error

type RequestAuthenticator 

type RequestAuthenticator interface {
	// Method returns the authentication method type provided by this RequestAuthenticator
	Method() AuthMethod

	// AuthenticateRequest extracts authentication session information from the incoming request.
	// If the request does not contain valid authentication, then it must return ErrNoAuthentication.
	AuthenticateRequest(cfg OIDCConfiguration, r *http.Request) (*session.Session, error)

	// StripRequest removes any authentication information from the request.
	StripRequest(r *http.Request)
}

A RequestAuthenticator extracts authentication information from an incoming request.

type SameSite 

type SameSite string

SameSite represents the same site attribute of a cookie. ENUM(lax, strict, none, default = "") 

const (
	// SameSiteLax is a SameSite of type lax.
	SameSiteLax SameSite = "lax"
	// SameSiteStrict is a SameSite of type strict.
	SameSiteStrict SameSite = "strict"
	// SameSiteNone is a SameSite of type none.
	SameSiteNone SameSite = "none"
	// SameSiteDefault is a SameSite of type default.
	SameSiteDefault SameSite = ""
)

func ParseSameSite 

func ParseSameSite(name string) (SameSite, error)

ParseSameSite attempts to convert a string to a SameSite.

func (*SameSite) AppendText 

func (x *SameSite) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (SameSite) HTTPSameSite 

func (ss SameSite) HTTPSameSite() http.SameSite

func (SameSite) IsValid 

func (x SameSite) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (SameSite) MarshalText 

func (x SameSite) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (SameSite) String 

func (x SameSite) String() string

String implements the Stringer interface.

func (*SameSite) UnmarshalText 

func (x *SameSite) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type SessionCookieAuthenticator 

type SessionCookieAuthenticator struct {
	Name        string   `json:"name,omitempty"`
	SameSite    SameSite `json:"same_site,omitempty"`
	Insecure    bool     `json:"insecure,omitempty"`
	Domain      string   `json:"domain,omitempty"`
	Path        string   `json:"path,omitempty"`
	Secret      string   `json:"secret,omitempty"`
	Claims      []string `json:"claims,omitempty"`
	RedirectURL string   `json:"redirect_url,omitempty"`
	// contains filtered or unexported fields
}

SessionCookieAuthenticator authenticates the request from a signed cookie.

func (*SessionCookieAuthenticator) AuthenticateRequest 

func (au *SessionCookieAuthenticator) AuthenticateRequest(cfg OIDCConfiguration, r *http.Request) (*session.Session, error)

func (*SessionCookieAuthenticator) CaddyModule 

func (*SessionCookieAuthenticator) CaddyModule() caddy.ModuleInfo

func (*SessionCookieAuthenticator) GetAbsRedirectURI 

func (au *SessionCookieAuthenticator) GetAbsRedirectURI(r *http.Request) *url.URL

GetAbsRedirectURI returns the absolute redirect URI, resolving it relative to the request URL if necessary.

func (*SessionCookieAuthenticator) HandleCallback 

func (au *SessionCookieAuthenticator) HandleCallback(cfg OAuthAuthorizationFlowConfiguration, rw http.ResponseWriter, r *http.Request) error

HandleCallback handles the callback from the authorization endpoint.

func (*SessionCookieAuthenticator) IsCallbackURL 

func (au *SessionCookieAuthenticator) IsCallbackURL(r *http.Request) bool

IsCallbackURL returns true if the request is a callback from the authorization endpoint. Determined if the absolute form of the redirect URI relative to the current request matches the scheme, host, and path of the current request.

func (*SessionCookieAuthenticator) Method 

func (*SessionCookieAuthenticator) Method() AuthMethod

func (*SessionCookieAuthenticator) NewCookie 

func (au *SessionCookieAuthenticator) NewCookie(value string) *http.Cookie

func (*SessionCookieAuthenticator) Provision 

func (au *SessionCookieAuthenticator) Provision(_ caddy.Context) error

func (*SessionCookieAuthenticator) StartLogin 

func (au *SessionCookieAuthenticator) StartLogin(cfg OAuthAuthorizationFlowConfiguration, rw http.ResponseWriter, r *http.Request) error

StartLogin starts the authorization flow by setting the state cookie and redirecting to the authorization endpoint. The state cookie is in the format of `<cookie_name>|<state>`, with the value containing the PKCE code verifier. The OAuth2 redirect URI is set to the configured redirect URI made absolute relative to the request URL.

func (*SessionCookieAuthenticator) StripRequest 

func (au *SessionCookieAuthenticator) StripRequest(r *http.Request)

func (*SessionCookieAuthenticator) UnmarshalCaddyfile 

func (au *SessionCookieAuthenticator) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (*SessionCookieAuthenticator) Validate 

func (au *SessionCookieAuthenticator) Validate() error

type Set 

type Set struct {
	AuthenticatorsRaw []json.RawMessage      `caddy:"namespace=http.oidc.authenticators inline_key=authenticator" json:"authenticators"`
	Authenticators    []RequestAuthenticator `json:"-"`
	PreserveRequest   bool                   `json:"preserve_request,omitzero"`
	Required          bool                   `json:"required,omitempty"`
}

Set contains an ordered list of RequestAuthenticator implementations.

func (*Set) AuthenticateRequest 

func (set *Set) AuthenticateRequest(cfg OIDCConfiguration, r *http.Request) (AuthMethod, *session.Session, error)

AuthenticateRequest attempts to authenticate the request using the configured authenticators. It returns the first successful authentication method and session.

Any ErrNoAuthentication or oidc.TokenExpiredError errors are ignored, and the next authenticator in sequence is tried. If no authenticators succeed and Required is set, then ErrNoAuthentication is returned. Otherwise, an anonymous session is returned.

func (*Set) Provision 

func (set *Set) Provision(ctx caddy.Context) error

func (*Set) StripRequest 

func (set *Set) StripRequest(r *http.Request)

StripRequest removes any authentication information from the request. If PreserveRequest is set, then this method does nothing.

func (*Set) UnmarshalCaddyfile 

func (set *Set) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (*Set) Validate 

func (set *Set) Validate() error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.