session

README

Session - Go JWT wrapper

A Go JWT wrapper which bundles common operations for JWT tokens. Makes pervasive use of the jwt Go implementation of JSON Web Tokens (JWT).

What?

This provides functionality to create custom map claims, new JWTs, validity checks, refresh JWTs and check JWT content. It was built and intended for use with auth but can be used as a standalone.

Why?

This was part of a learning exercise to create auth which is a very rough Go equivalent of dotnet core Identity services.

How?

See the tests for usage examples.

Examples

See [examples] for a http/appengine implementations which uses session and auth. This is written for appengine standard 2nd gen, but also works as a standalone.

Dependencies and services

This utilises the following fine pieces of work:

• jwt Go implementation of JSON Web Tokens (JWT)
• Segment's ksuid - K-Sortable Globally Unique IDs
• GCP's [Datastore Go client] and Storage Go client

Also uses:

• lidstromberg packages log, keypair and config. Please note that log and config do not require environment variables to be set, but keypair requires encryption keys to be set. Refer to the keypair package for further details. The easiest way to ensure all of these things are configured, is to refer to the auth package itself.

Installation

Install using go get.

$ go get -u github.com/lidstromberg/session

Environment Variables

You will also need to export (linux/macOS) or create (Windows) some environment variables.

################################
# SESSION
################################
export JWT_DEBUGON="false"
export JWT_ISSUER="{{DOMAINNAME}}"
export JWT_EXTMIN="15"
export JWT_APPROLEDELIM=":"

################################
# GCP CREDENTIALS
################################
export GOOGLE_APPLICATION_CREDENTIALS="/PATH/TO/GCPCREDENTIALS.JSON"

(See Google Application Credentials)

Private/Public Certs for JWT

If you want to run the authcore tests or the example implementations, then you will also require RSA certs for the jwt tokens. See keypair for details on how these are used.

Google Cloud Platform Requirements

If you intend to use GCP datastore as your backend, then you will require:

• A GCP project
• A GCP storage bucket (private) to store the jwt private/public keys (in the root of the bucket). See keypair for further details.
• Your GOOGLE_APPLICATION_CREDENTIALS json credentials key should be created with the following IAM scopes: 'Storage Object Viewer' and 'Storage Object Creator', or 'Storage Object Admin'.

Main Files

File	Purpose
sessmgr.go	Logic manager
sessmgr_test.go	Tests

Ancillary Files

File	Purpose
config.go	Boot package parameters, environment var collection
entity.go	Package structs
errors.go	Package error definitions
env	Package environment variables for local/dev installation
gogets	Statements for go-getting required packages

Documentation

Index

• Constants
• Variables
• func DrainFn(c <-chan interface{})
• func PollFn(ctx context.Context, wg *sync.WaitGroup, sessid string, c <-chan interface{}) string
• type LoginCandidate
• type SessMgr
  • func NewMgr(ctx context.Context, bc lbcf.ConfigSetting, kpr *kp.KeyPair) (*SessMgr, error)
  • func (sessMgr *SessMgr) CheckUserRole(ctx context.Context, sessionID string, roleName string) (bool, error)
  • func (sessMgr *SessMgr) DeleteAppClaim(ctx context.Context, sessionID string, appName string) (string, error)
  • func (sessMgr *SessMgr) GetJwtClaim(ctx context.Context, sessionID string) (map[string]interface{}, error)
  • func (sessMgr *SessMgr) GetJwtClaimElement(ctx context.Context, sessionID, element string) (interface{}, error)
  • func (sessMgr *SessMgr) IsSessionValid(ctx context.Context, sessionID string) (bool, error)
  • func (sessMgr *SessMgr) NewSession(ctx context.Context, shdr map[string]interface{}) (string, error)
  • func (sessMgr *SessMgr) RefreshSession(ctx context.Context, sessionID string) <-chan interface{}
  • func (sessMgr *SessMgr) SetAppClaim(ctx context.Context, sessionID string, appName string, appClaim string) (string, error)
• type SessProvider

Constants

const (
	//ConstJwtID id (session) element
	ConstJwtID = "jti"
	//ConstJwtRole roletoken id
	ConstJwtRole = "rle"
	//ConstJwtAccID account id
	ConstJwtAccID = "aid"
	//ConstJwtEml email
	ConstJwtEml = "eml"
)

Variables

var (
	//ErrKeyPairNotExist occurs if the key pair cannot be read
	ErrKeyPairNotExist = errors.New("keypair could not be created")
	//ErrJwtCouldNotParseToken error message
	ErrJwtCouldNotParseToken = errors.New("could not parse token, or token not valid")
	//ErrLoginSessionNotCreated failed to create session error
	ErrLoginSessionNotCreated = errors.New("could not create a login session")
	//ErrJwtInvalidSession error message
	ErrJwtInvalidSession = errors.New("session is no longer valid, please login")
	//ErrClaimElementNotExist error message
	ErrClaimElementNotExist = errors.New("the claim element does not exist")
)

errors

var (
	//EnvDebugOn controls verbose logging
	EnvDebugOn bool
)

Functions

func DrainFn

func DrainFn(c <-chan interface{})

DrainFn drains a channel until it is closed

func PollFn

func PollFn(ctx context.Context, wg *sync.WaitGroup, sessid string, c <-chan interface{}) string

PollFn processes either the error or the new session token

Types

type LoginCandidate

type LoginCandidate struct {
	SessionID     string     `json:"sessionid" datastore:"sessionid"`
	UserAccountID string     `json:"useraccountid" datastore:"useraccountid"`
	Email         string     `json:"email" datastore:"email"`
	RoleToken     string     `json:"roletoken" datastore:"roletoken"`
	Activated     bool       `json:"activated" datastore:"activated"`
	CreatedDate   *time.Time `json:"createddate,omitempty" datastore:"createddate"`
	ActivatedDate *time.Time `json:"activateddate,omitempty" datastore:"activateddate"`
}

LoginCandidate is a record of a login attempt

type SessMgr

type SessMgr struct {
	// contains filtered or unexported fields
}

SessMgr handles jwts

func NewMgr

func NewMgr(ctx context.Context, bc lbcf.ConfigSetting, kpr *kp.KeyPair) (*SessMgr, error)

NewMgr creates a new credential manager

func (*SessMgr) CheckUserRole

func (sessMgr *SessMgr) CheckUserRole(ctx context.Context, sessionID string, roleName string) (bool, error)

CheckUserRole checks that the jwt authorises a given claim

func (*SessMgr) DeleteAppClaim

func (sessMgr *SessMgr) DeleteAppClaim(ctx context.Context, sessionID string, appName string) (string, error)

DeleteAppClaim removes an appclaim within the jwt (includes token refresh)

func (*SessMgr) GetJwtClaim

func (sessMgr *SessMgr) GetJwtClaim(ctx context.Context, sessionID string) (map[string]interface{}, error)

GetJwtClaim returns a decoded map[string]interface{} from the session string

func (*SessMgr) GetJwtClaimElement

func (sessMgr *SessMgr) GetJwtClaimElement(ctx context.Context, sessionID, element string) (interface{}, error)

GetJwtClaimElement returns a decoded interface{} from the session string

func (*SessMgr) IsSessionValid

func (sessMgr *SessMgr) IsSessionValid(ctx context.Context, sessionID string) (bool, error)

IsSessionValid returns a bool indicating if the session is still valid

func (*SessMgr) NewSession

func (sessMgr *SessMgr) NewSession(ctx context.Context, shdr map[string]interface{}) (string, error)

NewSession returns a signed jwt as a string

func (*SessMgr) RefreshSession

func (sessMgr *SessMgr) RefreshSession(ctx context.Context, sessionID string) <-chan interface{}

RefreshSession exchanges a valid token for an extended life token

func (*SessMgr) SetAppClaim

func (sessMgr *SessMgr) SetAppClaim(ctx context.Context, sessionID string, appName string, appClaim string) (string, error)

SetAppClaim adds or updates an appclaim within the jwt (includes token refresh)

type SessProvider

type SessProvider interface {
	NewSession(ctx context.Context, shdr map[string]interface{}) (string, error)
	CheckUserRole(ctx context.Context, sessionID string, roleName string) (bool, error)
	GetJwtClaim(ctx context.Context, sessionID string) (map[string]interface{}, error)
	GetJwtClaimElement(ctx context.Context, sessionID, element string) (interface{}, error)
	IsSessionValid(ctx context.Context, sessionID string) (bool, error)
	RefreshSession(ctx context.Context, sessionID string) <-chan interface{}
	SetAppClaim(ctx context.Context, sessionID string, appName string, appClaim string) (string, error)
	DeleteAppClaim(ctx context.Context, sessionID string, appName string) (string, error)
}

SessProvider defines the public operations of a session manager