lestrrat-go/jwx

The jwt package provides an implementation of JSON Web Tokens (JWT) compliant with RFC 7519. It is designed for creating, parsing, and validating JWTs in Go applications.

For detailed how-to guides and practical code examples, refer to the Working with JWT documentation.

If you require OpenID Connect (OIDC) support, use the jwt/openid subpackage.

The github.com/lestrrat-go/jwx/v4 library provides tools for performing Javascript Object Signing and Encryption (JOSE) operations in Go. You can find detailed code examples and guides for specific JOSE components in the documentation:

• JWT: Working with JSON Web Tokens.
• JWS: Working with JSON Web Signatures.
• JWE: Working with JSON Web Encryption.
• JWK: Working with JSON Web Keys.
• Extensions: Using extension modules.
• Global Settings: Configuring global library settings.
• Framework Integration: Integrating the library with existing frameworks.

In versions v3 and later, most convenience accessors (e.g., (jwt.Token).Subject, (jws.Signed).Algorithm, or (jwk.Key).Algorithm) have changed their return type. They no longer return the value directly; instead, they return a tuple of (T, bool) to indicate if the value was present.

If you require a single return value without the boolean check, use the Get(dst) method instead.

Note: jwk.Key.KeyType is an exception and continues to always return a valid value.

A JWT is a payload contained within a JWS envelope. Because JWS headers are part of the envelope and not the payload, they are not accessible via the jwt.Token object.

To access JWS headers (for example, to determine which key to use for verification), you must use the tools provided in the jws package. If you need to decide on a key based on header fields, consider using a jwt.KeyProvider.

JWE (RFC7516) is used to encrypt arbitrary payloads and is implemented in the github.com/lestrrat-go/jwx/v4/jwe package.

Like JWS, JWE supports two formats:

1. A format consisting of 5 base64 encoded strings concatenated by a single period (.).
2. A JSON object format.

Example of a JWE message:

eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTE5MkdDTSIsImVwayI6eyJjcnYiOiJQLTI1NiIsImt0eSI6IkVDIiwieCI6IndMckhLNnBTLXZzdmhQZUNfNTN0ZWpxYzZIZUFsMllRWDRmY1hPNGV1bmciLCJ5IjoiV2V3bFdKazJ4QWJYSXE3WFJ6aVlZa2lxMjJfOF9TQ0VsbTA1Vm1iUGhFWSJ9fQ..7UTcbVpz-Ed1Q0wq.sneVfeTeAvzZNSMGpQ.JNo1BbDaKB-Q1mWaBNmdow

In the context of github.com/lestrrat-go/jwx/v4/jwt, it is important to distinguish between these two processes:

• Verification: The process of ensuring the integrity of the JWT by checking its signature (e.g., using JWS verification).
• Validation: The process of checking the contents of the JWT, such as verifying if claims like iss (issuer), sub (subject), or aud (audience) match expected values, and checking if the token has expired.

Note that jwt.Parse() performs signature verification but does not perform validation by default. To perform validation, you must explicitly call Validate() on the resulting token.

The genjwt tool is a code generator used to create JWT (JSON Web Token) related Go code. It generates interfaces, structs, constructors, getters, and methods like Has, Get, Set, Remove, UnmarshalJSON, MarshalJSON, Keys, and a Claims iterator.

Key technical characteristics of the generated code include:

• Multi-package support: It can target both jwt and openid packages. If targeting openid, it prepends jwt. to cross-package type references.
• Specialized Marshaling: It handles specific JWT field types with custom logic:
  • audience: Uses json.MarshalAudience with flattening options.
  • types.NumericDate: Converted to a Unix timestamp via .Unix().
  • []byte: Encoded as a Base64 string.
  • Other types: Standard JSON marshaling.
• Claims Iteration: Uses Go 1.22+ iter.Seq2 for the Claims() method.

In v4, optional features (like specific signature algorithms or encryption schemes) are provided as standalone modules under the github.com/jwx-go prefix.

To use an extension, you simply import the module for its side effects. Each module uses an init() function to automatically register its algorithms, key importers, and exporters with the core jwx library.

Warning: Extension modules will panic during init() if registration fails. This is a design choice to ensure that if an extension is imported but cannot be correctly registered, the application fails immediately at startup rather than failing later during a cryptographic operation.