webstd

Documentation

Overview

Package webstd contains common functions for setting up web apps at Fensak.

Index

• func GetBearerToken(r *http.Request) string
• func GetOIDCURLParams() []string
• func NewNosurfHandler(cfg *CSRF) func(h http.Handler) http.Handler
• func RunWithSignalHandler(app *App) (returnErr error)
• func SetSessionSettings(logger *zap.Logger, sessMgr *scs.SessionManager, cfg *Session)
• type App
• type AppContextKey
  • func NewAppContextKey(app, name string) *AppContextKey
  • func (k *AppContextKey) String() string
• type Authenticator
  • func NewAuthenticator(ctx context.Context, cfg *OIDCProvider) (*Authenticator, error)
  • func (a Authenticator) LogoutURL() string
  • func (a Authenticator) NewCodeVerifier() (PKCECodeVerifier, error)
  • func (a Authenticator) RefreshIDToken(ctx context.Context, refreshToken string) (string, *oidc.IDToken, *oauth2.Token, error)
  • func (a Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error)
  • func (a Authenticator) VerifyIDTokenStr(ctx context.Context, tokenStr string) (*oidc.IDToken, error)
  • func (a Authenticator) VerifyRawToken(ctx context.Context, rawToken string) (*oidc.IDToken, error)
• type CSRF
• type IdP
• type IdPProvider
• type IdPZitadel
• type OIDCProvider
• type PKCECodeVerifier
• type Session

Functions

func GetBearerToken

func GetBearerToken(r *http.Request) string

GetBearerToken retrieves the bearer token from the Authorization header of an http request.

func GetOIDCURLParams

func GetOIDCURLParams() []string

GetOIDCURLParams returns a list of sensitive URL params in the OIDC flow. This is useful for sanitizing these entries in the request logger.

func NewNosurfHandler

func NewNosurfHandler(cfg *CSRF) func(h http.Handler) http.Handler

NewNosurfHandler returns a nosurf handler function that can be used as a http middleware. The nosurf handler will take care to ensure that a valid CSRF token is provided in every PUT, POST, DELETE request.

func RunWithSignalHandler

func RunWithSignalHandler(app *App) (returnErr error)

RunWithSignalHandler runs the http web app described by the App struct in the background, and implements a signal handler in the foreground that traps the INT and TERM signals. When the INT or TERM signal is sent to the process, this will start a graceful shutdown of the http server, waiting up to ShutdownTimeout duration for all http server threads to stop processing.

func SetSessionSettings

func SetSessionSettings(
	logger *zap.Logger, sessMgr *scs.SessionManager, cfg *Session,
)

SetSessionSettings configures the session manager based on the provided session configuration.

Types

type App

type App struct {
	Handler         http.Handler
	Logger          *zap.SugaredLogger
	Port            int
	ShutdownTimeout time.Duration

	// Any addiitonal close routine should be handled in the custom close function passed in here.
	CloseFn func() error
}

type AppContextKey

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

AppContextKey is a value for use with context.WithValue. This should be used to define context keys that are specific to the app component.

NOTE: It's used as a pointer so it fits in an interface{} without allocation. This technique for defining context keys was copied from Go 1.7's new use of context in net/http.

func NewAppContextKey

func NewAppContextKey(app, name string) *AppContextKey

func (*AppContextKey) String

func (k *AppContextKey) String() string

type Authenticator

type Authenticator struct {
	*oidc.Provider
	oauth2.Config
	WithPKCE          bool
	RawTokenClientIDs []string
}

Authenticator is used to authenticate our users.

func NewAuthenticator

func NewAuthenticator(ctx context.Context, cfg *OIDCProvider) (*Authenticator, error)

NewAuthenticator instantiates the Authenticator object using the provided configuration options.

func (Authenticator) LogoutURL

func (a Authenticator) LogoutURL() string

LogoutURL returns the logout URL to end the session, if it exists. Note that there is no OIDC standard for RP initiated logout. As such, there is no guarantee that this will always return a valid logout URL. For IdPs where we can not determine a valid logout URL, this will return an empty string. NOTE: for now, we only support the `end_session_endpoint` claim, which is used by Azure AD B2C.

func (Authenticator) NewCodeVerifier

func (a Authenticator) NewCodeVerifier() (PKCECodeVerifier, error)

NewCodeVerifier creates cryptographically secure code verification string for the PKCE flow.

func (Authenticator) RefreshIDToken

func (a Authenticator) RefreshIDToken(ctx context.Context, refreshToken string) (string, *oidc.IDToken, *oauth2.Token, error)

RefreshIDToken obtains a new OIDC ID token using the provided refresh token.

func (Authenticator) VerifyIDToken

func (a Authenticator) VerifyIDToken(ctx context.Context, token *oauth2.Token) (*oidc.IDToken, error)

VerifyIDToken verifies that an *oauth2.Token is a valid *oidc.IDToken.

func (Authenticator) VerifyIDTokenStr

func (a Authenticator) VerifyIDTokenStr(ctx context.Context, tokenStr string) (*oidc.IDToken, error)

VerifyIDTokenStr parses and verifies that the given string is a valid ID token.

func (Authenticator) VerifyRawToken

func (a Authenticator) VerifyRawToken(ctx context.Context, rawToken string) (*oidc.IDToken, error)

VerifyRawToken verifies a given raw JWT token string issued by the OIDC provider. This is useful for verifying tokens that are provided through APIs.

type CSRF

type CSRF struct {
	MaxAge int `mapstructure:"maxage"`

	// Dev determines whether to use dev mode for CSRF validation. When true, disables the secure flag on the CSRF cookie.
	Dev bool `mapstructure:"dev"`
}

CSRF represents configuration options for CSRF protection. This can be embedded in a viper compatible config struct.

type IdP

type IdP struct {
	// Provider represents one of the supported identity providers.
	Provider IdPProvider `mapstructure:"provider"`

	Zitadel *IdPZitadel `mapstructure:"zitadel"`
}

IdP represents configuration options for interacting with the Identity Provider that handles authentication for the web app. This can be embedded in a viper compatible config struct.

type IdPProvider

type IdPProvider string

IdPProvider is an enum describing the possible options for the IdP.Provider setting.

const (
	IdPProviderZitadel IdPProvider = "zitadel"
	IdPProviderNopIdP  IdPProvider = "nopidp"
)

type IdPZitadel

type IdPZitadel struct {
	// The name of the Zitadel instance. Only used if the provider is set to zitadel.
	InstanceName string `mapstructure:"instance_name"`

	// The base64 encoded value of the JWT key to use for authentication. Only used if the provider is set to zitadel.
	JWTKeyBase64 string `mapstructure:"jwt_key_base64"`
}

type OIDCProvider

type OIDCProvider struct {
	// IssuerURL is the full URL (including scheme and path) of the OIDC provider issuer.
	IssuerURL string `mapstructure:"issuer_url"`

	// ClientID is the oauth2 application client ID to use for the OIDC protocol.
	ClientID string `mapstructure:"clientid"`

	// ClientSecret is the oauth2 application client secret to use for the OIDC protocol.
	ClientSecret string `mapstructure:"secret"`

	// RawTokenClientIDs is the list of potential client IDs to expect raw JWT tokens to be provided from.
	RawTokenClientIDs []string `mapstructure:"raw_token_clientids"`

	// WithPKCE determines whether PKCE should be used for the code exchange.
	// See https://www.oauth.com/oauth2-servers/pkce/ for more info.
	WithPKCE bool `mapstructure:"with_pkce"`

	// SkipIssuerVerification determines whether the issuer URL should be verified against the discovery base URL. This
	// should ONLY be set to true for OIDC providers that are off-spec, such as Azure where the discovery URL
	// (/.well-known/openid-configuration) is different from the issuer URL. When true, the discovery URL must be
	// provided under the DiscoveryURL config.
	SkipIssuerVerification bool `mapstructure:"skip_iss_verification"`

	// DiscoveryURL is the full base URL of the discovery page for OIDC. The authenticator will look for the OIDC
	// configuration under the page DISCOVERY_URL/.well-known/openid-configuration. Only used if SkipIssuerVerification is
	// true; when SkipIssuerVerification is false, the IssuerURL will be used instead.
	DiscoveryURL string `mapstructure:"discovery_url"`

	// AdditionalScopes is the list of Oauth2 scopes to request for the OIDC token. Note that the library will always
	// request the required "openid" scope.
	AdditionalScopes []string `mapstructure:"additional_scopes"`

	// CallbackURL is the full URL (including scheme) of the endpoint that handles the access token returned from the OIDC
	// protocol. This should be automatically configured by the application instead of being configured in the config
	// chain.
	CallbackURL string
}

OIDCProvider represents configuration options for the OIDC Provider that handles authentication for the web app. This can be embedded in a viper compatible config struct.

type PKCECodeVerifier

type PKCECodeVerifier struct {
	Verifier  string
	Challenge string
}

PKCECodeVerifier captures the code verifier string, as well as the hashed string that can be used as the code challenge for the PKCE flow.

type Session

type Session struct {
	// Lifetime indicates how long a session is valid for.
	Lifetime time.Duration `mapstructure:"lifetime"`

	// CookieName is the name of the cookie to use to store the session ID on the client side.
	CookieName string `mapstructure:"cookie_name"`

	// CookieSecure determines whether the secure flag should be set on the cookie.
	CookieSecure bool `mapstructure:"cookie_secure"`

	// CookieSameSiteStr is the string representation of the samesite mode to set on the session cookie.
	CookieSameSiteStr string `mapstructure:"cookie_samesite"`
}

Session represents configuration options for the Session object and cookie. This can be embedded in a viper compatible config struct.