jawsauth

README

jawsauth

OIDC-verified authentication for JaWS sessions.

• Requires an OIDC-compliant provider.
• Uses OIDC discovery from the configured issuer.
• Verifies id_token and stores identity claims in session data.

Documentation

Index

• Variables
• func DefaultSetHeaders(hw http.ResponseWriter, ishttps bool)
• type Config
  • func (cfg *Config) Validate() (err error)
• type EventFunc
• type FailedFunc
• type HandleFunc
• type JawsAuth
  • func (a *JawsAuth) Data() (x map[string]any)
  • func (a *JawsAuth) Email() (s string)
  • func (a *JawsAuth) EmailVerified() (yes bool)
  • func (a *JawsAuth) IsAdmin() (yes bool)
• type OAuth2CallbackError
  • func (err *OAuth2CallbackError) Error() string
  • func (err *OAuth2CallbackError) Is(target error) bool
• type Server
  • func New(jw *jaws.Jaws, cfg *Config, handleFn HandleFunc) (srv *Server, err error)
  • func NewDebug(jw *jaws.Jaws, cfg *Config, handleFn HandleFunc, overrideUrl string) (srv *Server, err error)
  • func (srv *Server) GetAdmins() (emails []string)
  • func (srv *Server) HandleAuthResponse(hw http.ResponseWriter, hr *http.Request)
  • func (srv *Server) HandleLogin(hw http.ResponseWriter, hr *http.Request)
  • func (srv *Server) HandleLogout(hw http.ResponseWriter, hr *http.Request)
  • func (srv *Server) Handler(name string, dot any) http.Handler
  • func (srv *Server) HandlerAdmin(name string, dot any) http.Handler
  • func (srv *Server) IsAdmin(email string) (yes bool)
  • func (srv *Server) Set403Handler(h http.Handler)
  • func (srv *Server) SetAdmins(emails []string)
  • func (srv *Server) Valid() bool
  • func (srv *Server) Wrap(h http.Handler) (rh http.Handler)
  • func (srv *Server) WrapAdmin(h http.Handler) (rh http.Handler)

Variables

var ErrConfig errConfig

ErrConfig matches all configuration validation errors.

var ErrConfigIssuerMustBeHTTPS = errors.New("issuer url must use https")

ErrConfigIssuerMustBeHTTPS means Issuer must use the https scheme unless AllowInsecureIssuer is enabled.

var ErrConfigMissingValue = errors.New("config value is missing")

ErrConfigMissingValue means a required configuration value is missing.

var ErrConfigURLMissingHost = errors.New("url host is missing")

ErrConfigURLMissingHost means a configured URL does not include a host.

var ErrConfigURLNotAbsolute = errors.New("url is not absolute")

ErrConfigURLNotAbsolute means a configured URL is not absolute.

var ErrOAuth2Callback = errors.New("oauth2 callback error")

ErrOAuth2Callback matches OAuth2 callback errors returned by the identity provider.

var ErrOAuth2MissingPKCEVerifier = errors.New("oauth2 missing pkce verifier")

ErrOAuth2MissingPKCEVerifier means the callback session did not contain the required PKCE verifier.

var ErrOAuth2MissingSession = errors.New("oauth2 missing session")

var ErrOAuth2MissingState = errors.New("oauth2 missing state")

var ErrOAuth2NotConfigured = errors.New("oauth2 not configured")

var ErrOAuth2WrongState = errors.New("oauth2 wrong state")

var ErrOIDCDiscovery = errors.New("oidc discovery failed")

ErrOIDCDiscovery means OIDC provider discovery failed.

var ErrOIDCInvalidIDToken = errors.New("oidc invalid id_token")

ErrOIDCInvalidIDToken means id_token verification failed.

var ErrOIDCMissingIDToken = errors.New("oidc missing id_token")

ErrOIDCMissingIDToken means the token response did not include an id_token.

var ErrOIDCMissingNonce = errors.New("oidc missing nonce")

ErrOIDCMissingNonce means the login request did not include a nonce.

var ErrOIDCNonceMismatch = errors.New("oidc nonce mismatch")

ErrOIDCNonceMismatch means the id_token nonce did not match the stored session nonce.

var ErrOIDCProviderMetadata = errors.New("oidc provider metadata invalid")

ErrOIDCProviderMetadata means discovered OIDC metadata was invalid.

var SetHeaders = DefaultSetHeaders

SetHeaders is called to write HTTP headers for all OAuth endpoint responses

Functions

func DefaultSetHeaders

func DefaultSetHeaders(hw http.ResponseWriter, ishttps bool)

DefaultSetHeaders writes response headers for OAuth endpoint responses.

Types

type Config

type Config struct {
	RedirectURL string // required. e.g. "https://application.example.com/oauth2/callback"
	Issuer      string // required. e.g. "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/v2.0"
	AuthURL     string // optional override for discovered authorization_endpoint
	TokenURL    string // optional override for discovered token_endpoint
	UserInfoURL string // optional override for discovered userinfo_endpoint
	// AllowInsecureIssuer permits "http://" Issuer URLs and should only be used for tests/dev.
	AllowInsecureIssuer bool
	// HTTPClient is used for OIDC discovery at startup.
	HTTPClient *http.Client
	Scopes     []string // optional additional scopes, "openid" and "email" are always ensured
	ClientID   string
	//gosec:disable G117
	ClientSecret string
}

func (*Config) Validate

func (cfg *Config) Validate() (err error)

type EventFunc

type EventFunc func(sess *jaws.Session, hr *http.Request)

type FailedFunc

type FailedFunc func(hw http.ResponseWriter, hr *http.Request, httpCode int, err error, email string) (wroteresponse bool)

type HandleFunc

type HandleFunc func(uri string, handler http.Handler)

type JawsAuth

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

func (*JawsAuth) Data

func (a *JawsAuth) Data() (x map[string]any)

func (*JawsAuth) Email

func (a *JawsAuth) Email() (s string)

func (*JawsAuth) EmailVerified

func (a *JawsAuth) EmailVerified() (yes bool)

func (*JawsAuth) IsAdmin

func (a *JawsAuth) IsAdmin() (yes bool)

type OAuth2CallbackError

type OAuth2CallbackError struct {
	Code        string // OAuth2 error code from the callback.
	Description string // Optional error description from the callback.
	URI         string // Optional URI with details about the callback error.
}

OAuth2CallbackError describes an OAuth2 callback error response.

func (*OAuth2CallbackError) Error

func (err *OAuth2CallbackError) Error() string

func (*OAuth2CallbackError) Is

func (err *OAuth2CallbackError) Is(target error) bool

type Server

type Server struct {
	Jaws *jaws.Jaws
	//gosec:disable G117
	SessionKey              string                  // default is "oidc_claims", value will be of type map[string]any // #nosec G117
	SessionTokenKey         string                  // default is "oauth2_tokensource", value will be of type oauth2.TokenSource
	SessionEmailKey         string                  // default is "email", value will be of type string
	SessionEmailVerifiedKey string                  // default is "email_verified", value will be of type bool
	HandledPaths            map[string]struct{}     // URI paths we have registered handlers for
	LoginEvent              EventFunc               // if not nil, called after a successful login
	LogoutEvent             EventFunc               // if not nil, called before logout
	LoginFailed             FailedFunc              // if not nil, called on failed login
	Options                 []oauth2.AuthCodeOption // options to use, see https://pkg.go.dev/golang.org/x/oauth2#AuthCodeOption
	// contains filtered or unexported fields
}

func New

func New(jw *jaws.Jaws, cfg *Config, handleFn HandleFunc) (srv *Server, err error)

func NewDebug

func NewDebug(jw *jaws.Jaws, cfg *Config, handleFn HandleFunc, overrideUrl string) (srv *Server, err error)

func (*Server) GetAdmins

func (srv *Server) GetAdmins() (emails []string)

GetAdmins returns a sorted list of the administrator emails. If empty, everyone is considered an administrator.

func (*Server) HandleAuthResponse

func (srv *Server) HandleAuthResponse(hw http.ResponseWriter, hr *http.Request)

func (*Server) HandleLogin

func (srv *Server) HandleLogin(hw http.ResponseWriter, hr *http.Request)

func (*Server) HandleLogout

func (srv *Server) HandleLogout(hw http.ResponseWriter, hr *http.Request)

func (*Server) Handler

func (srv *Server) Handler(name string, dot any) http.Handler

Handler returns a http.Handler using a jaws.Template that requires an authenticated user. Sets the jaws Session value srv.SessionKey to verified id_token claims, with optional fallback values from UserInfo.

func (*Server) HandlerAdmin

func (srv *Server) HandlerAdmin(name string, dot any) http.Handler

HandlerAdmin returns a http.Handler using a jaws.Template that requires an authenticated user having an email set using SetAdmins() before invoking h. Sets the jaws Session value srv.SessionKey to verified id_token claims, with optional fallback values from UserInfo.

func (*Server) IsAdmin

func (srv *Server) IsAdmin(email string) (yes bool)

IsAdmin returns true if email belongs to an admin or if the list of admins is empty or the server is not valod.

func (*Server) Set403Handler

func (srv *Server) Set403Handler(h http.Handler)

func (*Server) SetAdmins

func (srv *Server) SetAdmins(emails []string)

SetAdmins sets the emails of administrators. If empty, everyone is considered an administrator.

func (*Server) Valid

func (srv *Server) Valid() bool

Valid returns true if OIDC authentication is configured.

func (*Server) Wrap

func (srv *Server) Wrap(h http.Handler) (rh http.Handler)

Wrap returns a http.Handler that requires an authenticated user before invoking h. Sets the jaws Session value srv.SessionKey to verified id_token claims, with optional fallback values from UserInfo. If the Server is not Valid, returns h.

func (*Server) WrapAdmin

func (srv *Server) WrapAdmin(h http.Handler) (rh http.Handler)

WrapAdmin returns a http.Handler that requires an authenticated user having an email set using SetAdmins() before invoking h. Sets the jaws Session value srv.SessionKey to verified id_token claims, with optional fallback values from UserInfo. If the Server is not Valid, returns h.