gosesh

README

gosesh

An auth library that that abstracts away the OAuth2 flow.

⚠️ Under Development ⚠️

This library is currently under active development, and the API is subject to change.

Installation

go get github.com/rlebel12/gosesh

Usage

gosesh allows application developers to quickly add session-based authentication to their applications. This is achieved by requiring consumers to implement only their mechanisms for interfacing with their persistent data store (i.e. database) for performing CRUD operations on user data. Using that, the library can then provide a simple API for basic authentication (login, logout), guarded endpoints via middleware, automatic session refresh, and more.

See the gosesh/examples package for an example in-memory store that could be provided to gosesh.

Providers

To use the gosesh public API, you must defined OAuth2 providers via oauth2.Config objects. These objects are what tell gosesh precicesly how to authenticate with a specific provider. Examples of common providers are Google, Facebook, and GitHub. Check the documentation for a given provider to see what details they expect in the oauth2.Config object.

This library also includes gosesh/providers, which allows clients to quickly integrate with common OAuth2 providers, needing only provide their application-specific credentials.

At present, the following providers are supported:

• Discord
• Google

Documentation

Index

• Constants
• Variables
• func WithCookieDomain(fn func(*Gosesh) func() string) func(*Gosesh)
• func WithLogger(logger *slog.Logger) func(*Gosesh)
• func WithNow(fn func() time.Time) func(*Gosesh)
• func WithOAuth2StateCookieName(name string) func(*Gosesh)
• func WithOrigin(origin *url.URL) func(*Gosesh)
• func WithSessionActiveDuration(d time.Duration) func(*Gosesh)
• func WithSessionCookieName(name string) func(*Gosesh)
• func WithSessionIdleDuration(d time.Duration) func(*Gosesh)
• type CreateSessionRequest
• type Gosesh
  • func New(parser IDParser, store Storer, opts ...NewOpts) *Gosesh
  • func (gs *Gosesh) Authenticate(next http.Handler) http.Handler
  • func (gs *Gosesh) AuthenticateAndRefresh(next http.Handler) http.Handler
  • func (gs *Gosesh) CookieDomain() string
  • func (gs *Gosesh) Host() string
  • func (gs *Gosesh) Logout(done HandlerDone) http.HandlerFunc
  • func (gs *Gosesh) OAuth2Begin(oauthCfg *oauth2.Config) http.HandlerFunc
  • func (gs *Gosesh) OAuth2Callback(user OAuth2User, config *oauth2.Config, done HandlerDone) http.HandlerFunc
  • func (gs *Gosesh) RequireAuthentication(next http.Handler) http.Handler
  • func (gs *Gosesh) Scheme() string
• type HandlerDone
• type IDParser
• type Identifier
• type NewOpts
• type OAuth2Credentials
• type OAuth2User
• type Session
  • func CurrentSession(r *http.Request) (Session, bool)
• type Storer
• type UpdateSessionValues

Constants

const (
	SessionContextKey contextKey = "session"
)

Variables

var (
	ErrFailedGettingStateCookie = errors.New("failed getting state cookie")
	ErrInvalidStateCookie       = errors.New("invalid state cookie")
	ErrFailedExchangingToken    = errors.New("failed exchanging token")
	ErrFailedUnmarshallingData  = errors.New("failed unmarshalling data")
	ErrFailedUpsertingUser      = errors.New("failed upserting user")
	ErrFailedCreatingSession    = errors.New("failed creating session")
)

var (
	ErrUnauthorized          = errors.New("unauthorized")
	ErrFailedDeletingSession = errors.New("failed deleting session(s)")
)

Functions

func WithCookieDomain

func WithCookieDomain(fn func(*Gosesh) func() string) func(*Gosesh)

func WithLogger

func WithLogger(logger *slog.Logger) func(*Gosesh)

func WithNow

func WithNow(fn func() time.Time) func(*Gosesh)

Do not use: this is exported for testing-purposes only.

func WithOAuth2StateCookieName

func WithOAuth2StateCookieName(name string) func(*Gosesh)

func WithOrigin

func WithOrigin(origin *url.URL) func(*Gosesh)

func WithSessionActiveDuration

func WithSessionActiveDuration(d time.Duration) func(*Gosesh)

func WithSessionCookieName

func WithSessionCookieName(name string) func(*Gosesh)

func WithSessionIdleDuration

func WithSessionIdleDuration(d time.Duration) func(*Gosesh)

Types

type CreateSessionRequest

type CreateSessionRequest struct {
	UserID   Identifier
	IdleAt   time.Time
	ExpireAt time.Time
}

type Gosesh

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

func New

func New(parser IDParser, store Storer, opts ...NewOpts) *Gosesh

func (*Gosesh) Authenticate

func (gs *Gosesh) Authenticate(next http.Handler) http.Handler

func (*Gosesh) AuthenticateAndRefresh

func (gs *Gosesh) AuthenticateAndRefresh(next http.Handler) http.Handler

func (*Gosesh) CookieDomain

func (gs *Gosesh) CookieDomain() string

func (*Gosesh) Host

func (gs *Gosesh) Host() string

func (*Gosesh) Logout

func (gs *Gosesh) Logout(done HandlerDone) http.HandlerFunc

func (*Gosesh) OAuth2Begin

func (gs *Gosesh) OAuth2Begin(oauthCfg *oauth2.Config) http.HandlerFunc

func (*Gosesh) OAuth2Callback

func (gs *Gosesh) OAuth2Callback(user OAuth2User, config *oauth2.Config, done HandlerDone) http.HandlerFunc

Create a handler for the OAuth2 callback. This handler performs the token exchange and retrieves user data from the provider. When the OAuth2 flow has completed, the input `done` will be invoked, with the error value set to nil if the flow was successful, or an error if it was not.

func (*Gosesh) RequireAuthentication

func (gs *Gosesh) RequireAuthentication(next http.Handler) http.Handler

func (*Gosesh) Scheme

func (gs *Gosesh) Scheme() string

type HandlerDone

type HandlerDone func(http.ResponseWriter, *http.Request, error)

type IDParser

type IDParser func([]byte) (Identifier, error)

type Identifier

type Identifier interface {
	fmt.Stringer
}

type NewOpts

type NewOpts func(*Gosesh)

type OAuth2Credentials

type OAuth2Credentials interface {
	ClientID() string
	ClientSecret() string
}

type OAuth2User

type OAuth2User interface {
	Identifier // Uniquely identifies the user within the OAuth2 provider's system.
	Request(ctx context.Context, accessToken string) (*http.Response, error)
	Unmarshal(b []byte) error
}

Represents a user presented by an OAuth2 provider. Note that this is separate from a user as persisted in your system.

type Session

type Session interface {
	ID() Identifier
	UserID() Identifier
	IdleAt() time.Time
	ExpireAt() time.Time
}

func CurrentSession

func CurrentSession(r *http.Request) (Session, bool)

type Storer

type Storer interface {
	UpsertUser(ctx context.Context, user OAuth2User) (Identifier, error)
	CreateSession(ctx context.Context, req CreateSessionRequest) (Session, error)
	GetSession(ctx context.Context, sessionID Identifier) (Session, error)
	UpdateSession(ctx context.Context, sessionID Identifier, req UpdateSessionValues) (Session, error)
	DeleteSession(ctx context.Context, sessionID Identifier) error
	DeleteUserSessions(ctx context.Context, userID Identifier) (int, error)
}

type UpdateSessionValues

type UpdateSessionValues struct {
	IdleAt   time.Time
	ExpireAt time.Time
}