jwt

README

Go JWT

A Golang implementation of JSON Web Token (JWT) - RFC 7519.

Supported Go versions

Our support of Go versions is aligned with Go's version release policy. So we will support a major version of Go until there are two newer major releases.

---

• Install
• Available Algorithms
• Quick Start
• Issue Reporting
• Secure
• Author
• License

---

Install

With a correctly configured Go toolchain:

go get -u github.com/dmalix/gojwt

Available Algorithms

The library implements JWT Verification and Signing using the following algorithms:

JWS	Algorithm	Description
HS256	HMAC256	HMAC with SHA-256
HS512	HMAC512	HMAC with SHA-512

Quick Start

Create a new JWT instance and configure the parameters:

jwtInstance, err := gojwt.NewToken(&gojwt.Config{
   Headers: gojwt.Headers{
      Type:               gojwt.TokenType,
      SignatureAlgorithm: gojwt.TokenSignatureAlgorithmHS256,   
   },
   Claims: gojwt.Claims{
      Issuer:  "some data",
      Subject: "some subject",
   },
   ParseOptions: gojwt.ParseOptions{
      RequiredHeaderContentType:   true,
      RequiredClaimIssuer:         true,
      RequiredClaimSubject:        true,
      RequiredClaimJwtId:          true,
      RequiredClaimData:           true
   },
   TokenLifetimeSec: 100,
   Key:              "your-256-bit-secret",
})
if err != nil {
   log.Fatal(err)
}

Create a new token:

jwt, err := jwtInstance.Create(&gojwt.Claims{
   JwtId: "some Id",
   Data:  []byte("some dataset"),
})
if err != nil {
   log.Fatal(err)
}

And so you can check and get data from the token:

jwt := "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
jwtToken, codeError, err := jwtInstance.Parse(jwt)
if err != nil {
   log.Fatalln(codeError, err)
}

Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker.

Secure

If you discover any security related issues, please email dmalix@yahoo.com instead of using the issue tracker.

Author

DmAlix

License

This project is licensed under the MIT license. See the LICENSE file for more info.

Documentation

Index

• Constants
• type Claims
• type Config
• type Domain
• type Headers
• type Jwt
  • func NewToken(config *Config) (*Jwt, error)
  • func (t *Jwt) Create(claims *Claims, h ...*Headers) (string, error)
  • func (t *Jwt) GetClaims() Claims
  • func (t *Jwt) GetHeaders() Headers
  • func (t *Jwt) GetParseOptions() ParseOptions
  • func (t *Jwt) Parse(jwt string, options ...*ParseOptions) (*Token, string, error)
• type MockDescription
  • func (s *MockDescription) Create(_ Claims, _ ...Headers) (string, error)
  • func (s *MockDescription) GetClaims() Claims
  • func (s *MockDescription) GetHeaders() Headers
  • func (s *MockDescription) GetParseOptions() ParseOptions
  • func (s *MockDescription) Parse(_ string, _ ...ParseOptions) (Token, string, error)
• type ParseOptions
• type Token

Constants

const (
	ValidationErrorMalformed        = "token is malformed"
	ValidationErrorHeadersMalformed = "token headers are malformed"
	ValidationErrorClaimsMalformed  = "token claims are malformed"
	ValidationErrorUnverifiable     = "the token could not be verified due to problems with the generation of the test sample"
	ValidationErrorSignatureInvalid = "signature validation failed"

	ValidationErrorHeadersContentType = "header 'cty' validation failed"
	ValidationErrorHeadersKeyId       = "header 'kid' validation failed"
	ValidationErrorHeadersCritical    = "header 'crit' validation failed"

	ValidationErrorClaimsIssuer      = "claim 'iss' validation failed"
	ValidationErrorClaimsSubject     = "claim 'sub' validation failed"
	ValidationErrorClaimsAudience    = "claim 'aud' validation failed"
	ValidationErrorClaimsExpired     = "claim 'exp' validation failed"
	ValidationErrorClaimsNotValidYet = "claim 'nbf' validation failed"
	ValidationErrorClaimsIssuedAt    = "claim 'iat' validation failed"
	ValidationErrorClaimsJwtId       = "claim 'jti' validation failed"
	ValidationErrorClaimsSessionId   = "claim 'sessionId' validation failed"
	ValidationErrorClaimsData        = "claim 'data' validation failed"
)

const (
	TokenType                    = "JWT"
	TokenUseAccess               = "Access"
	TokenUseRefresh              = "Refresh"
	TokenSignatureAlgorithmHS256 = "HS256"
	TokenSignatureAlgorithmHS512 = "HS512"
)

Types

type Claims

type Claims struct {
	Issuer         string `json:"iss,omitempty"`
	Subject        string `json:"sub,omitempty"`
	Audience       string `json:"aud,omitempty"`
	ExpirationTime int64  `json:"exp,omitempty"`
	NotBefore      int64  `json:"nbf,omitempty"`
	IssuedAt       int64  `json:"iat,omitempty"`
	JwtId          string `json:"jti,omitempty"`
	Data           []byte `json:"data,omitempty"` // It is a custom field for any data (for example, encrypted data).
}

type Config

type Config struct {
	Headers       Headers
	Claims        Claims
	ParseOptions  ParseOptions
	TokenLifetime int64
	Key           string
}

type Domain

type Domain interface {
	Create(claims *Claims, headers ...*Headers) (string, error)
	Parse(jwt string, parseOptions ...*ParseOptions) (*Token, string, error)

	GetHeaders() Headers
	GetClaims() Claims
	GetParseOptions() ParseOptions
}

type Headers

type Headers struct {
	Type               string `json:"typ,omitempty"`
	SignatureAlgorithm string `json:"alg,omitempty"`
	ContentType        string `json:"cty,omitempty"`
	KeyId              string `json:"kid,omitempty"`
	Critical           string `json:"crit,omitempty"`
}

type Jwt

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

func NewToken

func NewToken(
	config *Config) (*Jwt, error)

func (*Jwt) Create

func (t *Jwt) Create(claims *Claims, h ...*Headers) (string, error)

func (*Jwt) GetClaims

func (t *Jwt) GetClaims() Claims

func (*Jwt) GetHeaders

func (t *Jwt) GetHeaders() Headers

func (*Jwt) GetParseOptions

func (t *Jwt) GetParseOptions() ParseOptions

func (*Jwt) Parse

func (t *Jwt) Parse(jwt string, options ...*ParseOptions) (*Token, string, error)

type MockDescription

type MockDescription struct {
	Expected struct {
		Create struct {
			Jwt   string
			Error error
		}
		Parse struct {
			Token Token
			Error error
		}
		GetHeaders struct {
			Headers Headers
		}
		GetClaims struct {
			Claims Claims
		}
		GetParseOptions struct {
			ParseOptions ParseOptions
		}
	}
}

var Mock MockDescription

func (*MockDescription) Create

func (s *MockDescription) Create(_ Claims, _ ...Headers) (string, error)

func (*MockDescription) GetClaims

func (s *MockDescription) GetClaims() Claims

func (*MockDescription) GetHeaders

func (s *MockDescription) GetHeaders() Headers

func (*MockDescription) GetParseOptions

func (s *MockDescription) GetParseOptions() ParseOptions

func (*MockDescription) Parse

func (s *MockDescription) Parse(_ string, _ ...ParseOptions) (Token, string, error)

type ParseOptions

type ParseOptions struct {
	RequiredHeaderContentType             bool
	RequiredHeaderKeyId                   bool
	RequiredHeaderX509CertificateChain    bool
	RequiredHeaderX509CertificateChainURL bool
	RequiredHeaderCritical                bool
	RequiredClaimIssuer                   bool
	RequiredClaimSubject                  bool
	RequiredClaimAudience                 bool
	RequiredClaimJwtId                    bool
	RequiredClaimData                     bool
	SkipClaimsValidation                  bool
	SkipSignatureValidation               bool
}

type Token

type Token struct {
	Headers   Headers
	Claims    Claims
	Signature string
}