sessions

Documentation

Index

• Constants
• Variables
• func Anonymous() *types.Session
• func Cookies(header ...string) []*http.Cookie
• func FromBase64(in string) (*types.Session, error)
• func FromContext(ctx context.Context) (*types.Session, bool)
• func FromHeaderString(header string) (*types.Session, error)
• func FromMetadata(md metadata.MD) (*types.Session, error)
• func GenerateID() ([]byte, error)
• func HasTaint(s *types.Session, taint string) bool
• func IsZero(id []byte) bool
• func MustFromContext(ctx context.Context) *types.Session
• func NewContext(ctx context.Context, s *types.Session) context.Context
• func Root() *types.Session
• func ToBase64(s *types.Session) string
• func ToHeaderString(s *types.Session) string
• func ToMetadata(dst metadata.MD, s *types.Session)
• func TransformToID() cmp.Option
• type CookieConfig
  • func (c *CookieConfig) EmptyCookie() *http.Cookie
  • func (c *CookieConfig) HandleSetCookie(w http.ResponseWriter, req *http.Request)
  • func (c *CookieConfig) LinkToSetCookie(token string) string
  • func (c *CookieConfig) NewSetCookieRequest(s *types.Session, redirectURL string) (string, error)
  • func (c *CookieConfig) SessionsFromAny(headers, cookies []string) ([]*types.Session, []*UnusedHeader, []*UnusedCookie)
  • func (c *CookieConfig) SessionsFromAuthorization(auths ...string) ([]*types.Session, []*UnusedHeader)
  • func (c *CookieConfig) SessionsFromCookies(cookies []*http.Cookie) ([]*types.Session, []*UnusedCookie)
  • func (c *CookieConfig) SessionsFromMetadata(md metadata.MD) ([]*types.Session, []*UnusedHeader, []*UnusedCookie)
  • func (c *CookieConfig) SessionsFromRequest(req *http.Request) ([]*types.Session, []*UnusedHeader, []*UnusedCookie)
• type UnusedCookie
• type UnusedHeader

Constants

const (
	TaintEnrollment = "enrollment"
	TaintStartLogin = "start_login"
	TaintAnonymous  = "anonymous"

	AnonymousUsername = "anonymous"
	AnonymousUser     = -2
	RootUsername      = "root"
	RootUser          = -1 // It pains me to make root not 0, but 0 means other things.
)

const SetCookieTokenLifetime = time.Minute

How long we'll accept a set-cookie token after issuance. We probably only need it for a few milliseconds, but the risk of making this longer is minimal, and a long duration helps with clock skew issues.

Variables

var (
	ErrSessionMissing  = errors.New("no session id")
	ErrSessionZero     = errors.New("session id is 0 ([64]byte{0, ...})")
	ErrUnknownAuthType = errors.New("unknown authorization header type")
)

Functions

func Anonymous

func Anonymous() *types.Session

Anonymous returns a session for an anonymous user.

func Cookies

func Cookies(header ...string) []*http.Cookie

Cookies returns the cookie objects in the provided string.

func FromBase64

func FromBase64(in string) (*types.Session, error)

FromBase64 extracts a session from a base64-encoded session ID.

func FromContext

func FromContext(ctx context.Context) (*types.Session, bool)

FromContext gets the session in the context.

func FromHeaderString

func FromHeaderString(header string) (*types.Session, error)

FromHeaderString extracts a session from an HTTP header.

func FromMetadata

func FromMetadata(md metadata.MD) (*types.Session, error)

FromMetadata extracts a session from gRPC metadata.

func GenerateID

func GenerateID() ([]byte, error)

GenerateID generates a valid session ID.

func HasTaint

func HasTaint(s *types.Session, taint string) bool

HasTaint returns true if the session has the named taint.

func IsZero

func IsZero(id []byte) bool

IsZero returns true if the session ID is all zeros (or is the wrong length).

func MustFromContext

func MustFromContext(ctx context.Context) *types.Session

MustFromContext gets the session in the context, or panics.

func NewContext

func NewContext(ctx context.Context, s *types.Session) context.Context

NewContext adds the session to the provided context.

func Root

func Root() *types.Session

Root returns a session for the root user.

func ToBase64

func ToBase64(s *types.Session) string

ToBase64 converts a session to a base64-encoded session ID.

func ToHeaderString

func ToHeaderString(s *types.Session) string

ToHeaderString formats a session as an Authorization header.

func ToMetadata

func ToMetadata(dst metadata.MD, s *types.Session)

ToMetadata adds a session ID to gRPC metadata.

func TransformToID

func TransformToID() cmp.Option

TransformToID returns a cmp.Option that transforms sessions to their ID.

Types

type CookieConfig

type CookieConfig struct {
	tokens.GeneratorConfig
	Name   string      // The name of the cookie (like "jsso-session-id").
	Domain string      // The domain that the cookie should be valid on.  ("sso.example.com" might choose "example.com" here.)
	Linker *web.Linker // A Linker for generating links to the set-cookie handler.
}

CookieConfig configures the session cookies (and set-cookie tokens) we produce.

func (*CookieConfig) EmptyCookie

func (c *CookieConfig) EmptyCookie() *http.Cookie

func (*CookieConfig) HandleSetCookie

func (c *CookieConfig) HandleSetCookie(w http.ResponseWriter, req *http.Request)

HandleSetCookie responds to an HTTP GET request with a set-cookie token from NewSetCookieRequest in the "set" query parameter with a Set-Cookie header and a redirect to the redirect_url inside the token. If the redirect_url is empty, we just respond with "ok".

func (*CookieConfig) LinkToSetCookie

func (c *CookieConfig) LinkToSetCookie(token string) string

LinkToSetCookie accepts a token from NewSetCookieRequest and returns the URL that will cause that token to actually set a cookie.

func (*CookieConfig) NewSetCookieRequest

func (c *CookieConfig) NewSetCookieRequest(s *types.Session, redirectURL string) (string, error)

NewSetCookieRequest returns a paseto token (a "set-cookie token") that, when provided to the HandleSetCookie http Handler below, causes a session cookie to be set for the provided session. (It also redirects to the redirectURL after setting the cookie.) We sign+encrypt the token so that random people on the Internet can't induce the handler to set an arbitrary cookie. We do not care about replay attacks -- while one of these tokens can't be revoked, the underlying session can be, so a compromised token is not particularly harmful.

func (*CookieConfig) SessionsFromAny

func (c *CookieConfig) SessionsFromAny(headers, cookies []string) ([]*types.Session, []*UnusedHeader, []*UnusedCookie)

SessionFromAny takes a slice of Authorization headers and Cookie headers, and returns valid sessions, a list of unused Authorization headers, and a list of unused cookies.

func (*CookieConfig) SessionsFromAuthorization

func (c *CookieConfig) SessionsFromAuthorization(auths ...string) ([]*types.Session, []*UnusedHeader)

SessionFromAuthorization extracts sessions from the authorization headers, returning unused/invalid authorization headers.

func (*CookieConfig) SessionsFromCookies

func (c *CookieConfig) SessionsFromCookies(cookies []*http.Cookie) ([]*types.Session, []*UnusedCookie)

SessionFromCookies looks through the provided cookies and returns the sessionID from cookies that look like a session, and the list of cookies with all matching cookies removed (along with a reason for not considering it a session cookie).

func (*CookieConfig) SessionsFromMetadata

func (c *CookieConfig) SessionsFromMetadata(md metadata.MD) ([]*types.Session, []*UnusedHeader, []*UnusedCookie)

SessionFromMetadata extracts authorization headers and cookies from the metadata, returning any sessions that were found, a list of unused authorization headers, and a list of unused cookies. md must not be nil.

func (*CookieConfig) SessionsFromRequest

func (c *CookieConfig) SessionsFromRequest(req *http.Request) ([]*types.Session, []*UnusedHeader, []*UnusedCookie)

SessionFromRequest extracts authentication material from the provided request, returning any sessions that were found, a list of unused authorization headers, and a list of unused cookies.

type UnusedCookie

type UnusedCookie struct {
	Cookie *http.Cookie
	Err    error
}

UnusedCookie is a cookie we couldn't extract a session from, and the reason why. If Err is null, then it simply wasn't a cookie we were looking for.

type UnusedHeader

type UnusedHeader struct {
	Value string
	Err   error
}

UnusedHeader is a header we couldn't extract a session from, and the reason why.