sessions

Documentation

Index

• Constants
• Variables
• func NewContext(ctx context.Context, t *State, err error) context.Context
• func RetrieveSession(s ...SessionLoader) func(http.Handler) http.Handler
• type SessionLoader
• type SessionStore
• type State
  • func FromContext(ctx context.Context) (*State, error)
  • func NewStateFromTokens(idToken *oidc.IDToken, accessToken *oauth2.Token, audience string) (*State, error)
  • func (s *State) Impersonating() bool
  • func (s State) NewSession(issuer string, audience []string) *State
  • func (s *State) RequestEmail() string
  • func (s *State) RequestGroups() string
  • func (s State) RouteSession() *State
  • func (s *State) SetImpersonation(email, groups string)
  • func (s *State) UnmarshalJSON(b []byte) error
  • func (s *State) UpdateState(idToken *oidc.IDToken, accessToken *oauth2.Token) error
  • func (s *State) Verify(audience string) error

Constants

const (
	// DefaultLeeway defines the default leeway for matching NotBefore/Expiry claims.
	DefaultLeeway = 1.0 * time.Minute
)

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 NewContext

func NewContext(ctx context.Context, t *State, 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) (*State, 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"`

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

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

	AccessToken   *oauth2.Token `json:"act,omitempty"`
	AccessTokenID string        `json:"ati,omitempty"`
	// contains filtered or unexported fields
}

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

func FromContext

func FromContext(ctx context.Context) (*State, error)

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

func NewStateFromTokens

func NewStateFromTokens(idToken *oidc.IDToken, accessToken *oauth2.Token, audience string) (*State, error)

NewStateFromTokens returns a session state built from oidc and oauth2 tokens as part of OpenID Connect flow with a new audience appended to the audience claim.

func (*State) Impersonating

func (s *State) Impersonating() bool

Impersonating returns if the request is impersonating.

func (State) NewSession

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

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

func (*State) RequestEmail

func (s *State) RequestEmail() string

RequestEmail is the email to make the request as.

func (*State) RequestGroups

func (s *State) RequestGroups() string

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

func (State) RouteSession

func (s State) RouteSession() *State

RouteSession creates a route session with access tokens stripped.

func (*State) SetImpersonation

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

SetImpersonation sets impersonation user and groups.

func (*State) UnmarshalJSON

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

UnmarshalJSON parses the JSON-encoded session state. TODO(BDD): remove in v0.8.0

func (*State) UpdateState

func (s *State) UpdateState(idToken *oidc.IDToken, accessToken *oauth2.Token) error

UpdateState updates the current state given a new identity (oidc) and authorization (oauth2) tokens following a oidc refresh. NB, unlike during authentication, refresh typically provides fewer claims in the token so we want to build from our previous state.

func (*State) Verify

func (s *State) Verify(audience string) error

Verify returns an error if the users's session state is not valid.