• Non-compact serialization and parsing.

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

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.

Once you have a payload and header, how are they compacted for web transmission, and what does the final JWT actually look like? Let’s walk through a simplified version of the process with some pseudocode:

1. Assume we have a JWT with a JSON header and a simple text message payload:

   header

   {
     "alg": "none"
   }

   payload

   The true sign of intelligence is not knowledge but imagination.

2. Remove all unnecessary whitespace in the JSON:

   String header = '{"alg":"none"}'
   String payload = 'The true sign of intelligence is not knowledge but imagination.'

3. Get the UTF-8 bytes and Base64URL-encode each:

   String encodedHeader = base64URLEncode( header.getBytes("UTF-8") )
   String encodedPayload = base64URLEncode( payload.getBytes("UTF-8") )

4. Join the encoded header and claims with period ('.') characters:

   String compact = encodedHeader + '.' + encodedPayload + '.'

The final concatenated compact JWT String looks like this:

This is called an 'unprotected' JWT because no security was involved - no digital signatures or encryption to 'protect' the JWT to ensure it cannot be changed by 3rd parties.

If we wanted to digitally sign the compact form so that we could at least guarantee that no-one changes the data without us detecting it, we’d have to perform a few more steps, shown next.

Instead of a plain text payload, the next example will use probably the most common type of payload - a JSON claims Object containing information about a particular identity. We’ll also digitally sign the JWT to ensure it cannot be changed by a 3rd party without us knowing.

1. Assume we have a JSON header and a claims payload:

   header

   {
     "alg": "HS256"
   }

   payload

   {
     "sub": "Joe"
   }

   In this case, the header indicates that the HS256 (HMAC using SHA-256) algorithm will be used to cryptographically sign the JWT. Also, the payload JSON object has a single claim, sub with value Joe.

   There are a number of standard claims, called Registered Claims, in the specification and sub (for 'Subject') is one of them.

2. Remove all unnecessary whitespace in both JSON objects:

   String header = '{"alg":"HS256"}'
   String claims = '{"sub":"Joe"}'

3. Get their UTF-8 bytes and Base64URL-encode each:

   String encodedHeader = base64URLEncode( header.getBytes("UTF-8") )
   String encodedClaims = base64URLEncode( claims.getBytes("UTF-8") )

4. Concatenate the encoded header and claims with a period character '.' delimiter:

   String concatenated = encodedHeader + '.' + encodedClaims

5. Use a sufficiently-strong cryptographic secret or private key, along with a signing algorithm of your choice (we’ll use HMAC-SHA-256 here), and sign the concatenated string:

    SecretKey key = getMySecretKey()
    byte[] signature = hmacSha256( concatenated, key )

6. Because signatures are always byte arrays, Base64URL-encode the signature and join it to the concatenated string with a period character '.' delimiter:

   String compact = concatenated + '.' + base64URLEncode( signature )

And there you have it, the final compact String looks like this:

This is called a 'JWS' - short for signed JWT.

Of course, no one would want to do this manually in code, and worse, if you get anything wrong, you could introduce serious security problems and weaknesses. As a result, JJWT was created to handle all of this for you: JJWT completely automates both the creation of JWSs and the parsing and verification of JWSs for you.

So far we have seen an unprotected JWT and a cryptographically signed JWT (called a 'JWS'). One of the things that is inherent to both of these two is that all the information within them can be seen by anyone - all the data in both the header and the payload is publicly visible. JWS just ensures the data hasn’t been changed by anyone - it doesn’t prevent anyone from seeing it. Many times, this is just fine because the data within them is not sensitive information.

But what if you needed to represent information in a JWT that is considered sensitive information - maybe someone’s postal address or social security number or bank account number?

In these cases, we’d want a fully-encrypted JWT, called a 'JWE' for short. A JWE uses cryptography to ensure that the payload remains fully encrypted and authenticated so unauthorized parties cannot see data within, nor change the data without being detected. Specifically, the JWE specification requires that Authenticated Encryption with Associated Data algorithms are used to fully encrypt and protect data.

A full overview of AEAD algorithms are out of scope for this documentation, but here’s an example of a final compact JWE that utilizes these algorithms (line breaks are for readability only):

Next we’ll cover how to install JJWT in your project, and then we’ll see how to use JJWT’s nice fluent API instead of risky string manipulation to quickly and safely build JWTs, JWSs, and JWEs.

If you’re building a (non-Android) JDK project, you will want to define the following dependencies:

Android projects will want to define the following dependencies and Proguard exclusions, and optional BouncyCastle Provider:

Notice the above JJWT dependency declarations all have only one compile-time dependency and the rest are declared as runtime dependencies.

This is because JJWT is designed so you only depend on the APIs that are explicitly designed for you to use in your applications and all other internal implementation details - that can change without warning - are relegated to runtime-only dependencies. This is an extremely important point if you want to ensure stable JJWT usage and upgrades over time:

This is done to benefit you: great care goes into curating the jjwt-api .jar and ensuring it contains what you need and remains backwards compatible as much as is possible so you can depend on that safely with compile scope. The runtime jjwt-impl .jar strategy affords the JJWT developers the flexibility to change the internal packages and implementations whenever and however necessary. This helps us implement features, fix bugs, and ship new releases to you more quickly and efficiently.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.1KP0SsvENi7Uz1oQc07aXTL7kpQG5jBNIybqr60AlD4

A JWT header is a JSON Object that provides metadata about the contents, format, and any cryptographic operations relevant to the JWT payload. JJWT provides a number of ways of setting the entire header and/or multiple individual header parameters (name/value pairs).

A JWT payload can be anything at all - anything that can be represented as a byte array, such as text, images, documents, and more. But since a JWT header is always JSON, it makes sense that the payload could also be JSON, especially for representing identity claims.

As a result, the JwtBuilder supports two distinct payload options:

• content if you would like the payload to be arbitrary byte array content, or

• claims (and supporting helper methods) if you would like the payload to be a JSON Claims Object.

Either option may be used, but not both. Using both will cause compact() to throw an exception.

If your JWT payload is large (contains a lot of data), you might want to compress the JWT to reduce its size. Note that this is not a standard feature for all JWTs - only JWEs - and is not likely to be supported by other JWT libraries for non-JWE tokens. JJWT supports compression for both JWSs and JWEs, however.

Please see the main Compression section to see how to compress and decompress JWTs.

If the JWT parsed is a JWS or JWE, a key will be necessary to verify the signature or decrypt it. If a JWS and signature verification fails, or if a JWE and decryption fails, the JWT cannot be safely trusted and should be discarded.

So which key do we use?

• If parsing a JWS and the JWS was signed with a SecretKey, the same SecretKey should be specified on the JwtParserBuilder. For example:

  Jwts.parser()
  
    .verifyWith(secretKey) // <----
  
    .build()
    .parseSignedClaims(jwsString);

• If parsing a JWS and the JWS was signed with a PrivateKey, that key’s corresponding PublicKey (not the PrivateKey) should be specified on the JwtParserBuilder. For example:

  Jwts.parser()
  
    .verifyWith(publicKey) // <---- publicKey, not privateKey
  
    .build()
    .parseSignedClaims(jwsString);

• If parsing a JWE and the JWE was encrypted with direct encryption using a SecretKey, the same SecretKey should be specified on the JwtParserBuilder. For example:

  Jwts.parser()
  
    .decryptWith(secretKey) // <---- or a Password from Keys.password(charArray)
  
    .build()
    .parseEncryptedClaims(jweString);

• If parsing a JWE and the JWE was encrypted with a key algorithm using with a PublicKey, that key’s corresponding PrivateKey (not the PublicKey) should be specified on the JwtParserBuilder. For example:

  Jwts.parser()
  
    .decryptWith(privateKey) // <---- privateKey, not publicKey
  
    .build()
    .parseEncryptedClaims(jweString);

It is common in many applications to receive JWTs that can be encrypted or signed by different cryptographic keys. For example, maybe a JWT created to assert a specific user identity uses a Key specific to that exact user. Or perhaps JWTs specific to a particular customer all use that customer’s Key. Or maybe your application creates JWTs that are encrypted with a key specific to your application for your own use (e.g. a user session token).

In all of these and similar scenarios, you won’t know which key was used to sign or encrypt a JWT until the JWT is received, at parse time, so you can’t 'hard code' any verification or decryption key using the JwtParserBuilder's verifyWith or decryptWith methods. Those are only to be used when the same key is used to verify or decrypt all JWSs or JWEs, which won’t work for dynamically signed or encrypted JWTs.

You can enforce that the JWT you are parsing conforms to expectations that you require and are important for your application.

For example, let’s say that you require that the JWT you are parsing has a specific sub (subject) value, otherwise you may not trust the token. You can do that by using one of the various require* methods on the JwtParserBuilder:

If it is important to react to a missing vs an incorrect value, instead of catching InvalidClaimException, you can catch either MissingClaimException or IncorrectClaimException:

You can also require custom claims by using the require(claimName, requiredValue) method - for example:

(or, again, you could catch either MissingClaimException or IncorrectClaimException instead).

Please see the JwtParserBuilder class and/or JavaDoc for a full list of the various require* methods you may use for claims assertions.

When parsing a JWT, you might find that exp or nbf claim assertions fail (throw exceptions) because the clock on the parsing machine is not perfectly in sync with the clock on the machine that created the JWT. This can cause obvious problems since exp and nbf are time-based assertions, and clock times need to be reliably in sync for shared assertions.

You can account for these differences (usually no more than a few minutes) when parsing using the JwtParserBuilder's clockSkewSeconds. For example:

This ensures that minor clock differences between the machines can be ignored. Two or three minutes should be more than enough; it would be fairly strange if a production machine’s clock was more than 5 minutes difference from most atomic clocks around the world.

If you used JJWT to compress a JWT and you used a custom compression algorithm, you will need to tell the JwtParserBuilder how to resolve your CompressionAlgorithm to decompress the JWT.

Please see the Compression section below to see how to decompress JWTs during parsing.

The JWT specifications identify 13 standard signature algorithms - 3 secret key algorithms and 10 asymmetric key algorithms:

^{1. Requires Java 15 or a compatible JCA Provider (like BouncyCastle) in the runtime classpath.}

^{2. Requires Java 15 or a compatible JCA Provider (like BouncyCastle) in the runtime classpath.}

These are all represented as constants in the io.jsonwebtoken.Jwts.SIG registry class.

What’s really important about the above standard signature algorithms - other than their security properties - is that the JWT specification RFC 7518, Sections 3.2 through 3.5 requires (mandates) that you MUST use keys that are sufficiently strong for a chosen algorithm.

This means that JJWT - a specification-compliant library - will also enforce that you use sufficiently strong keys for the algorithms you choose. If you provide a weak key for a given algorithm, JJWT will reject it and throw an exception.

This is not because we want to make your life difficult, we promise! The reason why the JWT specification, and consequently JJWT, mandates key lengths is that the security model of a particular algorithm can completely break down if you don’t adhere to the mandatory key properties of the algorithm, effectively having no security at all. No one wants completely insecure JWTs, right? Right!

So what are the key strength requirements?

You create a JWS as follows:

1. Use the Jwts.builder() method to create a JwtBuilder instance.

2. Call JwtBuilder methods to set the payload content or claims and any header parameters as desired.

3. Specify the SecretKey or asymmetric PrivateKey you want to use to sign the JWT.

4. Finally, call the compact() method to compact and sign, producing the final jws.

For example:

You read (parse) a JWS as follows:

1. Use the Jwts.parser() method to create a JwtParserBuilder instance.

2. Call either keyLocator or verifyWith methods to determine the key used to verify the JWS signature.

3. Call the build() method on the JwtParserBuilder to return a thread-safe JwtParser.

4. Finally, call the parseSignedClaims(String) method with your jws String, producing the original JWS.

5. The entire call is wrapped in a try/catch block in case parsing or signature validation fails. We’ll cover exceptions and causes for failure later.

For example:

In some cases, especially if a JWS payload is large, it could be desirable to not Base64URL-encode the JWS payload, or even exclude the payload from the compact JWS string entirely. The JWT RFC specifications provide support for these use cases via the JSON Web Signature (JWS) Unencoded Payload Option specification, which JJWT supports.

This option comes with both benefits and disadvantages:

The JWT specification defines 6 standard Authenticated Encryption algorithms used to encrypt a JWT payload:

^{1. Requires Java 8 or a compatible JCA Provider (like BouncyCastle) in the runtime classpath.}

These are all represented as constants in the io.jsonwebtoken.Jwts.ENC registry singleton as implementations of the io.jsonwebtoken.security.AeadAlgorithm interface.

As shown in the table above, each algorithm requires a key of sufficient length. The JWT specification RFC 7518, Sections 5.2.3 through 5.3 requires (mandates) that you MUST use keys that are sufficiently strong for a chosen algorithm. This means that JJWT - a specification-compliant library - will also enforce that you use sufficiently strong keys for the algorithms you choose. If you provide a weak key for a given algorithm, JJWT will reject it and throw an exception.

The reason why the JWT specification, and consequently JJWT, mandates key lengths is that the security model of a particular algorithm can completely break down if you don’t adhere to the mandatory key properties of the algorithm, effectively having no security at all.

As stated above, all standard JWA Encryption Algorithms are AES-based authenticated encryption algorithms. So what about RSA and Elliptic Curve cryptography? And password-based key derivation, or Diffie-Hellman exchange?

All of those are supported as well, but they are not used directly for encryption. They are used to produce the key that will be used to directly encrypt the JWT payload.

That is, JWT encryption can be thought of as a two-step process, shown in the following pseudocode:

Steps:

1. Use the algorithmKey to produce the actual key that will be used to encrypt the payload. The JWT specifications call this result the 'Content Encryption Key'.

2. Take the resulting Content Encryption Key and use it directly with the Authenticated Encryption algorithm to actually encrypt the JWT payload.

So why the indirection? Why not just use any PublicKey, SecretKey or Password to encrypt the payload directly ?

There are quite a few reasons for this.

1. Asymmetric key encryption (like RSA and Elliptic Curve) tends to be slow. Like really slow. Symmetric key cipher algorithms in contrast are really fast. This matters a lot in production applications that could be handling a JWT on every HTTP request, which could be thousands per second.

2. RSA encryption (for example) can only encrypt a relatively small amount of data. A 2048-bit RSA key can only encrypt up to a maximum of 245 bytes. A 4096-bit RSA key can only encrypt up to a maximum of 501 bytes. There are plenty of JWTs that can exceed 245 bytes, and that would make RSA unusable.

3. Passwords usually make for very poor encryption keys - they often have poor entropy, or they themselves are often too short to be used directly with algorithms that mandate minimum key lengths to help ensure safety.

For these reasons and more, using one secure algorithm to generate or encrypt a key used for another (very fast) secure algorithm has been proven to be a great way to increase security through many more secure algorithms while also still resulting in very fast and secure output. This is after all how TLS (for https encryption) works - two parties can use more complex cryptography (like RSA or Elliptic Curve) to negotiate a small, fast encryption key. This fast encryption key is produced during the 'TLS handshake' and is called the TLS 'session key'.

So the JWT specifications work much in the same way: one key from any number of various algorithm types can be used to produce a final symmetric key, and that symmetric key is used to encrypt the JWT payload.

Now that we know the difference between a JWE Encryption Algorithm and a JWE Key Management Algorithm, how do we use them to encrypt a JWT?

You create an encrypted JWT (called a 'JWE') as follows:

1. Use the Jwts.builder() method to create a JwtBuilder instance.

2. Call JwtBuilder methods to set the payload content or claims and any header parameters as desired.

3. Call the encryptWith method, specifying the Key, Key Algorithm, and Encryption Algorithm you want to use.

4. Finally, call the compact() method to compact and encrypt, producing the final jwe.

For example:

Before calling compact(), you may set any header parameters and claims exactly the same way as described for JWS.

You read (parse) a JWE as follows:

1. Use the Jwts.parser() method to create a JwtParserBuilder instance.

2. Call either keyLocator or decryptWith methods to determine the key used to decrypt the JWE.

3. Call the JwtParserBuilder's build() method to create a thread-safe JwtParser.

4. Parse the jwe string with the JwtParser's parseEncryptedClaims or parseEncryptedContent method.

5. Wrap the entire call is in a try/catch block in case decryption or integrity verification fails.

For example:

You create a JWK as follows:

1. Use the Jwks.builder() method to create a JwkBuilder instance.

2. Call the key method with the Java key you wish to represent as a JWK.

3. Call builder methods to set any additional key parameters or metadata, such as a kid (Key ID), X509 Certificates, etc as desired.

4. Call the build() method to produce the resulting JWK.

For example:

You can read/parse a JWK by building a JwkParser and parsing the JWK JSON string with its parse method:

As shown above you can specify a custom JCA Provider or JSON deserializer in the same way as the JwtBuilder.

Unlike Java, the JWA specification requires a private JWKs to contain both public key and private key material (see RFC 7518, Section 6.1.1 and RFC 7518, Section 6.3.2).

In this sense, a private JWK (represented as a PrivateJwk or a subtype, such as RsaPrivateJwk, EcPrivateJwk, etc) can be thought of more like a Java KeyPair instance. Consequently, when creating a PrivateJwk instance, the PrivateKey's corresponding PublicKey is required.

A JWK Thumbprint is a digest (aka hash) of a canonical JSON representation of a JWK’s public properties. 'Canonical' in this case means that only RFC-specified values in any JWK are used in an exact order thumbprint calculation. This ensures that anyone can calculate a JWK’s same exact thumbprint, regardless of custom parameters or JSON key/value ordering differences in a JWK.

All Jwk instances support JWK Thumbprints via the thumbprint() and thumbprint(HashAlgorithm) methods:

The resulting JwkThumbprint instance provides some useful methods:

• jwkThumbprint.toByteArray(): the thumbprint’s actual digest bytes - i.e. the raw output from the hash algorithm

• jwkThumbprint.toString(): the digest bytes as a Base64URL-encoded string

• jwkThumbprint.getHashAlgorithm(): the specific HashAlgorithm used to compute the thumbprint. Many standard IANA hash algorithms are available as constants in the Jwks.HASH utility class.

• jwkThumbprint.toURI(): the thumbprint’s canonical URI as defined by the JWK Thumbprint URI specification

Because they contain secret or private key material, SecretJwk and PrivateJwk (e.g. RsaPrivateJwk,
EcPrivateJwk, etc) instances should be used with great care and never accidentally transmitted to 3rd parties.

Even so, JJWT’s Jwk implementations will suppress certain values in toString() output for safety as described next.

A JWK Set is a JSON object that represents a set of JWKs.  The JSON
object MUST have a "keys" member, with its value being an array of
JWKs.

You create a JWK Set as follows:

1. Use the Jwks.set() method to create a JwkSetBuilder instance.

2. Call the add(Jwk) method any number of times to add one or more JWKs to the set.

3. Call builder methods to set any additional JSON members if desired, or the operationPolicy(KeyOperationPolicy) builder method to control what key operations may be assigned to any given JWK added to the set.

4. Call the build() method to produce the resulting JWK Set.

For example:

As shown, you can optionally configure the .operationPolicy(KeyOperationPolicy) method using a Jwts.OP.policy() builder. A KeyOperationPolicy allows you control what operations are allowed for any JWK before being added to the JWK Set; any JWK that does not match the policy will be rejected and not added to the set. JJWT internally defaults to a standard RFC-compliant policy, but you can create a policy to override the default if desired using the Jwks.OP.policy() builder method.

You can read/parse a JWK Set by building a JWK Set Parser and parsing the JWK Set JSON with one of its various parse methods:

As shown above, you can specify a custom JCA Provider, JSON deserializer or KeyOperationPolicy in the same way as the JwkSetBuilder. Any JWK that does not match the default (or configured) policy will be rejected. You can create a policy to override the default if desired using the Jwks.OP.policy() builder method.

If the default Jwts.ZIP compression algorithms are not suitable for your needs, you can create your own CompressionAlgorithm implementation(s).

Just as you would with the default algorithms, you may specify that you want a JWT compressed by calling the JwtBuilder's compressWith method, supplying your custom implementation instance. For example:

When you call compressWith, the JWT payload will be compressed with your algorithm, and the zip (Compression Algorithm) header will automatically be set to the value returned by your algorithm’s algorithm.getId() method as required by the JWT specification.

However, the JwtParser needs to be aware of this custom algorithm as well, so it can use it while parsing. You do this by modifying the JwtParserBuilder's zip() collection. For example:

This adds additional CompressionAlgorithm implementations to the parser’s overall total set of supported compression algorithms (which already includes all of the Jwts.ZIP algorithms by default).

The parser will then automatically check to see if the JWT zip header has been set to see if a compression algorithm has been used to compress the JWT. If set, the parser will automatically look up your CompressionAlgorithm by its getId() value, and use it to decompress the JWT.

If you don’t want to use JJWT’s runtime dependency approach, or just want to customize how JSON serialization and deserialization works, you can implement the Serializer and Deserializer interfaces and specify instances of them on the JwtBuilder and JwtParserBuilder respectively. For example:

When creating a JWT:

When reading a JWT:

If you want to use Jackson for JSON processing, just including the io.jsonwebtoken:jjwt-jackson dependency as a runtime dependency is all that is necessary in most projects, since Gradle and Maven will automatically pull in the necessary Jackson dependencies as well.

After including this dependency, JJWT will automatically find the Jackson implementation on the runtime classpath and use it internally for JSON parsing. There is nothing else you need to do - JJWT will automatically create a new Jackson ObjectMapper for its needs as required.

However, if you have an application-wide Jackson ObjectMapper (as is typically recommended for most applications), you can configure JJWT to use your own ObjectMapper instead.

You do this by declaring the io.jsonwebtoken:jjwt-jackson dependency with compile scope (not runtime scope which is the typical JJWT default). That is:

Maven

Gradle or Android

And then you can specify the JacksonSerializer using your own ObjectMapper on the JwtBuilder:

and the JacksonDeserializer using your ObjectMapper on the JwtParserBuilder:

If you want to use Gson for JSON processing, just including the io.jsonwebtoken:jjwt-gson dependency as a runtime dependency is all that is necessary in most projects, since Gradle and Maven will automatically pull in the necessary Gson dependencies as well.

After including this dependency, JJWT will automatically find the Gson implementation on the runtime classpath and use it internally for JSON parsing. There is nothing else you need to do - just declaring the dependency is all that is required, no code or config is necessary.

If you’re curious, JJWT will automatically create an internal default Gson instance for its own needs as follows:

The registerTypeHierarchyAdapter builder call is required to serialize JWKs with secret or private values.

However, if you prefer to use a different Gson instance instead of JJWT’s default, you can configure JJWT to use your own - just don’t forget to register the necessary JJWT type hierarchy adapter.

You do this by declaring the io.jsonwebtoken:jjwt-gson dependency with compile scope (not runtime scope which is the typical JJWT default). That is:

Maven

Gradle or Android

And then you can specify the GsonSerializer using your own Gson instance on the JwtBuilder:

and the GsonDeserializer using your Gson instance on the JwtParser:

Again, as shown above, it is critical to create your Gson instance using the GsonBuilder and include the line:

to ensure JWK serialization works as expected.

All cryptographic operations, like encryption and message digest calculations, result in binary data - raw byte arrays.

Because raw byte arrays cannot be represented natively in JSON, the JWT specifications employ the Base64URL encoding scheme to represent these raw byte values in JSON documents or compound structures like a JWT.

This means that the Base64 and Base64URL algorithms take a raw byte array and converts the bytes into a string suitable to use in text documents and protocols like HTTP. These algorithms can also convert these strings back into the original raw byte arrays for decryption or signature verification as necessary.

That’s nice and convenient, but there are two very important properties of Base64 (and Base64URL) text strings that are critical to remember when they are used in security scenarios like with JWTs:

• Base64 is not encryption

• Changing Base64 characters does not automatically invalidate data.

If for some reason you want to specify your own Base64Url encoder and decoder, you can use the JwtBuilder encoder method to set the encoder:

and the JwtParserBuilder's decoder method to set the decoder:

This is an example showing how to digitally sign a JWT using an HMAC (hash-based message authentication code). The JWT specifications define 3 standard HMAC signing algorithms:

• HS256: HMAC with SHA-256. This requires a 256-bit (32 byte) SecretKey or larger.

• HS384: HMAC with SHA-384. This requires a 384-bit (48 byte) SecretKey or larger.

• HS512: HMAC with SHA-512. This requires a 512-bit (64 byte) SecretKey or larger.

Example:

This is an example showing how to digitally sign and verify a JWT using RSA cryptography. The JWT specifications define 6 standard RSA signing algorithms. All 6 require that RSA keys 2048-bits or larger must be used.

In this example, Bob will sign a JWT using his RSA private key, and Alice can verify it came from Bob using Bob’s RSA public key:

This is an example showing how to digitally sign and verify a JWT using the Elliptic Curve Digital Signature Algorithm. The JWT specifications define 3 standard ECDSA signing algorithms:

• ES256: ECDSA using P-256 and SHA-256. This requires an EC Key exactly 256 bits (32 bytes) long.

• ES384: ECDSA using P-384 and SHA-384. This requires an EC Key exactly 384 bits (48 bytes) long.

• ES512: ECDSA using P-521 and SHA-512. This requires an EC Key exactly 521 bits (65 or 66 bytes depending on format) long.

In this example, Bob will sign a JWT using his EC private key, and Alice can verify it came from Bob using Bob’s EC public key:

This is an example showing how to digitally sign and verify a JWT using the Edwards Curve Digital Signature Algorithm using Ed25519 or Ed448 keys.

The EdDSA signature algorithm is defined for JWS in RFC 8037, Section 3.1 using keys for two Edwards curves:

• Ed25519: EdDSA using curve Ed25519. Ed25519 algorithm keys must be 255 bits long and produce signatures 512 bits (64 bytes) long.

• Ed448: EdDSA using curve Ed448. Ed448 algorithm keys must be 448 bits long and produce signatures 912 bits (114 bytes) long.

In this example, Bob will sign a JWT using his Edwards Curve private key, and Alice can verify it came from Bob using Bob’s Edwards Curve public key:

This is an example showing how to encrypt a JWT directly using a symmetric secret key. The JWT specifications define 6 standard AEAD Encryption algorithms:

• A128GCM: AES GCM using a 128-bit (16 byte) SecretKey or larger.

• A192GCM: AES GCM using a 192-bit (24 byte) SecretKey or larger.

• A256GCM: AES GCM using a 256-bit (32 byte) SecretKey or larger.

• A128CBC-HS256: AES_128_CBC_HMAC_SHA_256 using a 256-bit (32 byte) SecretKey.

• A192CBC-HS384: AES_192_CBC_HMAC_SHA_384 using a 384-bit (48 byte) SecretKey.

• A256CBC-HS512: AES_256_CBC_HMAC_SHA_512 using a 512-bit (64 byte) SecretKey.

The AES GCM (A128GCM, A192GCM and A256GCM) algorithms are strongly recommended - they are faster and more efficient than the A*CBC-HS* variants, but they do require JDK 8 or later (or JDK 7 + BouncyCastle).

Example:

This is an example showing how to encrypt and decrypt a JWT using RSA cryptography.

Because RSA cannot encrypt much data, RSA is used to encrypt and decrypt a secure-random key, and that generated key in turn is used to actually encrypt the payload as described in the RSA Key Encryption section above. As such, RSA Key Algorithms must be paired with an AEAD Encryption Algorithm, as shown below.

In this example, Bob will encrypt a JWT using Alice’s RSA public key to ensure only she may read it. Alice can then decrypt the JWT using her RSA private key:

This is an example showing how to encrypt and decrypt a JWT using AES Key Wrap algorithms.

These algorithms use AES to encrypt and decrypt a secure-random key, and that generated key in turn is used to actually encrypt the payload as described in the AES Key Encryption section above. This allows the payload to be encrypted with a random short-lived key, reducing material exposure of the potentially longer-lived symmetric secret key. This approach requires the AES Key Wrap algorithms to be paired with an AEAD content encryption algorithm, as shown below.

The AES GCM Key Wrap algorithms (A128GCMKW, A192GCMKW and A256GCMKW) are preferred - they are faster and more efficient than the A*KW variants, but they do require JDK 8 or later (or JDK 7 + BouncyCastle).

This is an example showing how to encrypt and decrypt a JWT using Elliptic Curve Diffie-Hellman Ephemeral Static Key Agreement (ECDH-ES) algorithms.

These algorithms use ECDH-ES to encrypt and decrypt a secure-random key, and that generated key in turn is used to actually encrypt the payload as described in the Elliptic Curve Diffie-Hellman Ephemeral Static Key Agreement section above. Because of this, ECDH-ES Key Algorithms must be paired with an AEAD Encryption Algorithm, as shown below.

In this example, Bob will encrypt a JWT using Alice’s Elliptic Curve public key to ensure only she may read it.
Alice can then decrypt the JWT using her Elliptic Curve private key:

This is an example showing how to encrypt and decrypt a JWT using Password-based key-derivation algorithms.

These algorithms use a password to securely derive a random key, and that derived random key in turn is used to actually encrypt the payload as described in the Password-based Key Encryption section above. This allows the payload to be encrypted with a random short-lived cryptographically-stronger key, reducing the need to expose the longer-lived (and potentially weaker) password.

This approach requires the Password-based Key Wrap algorithms to be paired with an AEAD content encryption algorithm, as shown below.

Example creating and parsing a secret JWK:

Example creating and parsing an RSA Public JWK:

Example creating and parsing an RSA Private JWK:

Example creating and parsing an Elliptic Curve Public JWK:

Example creating and parsing an Elliptic Curve Private JWK:

Example creating and parsing an Edwards Elliptic Curve (Ed25519, Ed448, X25519, X448) Public JWK (the JWT RFC 8037 specification calls these Octet keys, hence the OctetPublicJwk interface names):

Example creating and parsing an Edwards Elliptic Curve (Ed25519, Ed448, X25519, X448) Private JWK (the JWT RFC 8037 specification calls these Octet keys, hence the OctetPrivateJwk and OctetPublicJwk interface names):