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
  • func MultiSessionLoader(loaders ...SessionLoader) SessionLoader
• type SessionStore
• type State
  • func NewState(idpID string) *State
  • func (s *State) UnmarshalJSON(data []byte) error
  • func (s *State) UserID(provider string) string
  • func (s *State) WithNewIssuer(issuer string, audience []string) State

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.

func MultiSessionLoader

func MultiSessionLoader(loaders ...SessionLoader) SessionLoader

MultiSessionLoader returns a session loader that returns the first session available.

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"`
	IssuedAt *jwt.NumericDate `json:"iat,omitempty"`
	ID       string           `json:"jti,omitempty"`

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

	// 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"`

	// IdentityProviderID is the identity provider for the session.
	IdentityProviderID string `json:"idp_id,omitempty"`
}

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

func NewState

func NewState(idpID string) *State

NewState creates a new State.

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.

func (*State) WithNewIssuer

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

WithNewIssuer creates a new State from an existing State.