Home

Awesome

API Documentation Build Status

About

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

The API enforces secure use by design. Unsigned tokens are rejected. No support for encrypted tokens either—use wire encryption instead.

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

Introduction

Tokens encapsulate signed statements called claims. A claim is a named JSON value. Applications using JWTs should define which specific claims they use and when they are required or optional.

var claims jwt.Claims
claims.Subject = "alice"
claims.Issued  = jwt.NewNumericTime(time.Now().Round(time.Second))
claims.Set     = map[string]interface{}{"email_verified": false}
// issue a JWT
token, err := claims.EdDSASign(JWTPrivateKey)

Tokens consists of printable ASCII characters, e.g., eyJhbGciOiJFUzI1NiJ9.eyJzdWIiOiJha3JpZWdlciIsInByZWZpeCI6IkRyLiJ9.RTOboYsLW7zXFJyXtIypOmXfuRGVT_FpDUTs2TOuK73qZKm56JcESfsl_etnBsl7W80TXE5l5qecrMizh3XYmw. Secured resources can use such tokens to determine the respective permissions. Note how the verification process is self-contained with just a public key.

// verify a JWT
claims, err := jwt.EdDSACheck(token, JWTPublicKey)
if err != nil {
	log.Print("credentials rejected: ", err)
	return
}
err = claims.AcceptTemporal(time.Now(), time.Second)
if err != nil {
	log.Print("credential constraints violated: ", err)
	return
}

// ready for use
log.Print("hello ", claims.Subject)
if verified, _ := claims.Set["email_verified"].(bool); !verified {
	log.Print("e-mail confirmation pending")
}

Commonly, agents receive a JWT uppon authentication/login. Then, that token is included with requests to the secured resources, as a proof of authority. Token access is “eyes only” in such scenario. Include and enforce more context detail with claims to further reduce risk. E.g., a session identifier or a fingerprint of the client's TLS key can prevent usage of any hijacked tokens.

High-Level API

Server-side security can be applied with a standard http.Handler setup. The following example denies requests to MyAPI when the JWT is not valid, or when the JWT is missing either the subject, formatted name or roles claim.

// define trusted credentials
var keys jwt.KeyRegister
n, err := keys.LoadPEM(text, nil)
if err != nil {
	log.Fatal(err)
}
log.Print("setup with ", n, " JWT keys")

http.Handle("/api/v1", &jwt.Handler{
	Target: MyAPI, // protected HTTP handler
	Keys:   &keys,

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

	// map another claim with custom logic
	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.Audiences)

		// 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!\n", req.Header.Get("X-Verified-Name"))
	fmt.Fprintf(w, "You are authorized as %s.\n", req.Header.Get("X-Verified-User"))
}

The validated Claims object may also be exposed through the request context.

Performance

The following results were measured with Go 1.20.3 on an Apple M1.

ECDSA/sign-ES256-8         19.88µ ± 0%
ECDSA/sign-ES384-8         182.2µ ± 0%
ECDSA/check-ES256-8        58.65µ ± 0%
ECDSA/check-ES384-8        535.2µ ± 0%
EdDSA/sign-EdDSA-8         21.30µ ± 1%
EdDSA/check-EdDSA-8        47.12µ ± 1%
HMAC/sign-HS256-8          660.1n ± 0%
HMAC/sign-HS256-reuse-8    458.3n ± 1%
HMAC/sign-HS384-8          1.028µ ± 0%
HMAC/sign-HS384-reuse-8    600.4n ± 0%
HMAC/sign-HS512-8          1.053µ ± 0%
HMAC/sign-HS512-reuse-8    616.6n ± 0%
HMAC/check-HS256-8         1.826µ ± 0%
HMAC/check-HS256-reuse-8   1.611µ ± 1%
HMAC/check-HS384-8         2.271µ ± 1%
HMAC/check-HS384-reuse-8   1.786µ ± 1%
HMAC/check-HS512-8         2.287µ ± 1%
HMAC/check-HS512-reuse-8   1.803µ ± 0%
RSA/sign-1024-bit-8        292.8µ ± 1%
RSA/sign-2048-bit-8        1.273m ± 0%
RSA/sign-4096-bit-8        8.685m ± 1%
RSA/check-1024-bit-8       49.51µ ± 3%
RSA/check-2048-bit-8       168.6µ ± 0%
RSA/check-4096-bit-8       662.6µ ± 0%

EdDSA [Ed25519] produces small signatures and it performs well.

Standard Compliance

JWT.io