jwx

README

github.com/lestrrat-go/jwx

Command line tool jwx and libraries implementing various JWx technologies. Please click on the package names in the table below to find the synopsis/description for each package.

Package name	Notes
jwt	RFC 7519
jwk	RFC 7517 + RFC 7638
jwa	RFC 7518
jws	RFC 7515 + RFC 7797
jwe	RFC 7516

Index

• Documentation on pkg.go.dev
  • HTML version of what you can see using go doc command
• How-to style documentation
  • Frequently asked questions.
  • How to JWx That? Documentation by example.
• Overview of this package
  • Read on for more gory details.

Description

Why?

My goal was to write a server that heavily uses JWK and JWT. At first glance the libraries that already exist seemed sufficient, but soon I realized that

1. To completely implement the protocols, I needed the entire JWT, JWK, JWS, JWE (and JWA, by necessity).
2. Most of the libraries that existed only deal with a subset of the various JWx specifications that were necessary to implement their specific needs

For example, a certain library looks like it had most of JWS, JWE, JWK covered, but then it lacked the ability to include private claims in its JWT responses. Another library had support of all the private claims, but completely lacked in its flexibility to generate various different response formats.

Because I was writing the server side (and the client side for testing), I needed the entire JOSE toolset to properly implement my server, and they needed to be flexible enough to fulfill the entire spec that I was writing.

So here's github.com/lestrrat-go/jwx. This library is extensible, customizable, and hopefully well organized to the point that it is easy for you to slice and dice it.

Backwards Compatibility Notice

Users of github.com/lestrrat/go-jwx

Uh, why are you using such an ancient version? You know that repository is archived for a reason, yeah? Please use the new version.

Pre-1.0.0 users

The API has been reworked quite substantially between pre- and post 1.0.0 releases. Please check out the Changes file (or the diff, if you are into that sort of thing)

v1.0.x users

The API has gone under some changes for v1.1.0. If you are upgrading, you might want to read the relevant parts in the Changes file.

Command Line Tool

Since v1.1.1 we have a command line tool jwx (*). With jwx you can create JWKs (from PEM files, even), sign and verify JWS message, encrypt and decrypt JWE messages, etc.

(*) Okay, it existed since a long time ago, but it was never useful.

Installation

go install github.com/lestrrat-go/jwx/cmd/jwx

How-to style documentation

If you are looking for FAQs or want to look for ways to do X, you may have an easier time navigating through the documentation here

Global Settings

Allowing single element in 'aud' field

When you marshal "github.com/lestrrat-go/jwx/jwt".Token into JSON, by default the aud field is serialized as an array of strings. This field may take either a single string or array form, but apparently there are parsers that do not understand the array form.

The examples below shoud both be valid, but apparently there are systems that do not understand the former (AWS Cognito has been reported to be one such system).

{
  "aud": ["foo"],
  ...
}

{
  "aud": "foo",
  ...
}

To workaround these problematic parsers, you may use the jwt.Settings() function with the jwt.WithFlattenAudience(true) option.

func init() {
  jwt.Settings(jwt.WithFlattenAudience(true))
}

The above call will force all calls to marshal JWT tokens to flatten the aud field when it can. This has global effect.

Enabling ES256K

Some algorithms are intentionally left out because they are not as common in the wild, and you may want to avoid compiling this extra information in. To enable these, you must explicitly provide a build tag.

Algorithm	Build Tag
secp256k1/ES256K	jwx_es256k

If you do not provide these tags, the program will still compile, but it will return an error during runtime saying that these algorithms are not supported.

Switching to a faster JSON library

By default we use the standard library's encoding/json for all of our JSON needs. However, if performance for parsing/serializing JSON is really important to you, you might want to enable github.com/goccy/go-json by enabling the jwx_goccy tag.

% go build -tags jwx_goccy ...

github.com/goccy/go-json is disabled by default because it uses some really advanced black magic, and I really do not feel like debugging it IF it breaks. Please note that that's a big "if". As of github.com/goccy/go-json@v0.3.3 I haven't see any problems, and I would say that it is mostly stable.

However, it is a dependency that you can go without, and I won't be of much help if it breaks -- therefore it is not the default. If you know what you are doing, I highly recommend enabling this module -- all you need to do is to enable this tag. Disable the tag if you feel like it's not worth the hassle.

And when you do enable github.com/goccy/go-json and you encounter some mysterious error, I also trust that you know to file an issue to github.com/goccy/go-json and NOT to this library.

Using json.Number

If you want to parse numbers in the incoming JSON objects as json.Number instead of floats, you can use the following call to globally affect the behavior of JSON parsing.

func init() {
  jwx.DecoderSettings(jwx.WithUseNumber(true))
}

Do be aware that this has global effect. All code that calls in to encoding/json within jwx will use your settings.

Decode private fields to objects

Packages within github.com/lestrrat-go/jwx parses known fields into pre-defined types, but for everything else (usually called private fields/headers/claims) are decoded into wharever "encoding/json".Unmarshal deems appropriate.

For example, JSON objects are converted to map[string]interface{}, JSON arrays into []interface{}, and so on.

Sometimes you know beforehand that it makes sense for certain fields to be decoded into proper objects instead of generic maps or arrays. When you encounter this, you can use the RegisterCustomField() method in each of jwe, jwk, jws, and jwt packages.

func init() {
  jwt.RegisterCustomField(`x-foo-bar`, mypkg.FooBar{})
}

This tells the decoder that when it encounters a JWT token with the field named "x-foo-bar", it should be decoded to an instance of mypkg.FooBar. Then you can access this value by using Get()

v, _ := token.Get(`x-foo-bar`)
foobar := v.(mypkg.FooBar)

Do be aware that this has global effect. In the above example, all JWT tokens containing the "x-foo-bar" key will decode in the same way. If you need this behavior from jwe, jwk, or jws packages, you need to do the same thing for each package.

Other related libraries:

• https://github.com/dgrijalva/jwt-go
• https://github.com/square/go-jose
• https://github.com/coreos/go-oidc
• https://pkg.go.dev/golang.org/x/oauth2

Contributions

Issues

For bug reports and feature requests, please try to follow the issue templates as much as possible. For either bug reports or feature requests, failing tests are even better.

Pull Requests

Please make sure to include tests that excercise the changes you made.

If you are editing auto-generated files (those files with the _gen.go prefix, please make sure that you do the following:

1. Edit the generator, not the generated files (e.g. internal/cmd/genreadfile/main.go)
2. Run make generate (or go generate) to generate the new code
3. Commit both the generator and the generated files

Discussions / Usage

Please try discussions first.

Credits

• Work on this library was generously sponsored by HDE Inc (https://www.hde.co.jp)
• Lots of code, especially JWE was taken from go-jose library (https://github.com/square/go-jose)
• Lots of individual contributors have helped this project over the years. Thank each and everyone of you very much.

Documentation

Overview

Package jwx contains tools that deal with the various JWx (JOSE) technologies such as JWT, JWS, JWE, etc in Go.

JWS (https://tools.ietf.org/html/rfc7515)
JWE (https://tools.ietf.org/html/rfc7516)
JWK (https://tools.ietf.org/html/rfc7517)
JWA (https://tools.ietf.org/html/rfc7518)
JWT (https://tools.ietf.org/html/rfc7519)

The primary focus of this library tool set is to implement the extremely flexible OAuth2 / OpenID Connect protocols.

Examples are stored in a separate Go module (to avoid adding dependencies to this module), and thus does not appear in the online documentation for this module. You can find the examples in Github at https://github.com/lestrrat-go/jwx/examples

You can find more high level documentation at Github (https://github.com/lestrrat-go/jwx)

Index

• func DecoderSettings(options ...JSONOption)
• type FormatKind
  • func GuessFormat(payload []byte) FormatKind
  • func (i FormatKind) String() string
• type JSONOption
  • func WithUseNumber(b bool) JSONOption
• type Option

Functions

func DecoderSettings

func DecoderSettings(options ...JSONOption)

DecoderSettings gives you a access to configure the "encoding/json".Decoder used to decode JSON objects within the jwx framework.

Types

type FormatKind

type FormatKind int

const (
	UnknownFormat FormatKind = iota
	JWE
	JWS
	JWK
	JWKS
	JWT
)

func GuessFormat

func GuessFormat(payload []byte) FormatKind

GuessFormat is used to guess the format the given payload is in using heuristics. See the type FormatKind for a full list of possible types.

This may be useful in determining your next action when you may encounter a payload that could either be a JWE, JWS, or a plain JWT.

Because JWTs are almost always JWS signed, you may be thrown off if you pass what you think is a JWT payload to this function. If the function is in the "Compact" format, it means it's a JWS signed message, and its payload is the JWT. Therefore this function will reuturn JWS, not JWT.

This function requires an extra parsing of the payload, and therefore may be inefficient if you call it every time before parsing.

func (FormatKind) String

func (i FormatKind) String() string

type JSONOption

type JSONOption interface {
	Option
	// contains filtered or unexported methods
}

func WithUseNumber

func WithUseNumber(b bool) JSONOption

WithUseNumber controls whether the jwx package should unmarshal JSON objects with the "encoding/json".Decoder.UseNumber feature on.

Default is false.

type Option

type Option = option.Interface