1# Global Settings
2
3## Enabling Optional Signature Methods
4
5Some 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.
6To enable these, you must explicitly provide a build tag.
7
8| Algorithm | Build Tag |
9|:-----------------|:-----------|
10| secp256k1/ES256K | jwx_es256k |
11
12If 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.
13
14## Switching to a faster JSON library
15
16By default we use the standard library's `encoding/json` for all of our JSON needs.
17However, if performance for parsing/serializing JSON is really important to you, you might want to enable [github.com/goccy/go-json](https://github.com/goccy/go-json) by enabling the `jwx_goccy` tag.
18
19```shell
20% go build -tags jwx_goccy ...
21```
22
23[github.com/goccy/go-json](https://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".
24As of github.com/goccy/go-json@v0.3.3 I haven't see any problems, and I would say that it is mostly stable.
25
26However, 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.
27If you know what you are doing, I highly recommend enabling this module -- all you need to do is to enable this tag.
28Disable the tag if you feel like it's not worth the hassle.
29
30And when you *do* enable [github.com/goccy/go-json](https://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](https://github.com/goccy/go-json) and **NOT** to this library.
31
32## Using json.Number
33
34If you want to parse numbers in the incoming JSON objects as json.Number
35instead of floats, you can use the following call to globally affect the behavior of JSON parsing.
36
37```go
38func init() {
39 jwx.DecoderSettings(jwx.WithUseNumber(true))
40}
41```
42
43Do be aware that this has *global* effect. All code that calls in to `encoding/json`
44within `jwx` *will* use your settings.
45
46## Decode private fields to objects
47
48Packages within `github.com/lestrrat-go/jwx` parses known fields into pre-defined types,
49but for everything else (usually called private fields/headers/claims) are decoded into
50wharever `"encoding/json".Unmarshal` deems appropriate.
51
52For example, JSON objects are converted to `map[string]interface{}`, JSON arrays into
53`[]interface{}`, and so on.
54
55Sometimes you know beforehand that it makes sense for certain fields to be decoded into
56proper objects instead of generic maps or arrays. When you encounter this, you can use
57the `RegisterCustomField()` method in each of `jwe`, `jwk`, `jws`, and `jwt` packages.
58
59```go
60func init() {
61 jwt.RegisterCustomField(`x-foo-bar`, mypkg.FooBar{})
62}
63```
64
65This tells the decoder that when it encounters a JWT token with the field named
66`"x-foo-bar"`, it should be decoded to an instance of `mypkg.FooBar`. Then you can
67access this value by using `Get()`
68
69```go
70v, _ := token.Get(`x-foo-bar`)
71foobar := v.(mypkg.FooBar)
72```
73
74Do be aware that this has *global* effect. In the above example, all JWT tokens containing
75the `"x-foo-bar"` key will decode in the same way. If you need this behavior from
76`jwe`, `jwk`, or `jws` packages, you need to do the same thing for each package.
77
78
View as plain text