JSON Web Token library
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.travis.yml Drop Coveralls. Apr 3, 2018
LICENSE Link the CC0 legal text to the license file. Jun 28, 2018
README.md
bench_test.go Support ECDSA. Aug 24, 2018
check.go Minimal JOSE header support: reject extensions & key ID access. Nov 16, 2018
check_test.go Minimal JOSE header support: reject extensions & key ID access. Nov 16, 2018
examples_test.go
extend_test.go Simplify example tests for readability. Nov 15, 2018
jwt.go Minimal JOSE header support: reject extensions & key ID access. Nov 16, 2018
jwt_test.go Simplify example tests for readability. Nov 15, 2018
keys_test.go
register.go Add certificate support to PEM load. Nov 15, 2018
register_test.go Minor PEM consistencies in tests. Nov 16, 2018
sign.go Minimal JOSE header support: reject extensions & key ID access. Nov 16, 2018
sign_test.go Minimal JOSE header support: reject extensions & key ID access. Nov 16, 2018
web.go Rename pool misnomer. Sep 28, 2018
web_test.go Rename pool misnomer. Sep 28, 2018

README.md

API Documentation Build Status Test Coverage

A JSON Web Token (JWT) library for the Go programming language.

The API enforces secure use by design. Unsigned tokens are rejected and there is no support for encryption—use wire encryption instead. With about 700 lines of code and no third party dependencies, the implementation maintains full unit test coverage.

This is free and unencumbered software released into the public domain.

Get Started

The package comes with functions to verify [ECDSACheck, HMACCheck, RSACheck] and issue [ECDSASign, HMACSign, RSASign] claims.

For server side security an http.Handler based setup can be used as well. The following example enforces the subject, formatted name and roles to be present as a valid JWT in all requests towards the MyAPI handler.

// configuration demo
http.DefaultServeMux.Handle("/api/v1", &jwt.Handler{
	Target: MyAPI, // the protected service multiplexer
	RSAKey: JWTPublicKey,

	// map some claims to HTTP headers
	HeaderBinding: map[string]string{
		"sub": "X-Verified-User", // registered [standard] claim
		"fn":  "X-Verified-Name", // private [custom] claim
	},

	// customise further with RBAC
	Func: func(w http.ResponseWriter, req *http.Request, claims *jwt.Claims) (pass bool) {
		log.Printf("got a valid JWT %q for %q", claims.ID, claims.Audience)

		// map role enumeration
		s, ok := claims.String("roles")
		if !ok {
			http.Error(w, "jwt: want roles claim as a string", http.StatusForbidden)
			return false
		}
		req.Header["X-Verified-Roles"] = strings.Fields(s)

		return true
	},
})

When all applicable JWT claims are mapped to HTTP request headers, then the service logic can stay free of verification code plus easier unit testing.

// Greeting is a standard HTTP handler fuction.
func Greeting(w http.ResponseWriter, req *http.Request) {
	fmt.Fprintf(w, "Hello %s!\nYou are authorized as %s.\n",
		req.Header.Get("X-Verified-Name"), req.Header.Get("X-Verified-User"))
}

Optionally one can use the claims object in the service handlers as shown in the “direct” example.

Performance on a Mac Pro (late 2013)

BenchmarkECDSASign/ES256-12         	   50000	     38114 ns/op
BenchmarkECDSASign/ES384-12         	     300	   4279447 ns/op
BenchmarkECDSASign/ES512-12         	     200	   8064569 ns/op
BenchmarkECDSACheck/ES256-12        	   10000	    105350 ns/op
BenchmarkECDSACheck/ES384-12        	     200	   8331596 ns/op
BenchmarkECDSACheck/ES512-12        	     100	  16024017 ns/op
BenchmarkHMACSign/HS256-12          	  500000	      3498 ns/op
BenchmarkHMACSign/HS384-12          	  300000	      4071 ns/op
BenchmarkHMACSign/HS512-12          	  300000	      4144 ns/op
BenchmarkHMACCheck/HS256-12         	  200000	      6834 ns/op
BenchmarkHMACCheck/HS384-12         	  200000	      7543 ns/op
BenchmarkHMACCheck/HS512-12         	  200000	      7622 ns/op
BenchmarkRSASign/1024-bit-12        	    3000	    424131 ns/op
BenchmarkRSASign/2048-bit-12        	    1000	   2102947 ns/op
BenchmarkRSASign/4096-bit-12        	     100	  12877484 ns/op
BenchmarkRSACheck/1024-bit-12       	   50000	     32982 ns/op
BenchmarkRSACheck/2048-bit-12       	   20000	     73431 ns/op
BenchmarkRSACheck/4096-bit-12       	   10000	    201450 ns/op

JWT.io