token

README

token

JWT creation library to be shared across my apps, with sane defaults

A library for basic jwt creation and parsing written in go

I have gone back to basics reading the JWT spec and getting inspiration from jwt.io and Auth0.com

The idea was to create a standard JWT token to be used across multiple projects, using security best practices and sane defaults.

also, at least initially the idea is to have a minimal number of exportable functions, to allow the workings to invisibly change as required.

Currently the API is planned to be

// NewToken returns a new token object with the provided fields, and time fields filled based on the current time.
NewToken(issuer, userID, audience, tokenID, keyID string, expiresInXSeconds int64) (tokenStruct *Token)

// CreateJWT turns a NewToken() into a signed JWT using HMAC SHA512 using the secret obtained by calling the passwordLookup callback with the keyID value
CreateJWT(passwordLookup func(keyID string)(secret string, err error)) (jwt string)

// Decode turns a signed JWT into a *Token
// but only after checking the validity of the token.
// it also requires a callback to lookup the secret the signature was signed with,
// and a pointer to the object that it needs to fill
Decode(jwt string, passwordLookup func(keyID string)(secret string, err error), trustedTokenObject *Token) (err error)

Documentation

Index

• Variables
• func Decode(untrustedJWT string, passwordLookup func(key string) (secret string), ...) (err error)
• type Header
• type Payload
• type Token
  • func NewToken(issuer, audience, userID, jwtID, keyID string, validFor int64) (token *Token)
  • func (t *Token) CreateJWT(passwordLookup func(keyID string) string) (jwt string, err error)

Variables

var (
	ErrInvalidToken = errors.New("invalid token")
	ErrExpiredToken = errors.New("token has expired")
	ErrFailedSecret = errors.New("failed to retrieve secret")
)

Errors

Functions

func Decode

func Decode(untrustedJWT string, passwordLookup func(key string) (secret string), token *Token) (err error)

Decode turns a signed JWT into a map[string]interface (or returns an error) but only after checking the validity of the token.

Types

type Header

type Header struct {
	// Algorithm - "alg" - The encoding algorithm used to sign the token
	// This is "HS512" and is set automatically
	Algorithm string `json:"alg"`

	// TokenType - "typ" - The type of token to be produced
	// This is set to "JWT" automatically
	TokenType string `json:"typ"`
}

Header contains the required standard JWT fields

type Payload

type Payload struct {

	// Issuer - "iss" - issuer (string || URI)
	// The top level domain that issues the token
	Issuer string `json:"iss"`

	// Audience - "aud" - audience
	// who the JWT is intended for.
	// The token will be rejected if the principal processing
	// the claim does not identify itself with
	// the value listed here.
	Audience string `json:"aud"`

	// UserID - "sub" - subject
	// who the JWT was supplied to.
	// Should be a unique identifier
	UserID string `json:"sub"`

	// JwtID - "jti" - JWT ID
	// The unique identifier for this particular token
	JwtID string `json:"jti"`

	// KeyID - "kid" - Key ID
	// ** Public Claim **
	// The version of the secret used to hash the signature.
	KeyID string `json:"kid"`

	// IssuedAtTime - "iat" - issued at time
	// the time the JWT was issued
	// Represented as UNIX time int64 as seconds since the epoch
	IssuedAtTime int64 `json:"iat"`

	// NotBeforeTime - "nbf" - not before time
	// the time the token begins to be valid
	// Represented as UNIX time int64 as seconds since the epoch
	NotBeforeTime int64 `json:"nbf"`

	// ExpirationTime - "exp" - expiration time
	// the time the JWT ceases to be valid
	// Represented as UNIX time int64 as seconds since the epoch
	ExpirationTime int64 `json:"exp"`
}

Payload contains the data stored within the JWT Note information stored here is not secure, it will be transmitted encoded into URLBase64

type Token

type Token struct {
	Header
	Payload
	// contains filtered or unexported fields
}

Token is the struct that holds all of the data to be written to the JWT

func NewToken

func NewToken(issuer, audience, userID, jwtID, keyID string, validFor int64) (token *Token)

NewToken creates a new token, with sane defaults for header and payload time values,

func (*Token) CreateJWT

func (t *Token) CreateJWT(passwordLookup func(keyID string) string) (jwt string, err error)