README.md

JWTee

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 ./...