sjwt

README

sjwt

Simple JSON Web Token - Uses HMAC SHA-256

Example

// Set Claims
claims := New()
claims.Set("username", "billymister")
claims.Set("account_id", 8675309)

// Generate jwt
secretKey := []byte("secret_key_here")
jwt := claims.Generate(secretKey)

Example parse

// Parse jwt
jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
claims, _ := Parse(jwt)

// Get claims
name, err := claims.GetStr("name") // John Doe

Example verify and validate

jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
secretKey := []byte("secret_key_here")

// Verify that the secret signature is valid
hasVerified := Verify(jwt, secretKey)

// Parse jwt
claims, _ := Parse(jwt)

// Validate will check(if set) Expiration At and Not Before At dates
err := claims.Validate()

Example usage of registered claims

// Set Claims
claims := New()
claims.SetTokenID()                                  // UUID generated
claims.SetSubject("Subject Title")                   // Subject of the token
claims.SetIssuer("Google")                           // Issuer of the token
claims.SetAudience([]string{"Google", "Facebook"})   // Audience the toke is for
claims.SetIssuedAt(time.Now())                       // IssuedAt in time, value is set in unix
claims.SetNotBeforeAt(time.Now().Add(time.Hour * 1)) // Token valid in 1 hour
claims.SetExpiresAt(time.Now().Add(time.Hour * 24))  // Token expires in 24 hours

// Generate jwt
secretKey := []byte("secret_key_here")
jwt := claims.Generate(secretKey)

Example usage of struct to claims

type Info struct {
    Name string `json:"name"`
}

// Marshal your struct into claims
info := Info{Name: "Billy Mister"}
claims, _ := ToClaims(info)

// Generate jwt
secretKey := []byte("secret_key_here")
jwt := claims.Generate(secretKey)

Why?

For all the times I have needed the use of a jwt, its always been a simple HMAC SHA-256 and thats normally the use of most jwt tokens.

Documentation

Overview

Example

// Add Claims
claims := New()
claims.Set("username", "billymister")
claims.Set("account_id", 8675309)

// Generate jwt
secretKey := []byte("secret_key_here")
jwt := claims.Generate(secretKey)
fmt.Println(jwt)

Example (ClaimsToStruct)

type Info struct {
	Name string `json:"name"`
}

// Parse jwt
jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiQmlsbHkgTWlzdGVyIn0.2FYrpCNy1tg_4UvimpSrgAy-nT9snh-l4w9VLz71b6Y"
claims, _ := Parse(jwt)

// Marshal your struct into claims
info := Info{}
claims.ToStruct(&info)

name, _ := claims.GetStr("name")
fmt.Println(name)

Output:

Billy Mister

Example (Parse)

// Parse jwt
jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
claims, _ := Parse(jwt)

// Get claims
name, _ := claims.GetStr("name")
fmt.Println(name)

Output:

John Doe

Example (PublicClaims)

// Add Claims
claims := New()
claims.Set("username", "billymister")
claims.Set("account_id", 8675309)

// Generate jwt
secretKey := []byte("secret_key_here")
jwt := claims.Generate(secretKey)
fmt.Println(jwt)

Example (RegisteredClaims)

// Add Claims
claims := New()
claims.SetTokenID()                                  // UUID generated
claims.SetSubject("Subject Title")                   // Subject of the token
claims.SetIssuer("Google")                           // Issuer of the token
claims.SetAudience([]string{"Google", "Facebook"})   // Audience the toke is for
claims.SetIssuedAt(time.Now())                       // IssuedAt in time, value is set in unix
claims.SetNotBeforeAt(time.Now().Add(time.Hour * 1)) // Token valid in 1 hour
claims.SetExpiresAt(time.Now().Add(time.Hour * 24))  // Token expires in 24 hours

// Generate jwt
secretKey := []byte("secret_key_here")
jwt := claims.Generate(secretKey)
fmt.Println(jwt)

Example (StructToClaims)

type Info struct {
	Name string `json:"name"`
}

// Marshal your struct into claims
info := Info{Name: "Billy Mister"}
claims, _ := ToClaims(info)

// Generate jwt
secretKey := []byte("secret_key_here")
jwt := claims.Generate(secretKey)
fmt.Println(jwt)

Output:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiQmlsbHkgTWlzdGVyIn0.2FYrpCNy1tg_4UvimpSrgAy-nT9snh-l4w9VLz71b6Y

Example (VerifySignature)

secretKey := []byte("secret_key_here")
jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiQmlsbHkgTWlzdGVyIn0.2FYrpCNy1tg_4UvimpSrgAy-nT9snh-l4w9VLz71b6Y"

// Pass jwt and secret key to verify
verified := Verify(jwt, secretKey)
fmt.Println(verified)

Output:

true

Index

• Constants
• Variables
• func UUID() string
• func Verify(tokenStr string, secret []byte) bool
• type Claims
  • func New() *Claims
  • func Parse(tokenStr string) (Claims, error)
  • func ToClaims(struc interface{}) (Claims, error)
  • func (c Claims) Del(name string)
  • func (c Claims) DeleteAudience()
  • func (c Claims) DeleteExpiresAt()
  • func (c Claims) DeleteIssuedAt()
  • func (c Claims) DeleteIssuer()
  • func (c Claims) DeleteNotBeforeAt()
  • func (c Claims) DeleteSubject()
  • func (c Claims) DeleteTokenID()
  • func (c Claims) Generate(secret []byte) string
  • func (c Claims) Get(name string) (interface{}, error)
  • func (c Claims) GetAudience() ([]string, error)
  • func (c Claims) GetBool(name string) (bool, error)
  • func (c Claims) GetExpiresAt() (int64, error)
  • func (c Claims) GetFloat(name string) (float64, error)
  • func (c Claims) GetInt(name string) (int, error)
  • func (c Claims) GetIssuedAt() (int64, error)
  • func (c Claims) GetIssuer() (string, error)
  • func (c Claims) GetNotBeforeAt() (int64, error)
  • func (c Claims) GetStr(name string) (string, error)
  • func (c Claims) GetSubject() (string, error)
  • func (c Claims) GetTokenID() (string, error)
  • func (c Claims) Has(name string) bool
  • func (c Claims) Set(name string, value interface{})
  • func (c Claims) SetAudience(audience []string)
  • func (c Claims) SetExpiresAt(expiresAt time.Time)
  • func (c Claims) SetIssuedAt(issuedAt time.Time)
  • func (c Claims) SetIssuer(issuer string)
  • func (c Claims) SetNotBeforeAt(notbeforeAt time.Time)
  • func (c Claims) SetSubject(subject string)
  • func (c Claims) SetTokenID()
  • func (c Claims) ToStruct(struc interface{}) error
  • func (c Claims) Validate() error

Examples

• Package
• Package (ClaimsToStruct)
• Package (Parse)
• Package (PublicClaims)
• Package (RegisteredClaims)
• Package (StructToClaims)
• Package (VerifySignature)

Constants

const (
	// TokenID is a unique identifier for this token
	TokenID = "jti"

	// Issuer is the principal that issued the token
	Issuer = "iss"

	// Audience identifies the recipents the token is intended for
	Audience = "aud"

	// Subject is the subject of the token
	Subject = "sub"

	// IssuedAt is a timesatamp for when the token was issued
	IssuedAt = "iat"

	// ExpiresAt is a timestamp for when the token should expire
	ExpiresAt = "exp"

	// NotBeforeAt is a timestamp for which this token should not be excepted until
	NotBeforeAt = "nbf"
)

Variables

var (
	// ErrNotFound is an error string clarifying
	// that the attempted key does not exist in the claims
	ErrNotFound = errors.New("Claim key not found in claims")

	// ErrClaimValueInvalid is an error string clarifying
	// that the attempt to retrieve a value could not be properly converted
	ErrClaimValueInvalid = errors.New("Claim value invalid")

	// ErrTokenInvalid is an error string clarifying
	// the provided token is an invalid format
	ErrTokenInvalid = errors.New("Token is invalid")

	// ErrTokenHasExpired is an error string clarifying
	// the current unix timestamp has exceed the exp unix timestamp
	ErrTokenHasExpired = errors.New("Token has expired")

	// ErrTokenNotYetValid is an error string clarifying
	// the current unix timestamp has not exceeded the nbf unix timestamp
	ErrTokenNotYetValid = errors.New("Token is not yet valid")
)

Functions

func UUID

func UUID() string

UUID (version 4) will generate a random unique identifier based upon random nunbers Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

func Verify

func Verify(tokenStr string, secret []byte) bool

Verify will take in the token string and secret and identify the signature matches

Types

type Claims

type Claims map[string]interface{}

Claims is the main container for our body information

func New

func New() *Claims

New will initiate a new claims

func Parse

func Parse(tokenStr string) (Claims, error)

Parse will take in the token string grab the body and unmarshal into claims interface

func ToClaims

func ToClaims(struc interface{}) (Claims, error)

ToClaims takes in an interface and unmarshals it to claims

func (Claims) Del

func (c Claims) Del(name string)

Del deletes a name/value from claims

func (Claims) DeleteAudience

func (c Claims) DeleteAudience()

DeleteAudience deletes audience

func (Claims) DeleteExpiresAt

func (c Claims) DeleteExpiresAt()

DeleteExpiresAt deletes expires at

func (Claims) DeleteIssuedAt

func (c Claims) DeleteIssuedAt()

DeleteIssuedAt deletes issued at

func (Claims) DeleteIssuer

func (c Claims) DeleteIssuer()

DeleteIssuer deletes issuer

func (Claims) DeleteNotBeforeAt

func (c Claims) DeleteNotBeforeAt()

DeleteNotBeforeAt deletes not before at

func (Claims) DeleteSubject

func (c Claims) DeleteSubject()

DeleteSubject deletes token id

func (Claims) DeleteTokenID

func (c Claims) DeleteTokenID()

DeleteTokenID deletes token id

func (Claims) Generate

func (c Claims) Generate(secret []byte) string

Generate takes in claims and a secret and outputs jwt token

func (Claims) Get

func (c Claims) Get(name string) (interface{}, error)

Get gets claim value

func (Claims) GetAudience

func (c Claims) GetAudience() ([]string, error)

GetAudience will get the audience set on the Claims

func (Claims) GetBool

func (c Claims) GetBool(name string) (bool, error)

GetBool will get the boolean value on the Claims

func (Claims) GetExpiresAt

func (c Claims) GetExpiresAt() (int64, error)

GetExpiresAt will get the expires at timestamp set on the Claims

func (Claims) GetFloat

func (c Claims) GetFloat(name string) (float64, error)

GetFloat will get the float value on the Claims

func (Claims) GetInt

func (c Claims) GetInt(name string) (int, error)

GetInt will get the int value on the Claims

func (Claims) GetIssuedAt

func (c Claims) GetIssuedAt() (int64, error)

GetIssuedAt will get the issued at timestamp set on the Claims

func (Claims) GetIssuer

func (c Claims) GetIssuer() (string, error)

GetIssuer will get the issuer set on the Claims

func (Claims) GetNotBeforeAt

func (c Claims) GetNotBeforeAt() (int64, error)

GetNotBeforeAt will get the not before at timestamp set on the Claims

func (Claims) GetStr

func (c Claims) GetStr(name string) (string, error)

GetStr will get the string value on the Claims

func (Claims) GetSubject

func (c Claims) GetSubject() (string, error)

GetSubject will get the subject set on the Claims

func (Claims) GetTokenID

func (c Claims) GetTokenID() (string, error)

GetTokenID will get the id set on the Claims

func (Claims) Has

func (c Claims) Has(name string) bool

Has will let you know whether or not a claim exists

func (Claims) Set

func (c Claims) Set(name string, value interface{})

Set adds/sets a name/value to claims

func (Claims) SetAudience

func (c Claims) SetAudience(audience []string)

SetAudience will set a string value for the audience

func (Claims) SetExpiresAt

func (c Claims) SetExpiresAt(expiresAt time.Time)

SetExpiresAt will set an expires at timestamp in nanoseconds

func (Claims) SetIssuedAt

func (c Claims) SetIssuedAt(issuedAt time.Time)

SetIssuedAt will set an issued at timestamp in nanoseconds

func (Claims) SetIssuer

func (c Claims) SetIssuer(issuer string)

SetIssuer will set a string value for the issuer

func (Claims) SetNotBeforeAt

func (c Claims) SetNotBeforeAt(notbeforeAt time.Time)

SetNotBeforeAt will set an not before at timestamp in nanoseconds

func (Claims) SetSubject

func (c Claims) SetSubject(subject string)

SetSubject will set a subject value

func (Claims) SetTokenID

func (c Claims) SetTokenID()

SetTokenID will set a random uuid v4 id

func (Claims) ToStruct

func (c Claims) ToStruct(struc interface{}) error

ToStruct takes your claims and sets value to struct

func (Claims) Validate

func (c Claims) Validate() error

Validate checks expiration and not before times