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, accessToken *oauth2.Token) State
  • func (s *State) Impersonating() bool
  • func (s *State) IsExpired() bool
  • func (s *State) SetImpersonation(email, groups string)
  • func (s *State) UnmarshalJSON(data []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

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"`
	// At_hash is an OPTIONAL Access Token hash value
	// https://ldapwiki.com/wiki/At_hash
	AccessTokenHash string `json:"at_hash,omitempty"`

	// core pomerium identity claims ; not standard to RFC 7519
	Email  string   `json:"email"`
	Groups []string `json:"groups,omitempty"`
	User   string   `json:"user,omitempty"` // google

	// commonly supported IdP information
	// https://www.iana.org/assignments/jwt/jwt.xhtml#claims
	Name          string `json:"name,omitempty"`           // google
	GivenName     string `json:"given_name,omitempty"`     // google
	FamilyName    string `json:"family_name,omitempty"`    // google
	Picture       string `json:"picture,omitempty"`        // google
	EmailVerified bool   `json:"email_verified,omitempty"` // google
	Nickname      string `json:"nickname,omitempty"`       // gitlab

	// Impersonate-able fields
	ImpersonateEmail  string   `json:"impersonate_email,omitempty"`
	ImpersonateGroups []string `json:"impersonate_groups,omitempty"`

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

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

func NewSession

func NewSession(s *State, issuer string, audience []string, accessToken *oauth2.Token) State

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

func (*State) Impersonating

func (s *State) Impersonating() bool

Impersonating returns if the request is impersonating.

func (*State) IsExpired

func (s *State) IsExpired() bool

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

func (*State) SetImpersonation

func (s *State) SetImpersonation(email, groups string)

SetImpersonation sets impersonation user and groups.

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.