sessions

Documentation

Index

• Constants
• Variables
• func ExtendDeadline(ttl time.Duration) time.Time
• func MarshalSession(s *SessionState, c cryptutil.Cipher) (string, error)
• type CSRFStore
• type CookieStore
  • func NewCookieStore(opts *CookieStoreOptions) (*CookieStore, error)
  • func (s *CookieStore) ClearCSRF(w http.ResponseWriter, req *http.Request)
  • func (s *CookieStore) ClearSession(w http.ResponseWriter, req *http.Request)
  • func (s *CookieStore) GetCSRF(req *http.Request) (*http.Cookie, error)
  • func (s *CookieStore) LoadSession(req *http.Request) (*SessionState, error)
  • func (s *CookieStore) SaveSession(w http.ResponseWriter, req *http.Request, sessionState *SessionState) error
  • func (s *CookieStore) SetCSRF(w http.ResponseWriter, req *http.Request, val string)
• type CookieStoreOptions
• type MockCSRFStore
  • func (ms MockCSRFStore) ClearCSRF(http.ResponseWriter, *http.Request)
  • func (ms MockCSRFStore) GetCSRF(*http.Request) (*http.Cookie, error)
  • func (ms MockCSRFStore) SetCSRF(rw http.ResponseWriter, req *http.Request, val string)
• type MockSessionStore
  • func (ms *MockSessionStore) ClearSession(http.ResponseWriter, *http.Request)
  • func (ms MockSessionStore) LoadSession(*http.Request) (*SessionState, error)
  • func (ms MockSessionStore) SaveSession(http.ResponseWriter, *http.Request, *SessionState) error
• type RestStore
  • func NewRestStore(opts *RestStoreOptions) (*RestStore, error)
  • func (s *RestStore) ClearSession(w http.ResponseWriter, r *http.Request)
  • func (s *RestStore) LoadSession(r *http.Request) (*SessionState, error)
  • func (s *RestStore) SaveSession(w http.ResponseWriter, r *http.Request, sessionState *SessionState) error
• type RestStoreOptions
• type RestStoreResponse
• type SessionState
  • func UnmarshalSession(value string, c cryptutil.Cipher) (*SessionState, error)
  • func (s *SessionState) Impersonating() bool
  • func (s *SessionState) IssuedAt() (time.Time, error)
  • func (s *SessionState) RefreshPeriodExpired() bool
  • func (s *SessionState) RequestEmail() string
  • func (s *SessionState) RequestGroups() string
• type SessionStore

Constants

const ChunkedCanaryByte byte = '%'

ChunkedCanaryByte is the byte value used as a canary prefix to distinguish if the cookie is multi-part or not. This constant *should not* be valid base64. It's important this byte is ASCII to avoid UTF-8 variable sized runes. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Directives

const DefaultBearerTokenHeader = "Authorization"

DefaultBearerTokenHeader is default header name for the authorization bearer token header as defined in rfc2617 https://tools.ietf.org/html/rfc6750#section-2.1

const MaxChunkSize = 3800

MaxChunkSize sets the upper bound on a cookie chunks payload value. Note, this should be lower than the actual cookie's max size (4096 bytes) which includes metadata.

const MaxNumChunks = 5

MaxNumChunks limits the number of chunks to iterate through. Conservatively set to prevent any abuse.

Variables

var ErrInvalidSession = errors.New("internal/sessions: invalid session")

ErrInvalidSession is an error for invalid sessions.

var (
	// ErrLifetimeExpired is an error for the lifetime deadline expiring
	ErrLifetimeExpired = errors.New("user lifetime expired")
)

Functions

func ExtendDeadline

func ExtendDeadline(ttl time.Duration) time.Time

ExtendDeadline returns the time extended by a given duration, truncated by second

func MarshalSession

func MarshalSession(s *SessionState, c cryptutil.Cipher) (string, error)

MarshalSession marshals the session state as JSON, encrypts the JSON using the given cipher, and base64-encodes the result

Types

type CSRFStore

type CSRFStore interface {
	SetCSRF(http.ResponseWriter, *http.Request, string)
	GetCSRF(*http.Request) (*http.Cookie, error)
	ClearCSRF(http.ResponseWriter, *http.Request)
}

CSRFStore has the functions for setting, getting, and clearing the CSRF cookie

type CookieStore

type CookieStore struct {
	Name           string
	CookieCipher   cryptutil.Cipher
	CookieExpire   time.Duration
	CookieRefresh  time.Duration
	CookieSecure   bool
	CookieHTTPOnly bool
	CookieDomain   string
}

CookieStore represents all the cookie related configurations

func NewCookieStore

func NewCookieStore(opts *CookieStoreOptions) (*CookieStore, error)

NewCookieStore returns a new session with ciphers for each of the cookie secrets

func (*CookieStore) ClearCSRF

func (s *CookieStore) ClearCSRF(w http.ResponseWriter, req *http.Request)

ClearCSRF clears the CSRF cookie from the request

func (*CookieStore) ClearSession

func (s *CookieStore) ClearSession(w http.ResponseWriter, req *http.Request)

ClearSession clears the session cookie from a request

func (*CookieStore) GetCSRF

func (s *CookieStore) GetCSRF(req *http.Request) (*http.Cookie, error)

GetCSRF gets the CSRFCookie creates a CSRF cookie in a given request

func (*CookieStore) LoadSession

func (s *CookieStore) LoadSession(req *http.Request) (*SessionState, error)

LoadSession returns a SessionState from the cookie in the request.

func (*CookieStore) SaveSession

func (s *CookieStore) SaveSession(w http.ResponseWriter, req *http.Request, sessionState *SessionState) error

SaveSession saves a session state to a request sessions.

func (*CookieStore) SetCSRF

func (s *CookieStore) SetCSRF(w http.ResponseWriter, req *http.Request, val string)

SetCSRF sets the CSRFCookie creates a CSRF cookie in a given request

type CookieStoreOptions

type CookieStoreOptions struct {
	Name           string
	CookieSecure   bool
	CookieHTTPOnly bool
	CookieDomain   string
	CookieExpire   time.Duration
	CookieCipher   cryptutil.Cipher
}

CookieStoreOptions holds options for CookieStore

type MockCSRFStore

type MockCSRFStore struct {
	ResponseCSRF string
	Cookie       *http.Cookie
	GetError     error
}

MockCSRFStore is a mock implementation of the CSRF store interface

func (MockCSRFStore) ClearCSRF

func (ms MockCSRFStore) ClearCSRF(http.ResponseWriter, *http.Request)

ClearCSRF clears the ResponseCSRF string

func (MockCSRFStore) GetCSRF

func (ms MockCSRFStore) GetCSRF(*http.Request) (*http.Cookie, error)

GetCSRF returns the cookie and error

func (MockCSRFStore) SetCSRF

func (ms MockCSRFStore) SetCSRF(rw http.ResponseWriter, req *http.Request, val string)

SetCSRF sets the ResponseCSRF string to a val

type MockSessionStore

type MockSessionStore struct {
	ResponseSession string
	Session         *SessionState
	SaveError       error
	LoadError       error
}

MockSessionStore is a mock implementation of the SessionStore interface

func (*MockSessionStore) ClearSession

func (ms *MockSessionStore) ClearSession(http.ResponseWriter, *http.Request)

ClearSession clears the ResponseSession

func (MockSessionStore) LoadSession

func (ms MockSessionStore) LoadSession(*http.Request) (*SessionState, error)

LoadSession returns the session and a error

func (MockSessionStore) SaveSession

func (ms MockSessionStore) SaveSession(http.ResponseWriter, *http.Request, *SessionState) error

SaveSession returns a save error.

type RestStore

type RestStore struct {
	Name   string
	Cipher cryptutil.Cipher
}

RestStore is a session store suitable for REST

func NewRestStore

func NewRestStore(opts *RestStoreOptions) (*RestStore, error)

NewRestStore creates a new RestStore from a set of RestStoreOptions.

func (*RestStore) ClearSession

func (s *RestStore) ClearSession(w http.ResponseWriter, r *http.Request)

ClearSession functions differently because REST is stateless, we instead inform the client that this token is no longer valid. https://tools.ietf.org/html/rfc6750

func (*RestStore) LoadSession

func (s *RestStore) LoadSession(r *http.Request) (*SessionState, error)

LoadSession attempts to load a pomerium session from a Bearer Token set in the authorization header.

func (*RestStore) SaveSession

func (s *RestStore) SaveSession(w http.ResponseWriter, r *http.Request, sessionState *SessionState) error

SaveSession returns an encrypted pomerium session as a JSON object with associated, non sensitive meta-data like

type RestStoreOptions

type RestStoreOptions struct {
	Name   string
	Cipher cryptutil.Cipher
}

RestStoreOptions contains the options required to build a new RestStore.

type RestStoreResponse

type RestStoreResponse struct {
	// Token is the encrypted pomerium session that can be used to
	// programmatically authenticate with pomerium.
	Token string
	// In addition to the token, non-sensitive meta data is returned to help
	// the client manage token renewals.
	Expiry time.Time
}

RestStoreResponse is the JSON struct returned to the client.

type SessionState

type SessionState struct {
	AccessToken     string    `json:"access_token"`
	RefreshToken    string    `json:"refresh_token"`
	IDToken         string    `json:"id_token"`
	RefreshDeadline time.Time `json:"refresh_deadline"`

	Email  string   `json:"email"`
	User   string   `json:"user"`
	Groups []string `json:"groups"`

	ImpersonateEmail  string
	ImpersonateGroups []string
}

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

func UnmarshalSession

func UnmarshalSession(value string, c cryptutil.Cipher) (*SessionState, error)

UnmarshalSession takes the marshaled string, base64-decodes into a byte slice, decrypts the byte slice using the passed cipher, and unmarshals the resulting JSON into a session state struct

func (*SessionState) Impersonating

func (s *SessionState) Impersonating() bool

Impersonating returns if the request is impersonating.

func (*SessionState) IssuedAt

func (s *SessionState) IssuedAt() (time.Time, error)

IssuedAt parses the IDToken's issue date and returns a valid go time.Time.

func (*SessionState) RefreshPeriodExpired

func (s *SessionState) RefreshPeriodExpired() bool

RefreshPeriodExpired returns true if the refresh period has expired

func (*SessionState) RequestEmail

func (s *SessionState) RequestEmail() string

RequestEmail is the email to make the request as.

func (*SessionState) RequestGroups

func (s *SessionState) RequestGroups() string

RequestGroups returns the groups of the Groups making the request; uses impersonating user if set.

type SessionStore

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

SessionStore has the functions for setting, getting, and clearing the Session cookie