Categorygithub.com/furdarius/jwtee
modulepackage
0.0.2
Repository: https://github.com/furdarius/jwtee.git
Documentation: pkg.go.dev

# README

JWTee

GoDoc Build Status Go Report Card

Fast and flexible library to work with JSON Web Token and JSON Web Signature in Go based on the RFC 7519.

The purpose of the library is to use full power of strong typing when working with JWT.

Installation

go get github.com/furdarius/jwtee

Adding as dependency by "go dep"

$ dep ensure -add github.com/furdarius/jwtee

Usage

Parsing and Verifying

Define own claims, embedding RegisteredClaims:

type myclaims struct {
	jwtee.RegisteredClaims

	Name string `json:"name"`
}

Parse and verify token and claims:

hmacSigner := signer.NewHS256()
key := jwtee.NewSharedSecretKey(secret)
verifier := jwtee.NewPartsVerifier(hmacSigner, key)
jsonParser := jwtee.NewJSONParser()
verifyingParser := jwtee.NewVerifyingParser(jsonParser, verifier)
claimsValidator := jwtee.NewClaimsValidator()

secret := []byte("secret_code")
token := []byte("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJteXNlcnZpY2UiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjJ9.10i7pIGVUVloV6vrixXDhPdeq09KCdBrUzSzKZxIzLA")

tokenParts, err := verifyingParser.Parse(token)

if err == jwtee.ErrInvalidSignature {
    log.Fatal("token has invalid signature")
}

if err != nil {
    log.Fatalf("failed to parse JWT string: %v", err)
}

var claims myclaims
err = json.Unmarshal(tokenParts.RawClaims(), &claims)
if err != nil {
    log.Fatalf("failed to unmarshal claims: %v", err)
}

errs := claimsValidator.Validate(claims.RegisteredClaims,
    constraint.NewValidAt().WithLeeway(1*time.Minute),
    constraint.NewRelatedTo("myservice"),
)
if errs != nil {
    log.Println("claims is not valid:")
    for _, constraintErr := range errs {
        log.Println("  ", constraintErr)
    }
    os.Exit(1)
}

fmt.Println("Name from claims:", claims.Name)

Token building

Define own claims, embedding RegisteredClaims and implements encoding.BinaryMarshaler:

type myclaims struct {
	jwtee.RegisteredClaims

	Name  string `json:"name"`
	Admin bool   `json:"admin"`
}

// MarshalBinary implements encoding.BinaryMarshaler.
func (c myclaims) MarshalBinary() (data []byte, err error) {
	return json.Marshal(c)
}

Build token from claims:

secret := []byte("secret_code")

hmacSigner := signer.NewHS256()
key := jwtee.NewSharedSecretKey(secret)
builder := jwtee.NewTokenBuilder()

claims := myclaims{
    RegisteredClaims: jwtee.RegisteredClaims{
        Sub: "1234567890",
        Iat: 1516239022,
    },
    Name:  "John Doe",
    Admin: true,
}

tokenParts, err := builder.Build(claims, hmacSigner, key)
if err != nil {
    log.Fatalf("failed to build jwt: %v", err)
}

rawJWT, err := tokenParts.MarshalText()
if err != nil {
    log.Fatalf("failed to marshal token parts: %v", err)
}

fmt.Println(string(rawJWT))

More examples

Contributing

Pull requests are very much welcomed. Make sure a test or example is included that covers your change and your commits represent coherent changes that include a reason for the change.

Use gometalinter to check code with linters:

gometalinter -t --vendor ./...

# Packages

No description provided by the author
No description provided by the author
No description provided by the author

# Functions

NewClaimsValidator returns new instance of ClaimsValidator.
NewJSONParser returns new instance of JSONParser.
NewPartsVerifier returns new instance of PartsVerifier.
NewSharedSecretKey returns Key with secret inside.
NewTokenBuilder returns new instance of TokenBuilder.
NewVerifyingParser returns new instance of VerifyingParser.

# Constants

Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.
Algorithm constants represents available algorithms values.

# Variables

ErrInvalidSignature indicates that signature invalid.
ErrPartMissed indicates that token has invalid format.
ErrRequestedHashUnavailable indicates that hash func is not registered.

# Structs

ClaimsValidator used to validate RegisteredClaims with Constraints.
DecodedParts stores ready to use parts of the JWT token.
Header stores JWT header data.
JSONParser used to parse JWT token.
Key stores signing key data.
PartsVerifier used to verify signature of JWT.
RegisteredClaims are the IANA registered “JSON Web Token Claims”.
TokenBuilder implements Builder.
VerifyingParser used to parse and then verify JWT.

# Interfaces

Builder used to build encoded and signed token.
Constraint used to validate JWT Claims with Constraint.
Parser used to take JWT apart.
Signer used to sign and verify token signature.
Validator used to validate JWT Claims.

# Type aliases

Algorithm describes algorithms supported for signing/verifying.
Timestamp represents time as number of seconds from 1970-01-01T00:00:00Z UTC until the specified moment.