:doctype: book = Java JWT: JSON Web Token for Java and Android :project-version: 0.13.0 :toc: :toc-title: :toc-placement!: :toclevels: 4

ifdef::env-github[] :tip-caption: ✏️TIP :note-caption: ℹ️ NOTE :important-caption: ‼️IMPORTANT :caution-caption: ⛔️CAUTION :warning-caption: ⚠️WARNING endif::[]

// Macros :fn-require-java8-plus: Requires Java 8 or a compatible JCA Provider (like BouncyCastle) in the runtime classpath. :fn-require-java11-plus: Requires Java 11 or a compatible JCA Provider (like BouncyCastle) in the runtime classpath. :fn-require-java15-plus: Requires Java 15 or a compatible JCA Provider (like BouncyCastle) in the runtime classpath.

image:https://github.com/jwtk/jjwt/actions/workflows/ci.yml/badge.svg?branch=master[Build Status,link=https://github.com/jwtk/jjwt/actions/workflows/ci.yml?query=branch%3Amaster] image:https://coveralls.io/repos/github/jwtk/jjwt/badge.svg?branch=master[Coverage Status,link=https://coveralls.io/github/jwtk/jjwt?branch=master] image:https://snyk-widget.herokuapp.com/badge/mvn/io.jsonwebtoken/jjwt-root/badge.svg[Vuln score,link=https://snyk-widget.herokuapp.com/badge/mvn/io.jsonwebtoken/jjwt-root/badge.svg] image:https://snyk.io/test/github/jwtk/jjwt/badge.svg[Known Vulns,link=https://snyk.io/test/github/jwtk/jjwt/badge.svg]

JJWT aims to be the easiest to use and understand library for creating and verifying JSON Web Tokens (JWTs) and JSON Web Keys (JWKs) on the JVM and Android.

JJWT is a pure Java implementation based exclusively on the https://datatracker.ietf.org/wg/jose/documents/[JOSE Working Group] RFC specifications:

• https://tools.ietf.org/html/rfc7519[RFC 7519: JSON Web Token (JWT)]
• https://tools.ietf.org/html/rfc7515[RFC 7515: JSON Web Signature (JWS)]
• https://tools.ietf.org/html/rfc7516[RFC 7516: JSON Web Encryption (JWE)]
• https://tools.ietf.org/html/rfc7517[RFC 7517: JSON Web Key (JWK)]
• https://tools.ietf.org/html/rfc7518[RFC 7518: JSON Web Algorithms (JWA)]
• https://www.rfc-editor.org/rfc/rfc7638.html[RFC 7638: JSON Web Key Thumbprint]
• https://www.rfc-editor.org/rfc/rfc9278.html[RFC 9278: JSON Web Key Thumbprint URI]
• https://www.rfc-editor.org/rfc/rfc7797.html[RFC 7797: JWS Unencoded Payload Option]
• https://www.rfc-editor.org/rfc/rfc8037[RFC 8037: Edwards Curve algorithms and JWKs]

It was created by https://github.com/lhazlewood[Les Hazlewood] and is supported and maintained by a https://github.com/jwtk/jjwt/graphs/contributors[community] of contributors.

JJWT is open source under the terms of the http://www.apache.org/licenses/LICENSE-2.0[Apache 2.0 License].

==== [discrete] == Table of Contents

toc::[]

+++<a name="features">++++++</a>+++

== Features

• Fully functional on all Java 7+ JDKs and Android
• Automatic security best practices and assertions
• Easy to learn and read API
• Convenient and readable http://en.wikipedia.org/wiki/Fluent_interface[fluent] interfaces, great for IDE auto-completion to write code quickly
• Fully RFC specification compliant on all implemented functionality, tested against RFC-specified test vectors
• Stable implementation with almost 1,700 tests and enforced 100% test code coverage. Every single method, statement and conditional branch variant in the entire codebase is tested and required to pass on every build.
• Creating, parsing and verifying digitally signed compact JWTs (aka JWSs) with all standard JWS algorithms:

|=== | Identifier | Signature Algorithm

| HS256 | HMAC using SHA-256

| HS384 | HMAC using SHA-384

| HS512 | HMAC using SHA-512

| ES256 | ECDSA using P-256 and SHA-256

| ES384 | ECDSA using P-384 and SHA-384

| ES512 | ECDSA using P-521 and SHA-512

| RS256 | RSASSA-PKCS-v1_5 using SHA-256

| RS384 | RSASSA-PKCS-v1_5 using SHA-384

| RS512 | RSASSA-PKCS-v1_5 using SHA-512

| PS256 | RSASSA-PSS using SHA-256 and MGF1 with SHA-256^1^

| PS384 | RSASSA-PSS using SHA-384 and MGF1 with SHA-384^1^

| PS512 | RSASSA-PSS using SHA-512 and MGF1 with SHA-512^1^

| EdDSA | Edwards-curve Digital Signature Algorithm^2^ |=== + ^1.{sp}{fn-require-java11-plus}^ + ^2.{sp}{fn-require-java15-plus}^

• Creating, parsing and decrypting encrypted compact JWTs (aka JWEs) with all standard JWE encryption algorithms:

|=== | Identifier | Encryption Algorithm

| A128CBC‑HS256 | https://www.rfc-editor.org/rfc/rfc7518.html#section-5.2.3[AES_128_CBC_HMAC_SHA_256] authenticated encryption algorithm

| A192CBC-HS384 | https://www.rfc-editor.org/rfc/rfc7518.html#section-5.2.4[AES_192_CBC_HMAC_SHA_384] authenticated encryption algorithm

| A256CBC-HS512 | https://www.rfc-editor.org/rfc/rfc7518.html#section-5.2.5[AES_256_CBC_HMAC_SHA_512] authenticated encryption algorithm

| A128GCM | AES GCM using 128-bit key^1^

| A192GCM | AES GCM using 192-bit key^1^

| A256GCM | AES GCM using 256-bit key^1^ |=== + ^1.{sp}{fn-require-java8-plus}^

• All Key Management Algorithms for obtaining JWE encryption and decryption keys:

|=== | Identifier | Key Management Algorithm

| RSA1_5 | RSAES-PKCS1-v1_5

| RSA-OAEP | RSAES OAEP using default parameters

| RSA-OAEP-256 | RSAES OAEP using SHA-256 and MGF1 with SHA-256

| A128KW | AES Key Wrap with default initial value using 128-bit key

| A192KW | AES Key Wrap with default initial value using 192-bit key

| A256KW | AES Key Wrap with default initial value using 256-bit key

| dir | Direct use of a shared symmetric key as the CEK

| ECDH-ES | Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF

| ECDH-ES+A128KW | ECDH-ES using Concat KDF and CEK wrapped with "A128KW"

| ECDH-ES+A192KW | ECDH-ES using Concat KDF and CEK wrapped with "A192KW"

| ECDH-ES+A256KW | ECDH-ES using Concat KDF and CEK wrapped with "A256KW"

| A128GCMKW | Key wrapping with AES GCM using 128-bit key^1^

| A192GCMKW | Key wrapping with AES GCM using 192-bit key^1^

| A256GCMKW | Key wrapping with AES GCM using 256-bit key^1^

| PBES2-HS256+A128KW | PBES2 with HMAC SHA-256 and "A128KW" wrapping^1^

| PBES2-HS384+A192KW | PBES2 with HMAC SHA-384 and "A192KW" wrapping^1^

| PBES2‑HS512+A256KW | PBES2 with HMAC SHA-512 and "A256KW" wrapping^1^ |=== + ^1.{sp}{fn-require-java8-plus}^

• Creating, parsing and verifying JSON Web Keys (JWKs) in all standard JWA key formats using native Java Key types:

|=== | JWK Key Format | Java Key Type | JJWT Jwk Type

| Symmetric Key | SecretKey | SecretJwk

| Elliptic Curve Public Key | ECPublicKey | EcPublicJwk

| Elliptic Curve Private Key | ECPrivateKey | EcPrivateJwk

| RSA Public Key | RSAPublicKey | RsaPublicJwk

| RSA Private Key | RSAPrivateKey | RsaPrivateJwk

| XDH Private Key | XECPublicKey^1^ | OctetPublicJwk

| XDH Private Key | XECPrivateKey^1^ | OctetPrivateJwk

| EdDSA Public Key | EdECPublicKey^2^ | OctetPublicJwk

| EdDSA Private Key | EdECPublicKey^2^ | OctetPrivateJwk |=== + ^1.{sp}{fn-require-java15-plus}^ + ^2.{sp}{fn-require-java15-plus}^

• Convenience enhancements beyond the specification such as ** Payload compression for any large JWT, not just JWEs ** Claims assertions (requiring specific values) ** Claim POJO marshaling and unmarshalling when using a compatible JSON parser (e.g. Jackson) ** Secure Key generation based on desired JWA algorithms ** and more...

+++<a name="features-unsupported">++++++</a>+++

=== Currently Unsupported Features

• https://tools.ietf.org/html/rfc7515#section-7.2[Non-compact] serialization and parsing.

This feature may be implemented in a future release. Community contributions are welcome!

+++<a name="community">++++++</a>+++

== Community

+++<a name="help">++++++</a>+++

=== Getting Help

If you have trouble using JJWT, please first read the documentation on this page before asking questions. We try very hard to ensure JJWT's documentation is robust, categorized with a table of contents, and up to date for each release.

+++<a name="help-questions">++++++</a>+++

==== Questions

If the documentation or the API JavaDoc isn't sufficient, and you either have usability questions or are confused about something, please https://github.com/jwtk/jjwt/discussions/new?category=q-a[ask your question here]. However:

Please do not create a GitHub issue to ask a question.

We use GitHub Issues to track actionable work that requires changes to JJWT's design and/or codebase. If you have a usability question, instead please https://github.com/jwtk/jjwt/discussions/new?category=q-a[ask your question here], and we can convert that to an issue if necessary.

If a GitHub Issue is created that does not represent actionable work for JJWT's codebase, it will be promptly closed.

+++<a name="help-issues">++++++</a>+++

==== Bugs, Feature Requests, Ideas and General Discussions

If you do not have a usability question and believe you have a legitimate bug or feature request, please https://github.com/jwtk/jjwt/discussions[discuss it here] FIRST. Please do a quick search first to see if an existing discussion related to yours exist already and join that existing discussion if necesary.

If you feel like you'd like to help fix a bug or implement the new feature yourself, please read the Contributing section next before starting any work.

+++<a name="contributing">++++++</a>+++

=== Contributing

+++<a name="contributing-pull-requests">++++++</a>+++

==== Pull Requests

Simple Pull Requests that fix anything other than JJWT core code (documentation, JavaDoc, typos, test cases, etc) are always appreciated and have a high likelihood of being merged quickly. Please send them!

However, if you want or feel the need to change JJWT's functionality or core code, please do not issue a pull request without https://github.com/jwtk/jjwt/discussions[starting a new JJWT discussion] and discussing your desired changes first, before you start working on it.

It would be a shame to reject your earnest and genuinely-appreciated pull reque