sessions

Documentation

Overview

Package sessions handles the storage, management, and validation of pomerium user sessions.

Index

• Variables
• func FromContext(ctx context.Context) (string, error)
• func NewContext(ctx context.Context, jwt string, err error) context.Context
• func RetrieveSession(s ...SessionLoader) func(http.Handler) http.Handler
• type SessionLoader
• type SessionStore
• type State
  • func NewSession(s *State, issuer string, audience []string) State
  • func (s *State) IsExpired() bool
  • func (s *State) UnmarshalJSON(data []byte) error
  • func (s *State) UserID(provider string) string
• type Version
  • func (v *Version) String() string
  • func (v *Version) UnmarshalJSON(b []byte) error

Variables

var (
	// ErrNoSessionFound is the error for when no session is found.
	ErrNoSessionFound = errors.New("internal/sessions: session is not found")

	// ErrMalformed is the error for when a session is found but is malformed.
	ErrMalformed = errors.New("internal/sessions: session is malformed")

	// ErrNotValidYet indicates that token is used before time indicated in nbf claim.
	ErrNotValidYet = errors.New("internal/sessions: validation failed, token not valid yet (nbf)")

	// ErrExpired indicates that token is used after expiry time indicated in exp claim.
	ErrExpired = errors.New("internal/sessions: validation failed, token is expired (exp)")

	// ErrExpiryRequired indicates that the token does not contain a valid expiry (exp) claim.
	ErrExpiryRequired = errors.New("internal/sessions: validation failed, token expiry (exp) is required")

	// ErrIssuedInTheFuture indicates that the iat field is in the future.
	ErrIssuedInTheFuture = errors.New("internal/sessions: validation field, token issued in the future (iat)")

	// ErrInvalidAudience indicated invalid aud claim.
	ErrInvalidAudience = errors.New("internal/sessions: validation failed, invalid audience claim (aud)")
)

var (
	SessionCtxKey = &contextKey{"Session"}
	ErrorCtxKey   = &contextKey{"Error"}
)

Context keys

var ErrMissingID = errors.New("invalid session: missing id")

ErrMissingID is the error for a session state that has no ID set.

Functions

func FromContext

func FromContext(ctx context.Context) (string, error)

FromContext retrieves context values for the user session state and error.

func NewContext

func NewContext(ctx context.Context, jwt string, err error) context.Context

NewContext sets context values for the user session state and error.

func RetrieveSession

func RetrieveSession(s ...SessionLoader) func(http.Handler) http.Handler

RetrieveSession takes a slice of session loaders and tries to find a valid session in the order they were supplied and is added to the request's context

Types

type SessionLoader

type SessionLoader interface {
	LoadSession(*http.Request) (string, error)
}

SessionLoader defines an interface for loading a session.

type SessionStore

type SessionStore interface {
	SessionLoader
	ClearSession(http.ResponseWriter, *http.Request)
	SaveSession(http.ResponseWriter, *http.Request, interface{}) error
}

SessionStore defines an interface for loading, saving, and clearing a session.

type State

type State struct {
	// Public claim values (as specified in RFC 7519).
	Issuer    string           `json:"iss,omitempty"`
	Subject   string           `json:"sub,omitempty"`
	Audience  jwt.Audience     `json:"aud,omitempty"`
	Expiry    *jwt.NumericDate `json:"exp,omitempty"`
	NotBefore *jwt.NumericDate `json:"nbf,omitempty"`
	IssuedAt  *jwt.NumericDate `json:"iat,omitempty"`
	ID        string           `json:"jti,omitempty"`

	// "ver" field is not standard, but is supported by most providers.
	Version Version `json:"ver,omitempty"`

	// Azure returns OID which should be used instead of subject.
	OID string `json:"oid,omitempty"`

	// Programmatic whether this state is used for machine-to-machine
	// programmatic access.
	Programmatic bool `json:"programmatic"`

	// DatabrokerServerVersion tracks the last referenced databroker server version
	// for the saved session.
	DatabrokerServerVersion uint64 `json:"databroker_server_version,omitempty"`
	// DatabrokerRecordVersion tracks the last referenced databroker record version
	// for the saved session.
	DatabrokerRecordVersion uint64 `json:"databroker_record_version,omitempty"`
}

State is our object that keeps track of a user's session state

func NewSession

func NewSession(s *State, issuer string, audience []string) State

NewSession updates issuer, audience, and issuance timestamps but keeps parent expiry.

func (*State) IsExpired

func (s *State) IsExpired() bool

IsExpired returns true if the users's session is expired.

func (*State) UnmarshalJSON

func (s *State) UnmarshalJSON(data []byte) error

UnmarshalJSON returns a State struct from JSON. Additionally munges a user's session by using by setting `user` claim to `sub` if empty.

func (*State) UserID

func (s *State) UserID(provider string) string

UserID returns the corresponding user ID for a session.

type Version

type Version string

Version represents "ver" field in JWT public claims.

The field is not specified by RFC 7519, so providers can return either string or number (like okta).

func (*Version) String

func (v *Version) String() string

String implements fmt.Stringer interface.

func (*Version) UnmarshalJSON

func (v *Version) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler interface.