Java JWT: JSON Web Token for Java and Android

• Features
  • Currently Unsupported Features
• Community
  • Getting Help
    • Questions
    • Bugs, Feature Requests, Ideas and General Discussions
  • Contributing
    • Pull Requests
    • Help Wanted
• What is a JSON Web Token?
  • JWT Example
  • JWS Example
  • JWE Example
• Installation
  • JDK Projects
    • Maven
    • Gradle
  • Android Projects
    • Dependencies
    • Proguard
    • Bouncy Castle
  • Understanding JJWT Dependencies
• Quickstart
• Creating a JWT
  • JWT Header
    • JwtBuilder Header
      • Custom Header Parameters
      • Header Parameter Map
    • Jwts HeaderBuilder
  • JWT Payload
    • Arbitrary Content
    • JWT Claims
      • Standard Claims
      • Custom Claims
      • Claims Map
  • JWT Compression
• Reading a JWT
  • Constant Parsing Key
    • Multiple Keys?
  • Dynamic Key Lookup
    • Key Locator
    • Key Locator Strategy
    • Key Locator Return Values
    • Provider-constrained Keys
  • Claim Assertions
  • Accounting for Clock Skew
    • Custom Clock Support
  • JWT Decompression
• Signed JWTs
  • Standard Signature Algorithms
  • Signature Algorithms Keys
    • HMAC-SHA
    • RSA
    • Elliptic Curve
    • Edwards Curve
    • Creating Safe Keys
      • Secret Keys
      • Asymmetric Keys
  • Creating a JWS
    • Signing Key
      • SecretKey Formats
      • SignatureAlgorithm Override
    • JWS Compression
  • Reading a JWS
    • Verification Key
    • Verification Key Locator
    • JWS Decompression
  • Unencoded Payload Option
    • Benefits
    • Disadvantages
    • Detached Payload Example
    • Non-Detached Payload Example
• Encrypted JWTs
  • JWE Encryption Algorithms
    • Symmetric Ciphers
  • JWE Key Management Algorithms
    • JWE Standard Key Management Algorithms
      • RSA Key Encryption
      • AES Key Encryption
      • Direct Key Encryption
      • Password-Based Key Encryption
      • Elliptic Curve Diffie-Hellman Ephemeral Static Key Agreement (ECDH-ES)
  • Creating a JWE
    • JWE Compression
  • Reading a JWE
    • Decryption Key
    • Decryption Key Locator
    • ECDH-ES Decryption with PKCS11 PrivateKeys
    • JWE Decompression
• JSON Web Keys (JWKs)
  • Create a JWK
    • JWK from a Map
  • Read a JWK
  • PrivateKey JWKs
    • Private JWK PublicKey
    • Private JWK from KeyPair
    • Private JWK Public Conversion
  • JWK Thumbprints
    • JWK Thumbprint as a Key ID
    • JWK Thumbprint URI
  • JWK Security Considerations
    • JWK toString() Safety
• JWK Sets
  • Create a JWK Set
  • Read a JWK Set
• Compression
  • Custom Compression Algorithm
• JSON Support
  • Custom JSON Processor
  • Jackson JSON Processor
    • Parsing of Custom Claim Types
  • Gson JSON Processor
• Base64 Support
  • Understanding Base64 in Security Contexts
    • Base64 is not encryption
    • Changing Base64 Characters
      • Adding Invalid Characters
  • Custom Base64
• Examples
  • JWT Signed with HMAC
  • JWT Signed with RSA
  • JWT Signed with ECDSA
  • JWT Signed with EdDSA
  • JWT Encrypted Directly with a SecretKey
  • JWT Encrypted with RSA
  • JWT Encrypted with AES Key Wrap
  • JWT Encrypted with ECDH-ES
  • JWT Encrypted with a Password
  • SecretKey JWK
  • RSA Public JWK
  • RSA Private JWK
  • Elliptic Curve Public JWK
  • Elliptic Curve Private JWK
  • Edwards Elliptic Curve Public JWK
  • Edwards Elliptic Curve Private JWK
• Learn More
• Author
• License

If the documentation or the API JavaDoc isn’t sufficient, and you either have usability questions or are confused about something, please 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 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.

If you do not have a usability question and believe you have a legitimate bug or feature request, please 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.

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 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 request if it might not align with the project’s goals, design expectations or planned functionality. We’ve sadly had to reject large PRs in the past because they were out of sync with project or design expectations - all because the PR author didn’t first check in with the team first before working on a solution.

So, please create a new JJWT discussion first to discuss, and then we can see easily convert the discussion to an issue and then see if (or how) a PR is warranted. Thank you!

If you would like to help, but don’t know where to start, please visit the Help Wanted Issues page and pick any of the ones there, and we’ll be happy to discuss and answer questions in the issue comments.

If any of those don’t appeal to you, no worries! Any help you would like to offer would be appreciated based on the above caveats concerning contributing pull requests. Feel free to discuss or ask questions first if you’re not sure. :)

eyJhbGciOiJub25lIn0.VGhlIHRydWUgc2lnbiBvZiBpbnRlbGxpZ2VuY2UgaXMgbm90IGtub3dsZWRnZSBidXQgaW1hZ2luYXRpb24u.

eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJKb2UifQ.1KP0SsvENi7Uz1oQc07aXTL7kpQG5jBNIybqr60AlD4

eyJhbGciOiJBMTI4S1ciLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.
6KB707dM9YTIgHtLvtgWQ8mKwboJW3of9locizkDTHzBC2IlrT1oOQ.
AxY8DCtDaGlsbGljb3RoZQ.
KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.
U0m_YmjN04DJvceFICbCVQ

Add the dependencies to your project:

You can use the following Android Proguard exclusion rules:

If you want to use JWT RSASSA-PSS algorithms (i.e. PS256, PS384, and PS512), EdECDH (X25512 or X448) Elliptic Curve Diffie-Hellman encryption, EdDSA (Ed25519 or Ed448) signature algorithms, or you just want to ensure your Android application is running an updated version of BouncyCastle, you will need to:

1. Uncomment the BouncyCastle dependency as commented above in the dependencies section.

2. Replace the legacy Android custom BC provider with the updated one.

Provider registration needs to be done early in the application’s lifecycle, preferably in your application’s main Activity class as a static initialization block. For example:

The easiest and recommended way to set one or more JWT header parameters (name/value pairs) is to use the JwtBuilder's header() builder as desired, and then call its and() method to return back to the JwtBuilder for further configuration. For example:

The JwtBuilder header() builder also supports automatically calculating X.509 thumbprints and other builder-style benefits that a simple property getter/setter object would not do.

Custom Header Parameters

Jwts.builder()

    .header()
        .add("aHeaderName", aValue)
        // ... etc ...
        .and() // return to the JwtBuilder

// ... etc ...

Header Parameter Map

Jwts.builder()

    .header()
        .add(multipleHeaderParamsMap)
        // ... etc ...
        .and() // return to the JwtBuilder

// ... etc ...

Using Jwts.builder().header() shown above is the preferred way to modify a header when using the JwtBuilder.

However, if you would like to create a 'standalone' Header outside of the context of using the JwtBuilder, you can use Jwts.header() instead to return an independent Header builder. For example:

There are only two differences between Jwts.header() and Jwts.builder().header():

1. Jwts.header() builds a 'detached' Header that is not associated with any particular JWT, whereas Jwts.builder().header() always modifies the header of the immediate JWT being constructed by its parent JwtBuilder.

2. Jwts.header() has a build() method to produce an explicit Header instance and Jwts.builder().header() does not (it has an and() method instead) because its parent JwtBuilder will implicitly create the header instance when necessary.

A standalone header might be useful if you want to aggregate common header parameters in a single 'template' instance so you don’t have to repeat them for each JwtBuilder usage. Then this 'template' Header can be used to populate JwtBuilder usages by just appending it to the JwtBuilder header, for example:

You can set the JWT payload to be any arbitrary byte array content by using the JwtBuilder content method. For example:

Notice this particular example of content uses the two-argument convenience variant:

1. The first argument is the actual byte content to set as the JWT payload

2. The second argument is a String identifier of an IANA Media Type.

The second argument will cause the JwtBuilder to automatically set the cty (Content Type) header according to the JWT specification’s recommended compact format.

This two-argument variant is typically recommended over the single-argument content(byte[]) method because it guarantees the JWT recipient can inspect the cty header to determine how to convert the payload byte array into a final form that the application can use.

Without setting the cty header, the JWT recipient must know via out-of-band (external) information how to process the byte array, which is usually less convenient and always requires code changes if the content format ever changes. For these reasons, it is strongly recommended to use the two-argument content method variant.

Instead of a content byte array, a JWT payload may contain assertions or claims for a JWT recipient. In this case, the payload is a Claims JSON Object, and JJWT supports claims creation with type-safe builder methods.

Standard Claims

String jws = Jwts.builder()

    .issuer("me")
    .subject("Bob")
    .audience().add("you").and()
    .expiration(expiration) //a java.util.Date
    .notBefore(notBefore) //a java.util.Date
    .issuedAt(new Date()) // for example, now
    .id(UUID.randomUUID().toString()) //just an example id

    /// ... etc ...

Custom Claims

String jws = Jwts.builder()

    .claim("hello", "world")

    // ... etc ...

Claims Map

Map<String,?> claims = getMyClaimsMap(); //implement me

String jws = Jwts.builder()

    .claims(claims)

    // ... etc ...

But you might have noticed something - what if your application doesn’t use just a single SecretKey or KeyPair? What if JWSs and JWEs can be created with different SecretKeys or public/private keys, or a combination of both? How do you know which key to specify if you don’t inspect the JWT first?

In these cases, you can’t call the JwtParserBuilder's verifyWith or decryptWith methods with a single key - instead, you’ll need to configure a parsing Key Locator, discussed next.

If you need to support dynamic key lookup when encountering JWTs, you’ll need to implement the Locator<Key> interface and specify an instance on the JwtParserBuilder via the keyLocator method. For example:

A Locator<Key> is used to lookup both JWS signature verification keys and JWE decryption keys. You need to determine which key to return based on information in the JWT header, for example:

The JwtParser will invoke the locate method after parsing the JWT header, but before parsing the payload, or verifying any JWS signature or decrypting any JWE ciphertext. This allows you to inspect the header argument for any information that can help you look up the Key to use for verifying that specific jwt. This is very powerful for applications with more complex security models that might use different keys at different times or for different users or customers.

What data might you inspect to determine how to lookup a signature verification or decryption key?

The JWT specifications' preferred approach is to set a kid (Key ID) header value when the JWT is being created, for example:

Then during parsing, your Locator<Key> implementation can inspect the header to get the kid value and then use it to look up the verification or decryption key from somewhere, like a database, keystore or Hardware Security Module (HSM). For example:

Note that inspecting the header.getKeyId() is just the most common approach to look up a key - you could inspect any number of header parameters to determine how to lookup the verification or decryption key. It is all based on how the JWT was created.

If you extend LocatorAdapter<Key> as shown above, but for some reason have different lookup strategies for signature verification keys versus decryption keys, you can forego overriding the locate(ProtectedHeader<?>) method in favor of two respective locate(JwsHeader) and locate(JweHeader) methods:

Regardless of which implementation strategy you choose, remember to return the appropriate type of key depending on the type of JWS or JWE algorithm used. That is:

• For JWS:

  • For HMAC-based signature algorithms, the returned verification key should be a SecretKey, and,

  • For asymmetric signature algorithms, the returned verification key should be a PublicKey (not a PrivateKey).

• For JWE:

  • For JWE direct encryption, the returned decryption key should be a SecretKey.

  • For password-based key derivation algorithms, the returned decryption key should be a io.jsonwebtoken.security.Password. You can create a Password instance by calling Keys.password(char[] passwordCharacters).

  • For asymmetric key management algorithms, the returned decryption key should be a PrivateKey (not a PublicKey).

If any verification or decryption key returned from a Key Locator must be used with a specific security Provider (such as for PKCS11 or Hardware Security Module (HSM) keys), you must make that Provider available for JWT parsing in one of 3 ways, listed in order of recommendation and simplicity:

1. Configure the Provider in the JVM, either by modifying the java.security file or by registering the Provider dynamically via Security.addProvider(Provider). This is the recommended approach so you do not need to modify code anywhere that may need to parse JWTs.

2. Set the Provider as the parser default by calling JwtParserBuilder#provider(Provider). This will ensure the provider is used by default with all located keys unless overridden by a key-specific Provider. This is only recommended when you are confident that all JWTs encountered by the parser instance will use keys attributed to the same Provider, unless overridden by a specific key.

3. Associate the Provider with a specific key using Keys.builder so it is used for that key only. This option is useful if some located keys require a specific provider, while other located keys can assume a default provider. For example:

   public Key locate(Header<?> header) {
   
       PrivateKey /* or SecretKey */ key = findKey(header); // implement me
   
       Provider keySpecificProvider = findKeyProvider(key); // implement me
       if (keySpecificProvider != null) {
           // Ensure the key-specific provider (e.g. for PKCS11 or HSM) will be used
           // during decryption with the KeyAlgorithm in the JWE 'alg' header
           return Keys.builder(key).provider(keySpecificProvider).build();
       }
   
       // otherwise default provider is fine:
       return key;
   }

If the above clockSkewSeconds isn’t sufficient for your needs, the timestamps created during parsing for timestamp comparisons can be obtained via a custom time source. Call the JwtParserBuilder's clock method with an implementation of the io.jsonwebtoken.Clock interface. For example:

The JwtParser's default Clock implementation simply returns new Date() to reflect the time when parsing occurs, as most would expect. However, supplying your own clock could be useful, especially when writing test cases to guarantee deterministic behavior.

JWT HMAC-SHA signature algorithms HS256, HS384, and HS512 require a secret key that is at least as many bits as the algorithm’s signature (digest) length per RFC 7512 Section 3.2. This means:

• HS256 is HMAC-SHA-256, and that produces digests that are 256 bits (32 bytes) long, so HS256 requires that you use a secret key that is at least 32 bytes long.

• HS384 is HMAC-SHA-384, and that produces digests that are 384 bits (48 bytes) long, so HS384 requires that you use a secret key that is at least 48 bytes long.

• HS512 is HMAC-SHA-512, and that produces digests that are 512 bits (64 bytes) long, so HS512 requires that you use a secret key that is at least 64 bytes long.

JWT RSA signature algorithms RS256, RS384, RS512, PS256, PS384 and PS512 all require a minimum key length (aka an RSA modulus bit length) of 2048 bits per RFC 7512 Sections 3.3 and 3.5. Anything smaller than this (such as 1024 bits) will be rejected with an WeakKeyException.

That said, in keeping with best practices and increasing key lengths for security longevity, JJWT recommends that you use:

• at least 2048 bit keys with RS256 and PS256

• at least 3072 bit keys with RS384 and PS384

• at least 4096 bit keys with RS512 and PS512

These are only JJWT suggestions and not requirements. JJWT only enforces JWT specification requirements and for any RSA key, the requirement is the RSA key (modulus) length in bits MUST be >= 2048 bits.

JWT Elliptic Curve signature algorithms ES256, ES384, and ES512 all require a key length (aka an Elliptic Curve order bit length) equal to the algorithm signature’s individual R and S components per RFC 7512 Section 3.4. This means:

• ES256 requires that you use a private key that is exactly 256 bits (32 bytes) long.

• ES384 requires that you use a private key that is exactly 384 bits (48 bytes) long.

• ES512 requires that you use a private key that is exactly 521 bits (65 or 66 bytes) long (depending on format).

The JWT Edwards Curve signature algorithm EdDSA supports two sizes of private and public EdECKeys (these types were introduced in Java 15):

• Ed25519 algorithm keys must be 256 bits (32 bytes) long and produce signatures 512 bits (64 bytes) long.

• Ed448 algorithm keys must be 456 bits (57 bytes) long and produce signatures 912 bits (114 bytes) long.

If you don’t want to think about bit length requirements or just want to make your life easier, JJWT has provided convenient builder classes that can generate sufficiently secure keys for any given JWT signature algorithm you might want to use.

Secret Keys

SecretKey key = Jwts.SIG.HS256.key().build(); //or HS384.key() or HS512.key()

SecretKey key = Jwts.SIG.HS256.key().provider(aProvider).random(aSecureRandom).build();

String secretString = Encoders.BASE64.encode(key.getEncoded());

Asymmetric Keys

KeyPair keyPair = Jwts.SIG.RS256.keyPair().build(); //or RS384, RS512, PS256, etc...

It is usually recommended to specify the signing key by calling the JwtBuilder's signWith method and let JJWT determine the most secure algorithm allowed for the specified key.:

For example, if you call signWith with a SecretKey that is 256 bits (32 bytes) long, it is not strong enough for HS384 or HS512, so JJWT will automatically sign the JWT using HS256.

When using signWith JJWT will also automatically set the required alg header with the associated algorithm identifier.

Similarly, if you called signWith with an RSA PrivateKey that was 4096 bits long, JJWT will use the RS512 algorithm and automatically set the alg header to RS512.

The same selection logic applies for Elliptic Curve PrivateKeys.

SecretKey Formats

SignatureAlgorithm Override

   .signWith(privateKey, Jwts.SIG.RS512) // <---

   .compact();

If your JWT payload is large (contains a lot of data), and you are certain that JJWT will also be the same library that reads/parses your JWS, you might want to compress the JWS to reduce its size.

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

The most important thing to do when reading a JWS is to specify the key used to verify the JWS’s cryptographic signature. If signature verification fails, the JWT cannot be safely trusted and should be discarded.

So which key do we use for verification?

• If 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 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);

But you might have noticed something - what if your application doesn’t use just a single SecretKey or KeyPair? What if JWSs can be created with different SecretKeys or public/private keys, or a combination of both? How do you know which key to specify if you can’t inspect the JWT first?

In these cases, you can’t call the JwtParserBuilder's verifyWith method with a single key - instead, you’ll need a Key Locator. Please see the Key Lookup section to see how to dynamically obtain different keys when parsing JWSs or JWEs.

If you used JJWT to compress a JWS 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.

A JWS producer can still create a JWS string to use for payload integrity verification without having to either:

1. Base64URL-encode the (potentially very large) payload, saving the time that could take.

2. Include the payload in the compact JWS string at all. Omitting the payload from the JWS compact string entirely produces smaller JWSs that can be more efficient to transfer.

1. Your application, and not JJWT, incurs the responsibility to ensure the payload is not modified during transmission so the recipient can verify the JWS signature. For example, by using a sufficiently strong TLS (https) cipher suite as well as any additional care before and after transmission, since TLS does not guarantee end-to-end security.

2. If you choose to include the unencoded payload in the JWS compact string, your application MUST ensure that the payload does not contain a period (.) character anywhere in the payload. The JWS recipient will experience parsing errors otherwise.

Before attempting to use this option, one should be aware of the RFC’s security considerations first.

This example shows creating and parsing a compact JWS using an unencoded payload that is detached, i.e. where the payload is not embedded in the compact JWS string at all.

We need to do three things during creation:

1. Specify the JWS signing key; it’s a JWS and still needs to be signed.

2. Specify the raw payload bytes via the JwtBuilder's content method.

3. Indicate that the payload should not be Base64Url-encoded using the JwtBuilder's encodePayload(false) method.

To parse the resulting jws string, we need to do two things when creating the JwtParser:

1. Specify the signature verification key.

2. Specify the externally-transmitted unencoded payload bytes, required for signature verification.

This example shows creating and parsing a compact JWS with what the RFC calls a 'non-detached' unencoded payload, i.e. a raw string directly embedded as the payload in the compact JWS string.

We need to do three things during creation:

1. Specify the JWS signing key; it’s a JWS and still needs to be signed.

2. Specify the raw payload string via the JwtBuilder's content method. Per the RFC, the payload string MUST NOT contain any period (.) characters.

3. Indicate that the payload should not be Base64Url-encoded using the JwtBuilder's encodePayload(false) method.

If you were to print the jws string, you’d see something like this:

See how the claimsString is embedded directly as the center payload token instead of a standard Base64URL value? This is why no period (.) characters can exist in the payload. If they did, any standard JWT parser would see more than two periods total, which is required for parsing standard JWSs.

To parse the resulting jws string, we need to do two things when creating the JwtParser:

1. Specify the signature verification key.

2. Indicate that we want to support Unencoded Payload Option JWSs by enabling the b64 crit header parameter.

Did you notice we used the .parseSignedClaims(String) method instead of .parseSignedClaims(String, byte[])? This is because the non-detached payload is already present and JJWT has what it needs for signature verification.

Additionally, we needed to specify the b64 critical value: because we’re not using the two-argument parseSignedClaims(jws, content) method, the parser has no way of knowing if you wish to allow or support unencoded payloads. Unencoded payloads have additional security considerations as described above, so they are disabled by the parser by default unless you indicate you want to support them by using critical().add("b64").

Finally, even if the payload contains a non-detached String, you could still use the two-argument method using the payload String’s UTF-8 bytes instead:

You might have noticed something about the above Authenticated Encryption algorithms: they’re all variants of the AES algorithm, and AES always uses a symmetric (secret) key to perform encryption and decryption. That’s kind of strange, isn’t it?

What about RSA and Elliptic Curve asymmetric key cryptography? And Diffie-Hellman key exchange? What about password-based key derivation algorithms? Surely any of those could be desirable depending on the use case, no?

Yes, they definitely can, and the JWT specifications do support them, albeit indirectly: those other algorithms are indeed supported and used, but they aren’t used to encrypt the JWT payload directly. They are used to produce the actual key used to encrypt the JWT payload.

This is all done via the JWT specification’s concept of a Key Management Algorithm, covered next. After we cover that, we’ll show you how to encrypt and parse your own JWTs with the JwtBuilder and JwtParserBuilder.

The JWT specification defines 17 standard Key Management Algorithms used to produce the JWE Content Encryption Key (CEK):

^{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.KEY registry singleton as implementations of the io.jsonwebtoken.security.KeyAlgorithm interface.

But 17 algorithms are a lot to choose from. When would you use them? The sections below describe when you might choose each category of algorithms and how they behave.

RSA Key Encryption

AES Key Encryption

Direct Key Encryption

Password-Based Key Encryption

Elliptic Curve Diffie-Hellman Ephemeral Static Key Agreement (ECDH-ES)

If your JWT payload or Claims set is large (contains a lot of data), you might want to compress the JWE to reduce its size. Please see the main Compression section to see how to compress and decompress JWTs.

The most important thing to do when reading a JWE is to specify the key used during decryption. If decryption or integrity protection checks fail, the JWT cannot be safely trusted and should be discarded.

So which key do we use for decryption?

• If the jwe was encrypted directly with a SecretKey, the same SecretKey must be specified on the JwtParserBuilder. For example:

  Jwts.parser()
  
    .decryptWith(secretKey) // <----
  
    .build()
    .parseEncryptedClaims(jweString);

• If the jwe was encrypted using a key produced by a Password-based key derivation KeyAlgorithm, the same Password must be specified on the JwtParserBuilder. For example:

  Password password = Keys.password(passwordChars);
  
  Jwts.parser()
  
    .decryptWith(password) // <---- an `io.jsonwebtoken.security.Password` instance
  
    .build()
    .parseEncryptedClaims(jweString);

• If the jwe was encrypted with a key produced by an asymmetric KeyAlgorithm, the corresponding PrivateKey (not the PublicKey) must be specified on the JwtParserBuilder. For example:

  Jwts.parser()
  
    .decryptWith(privateKey) // <---- a `PrivateKey`, not a `PublicKey`
  
    .build()
    .parseSignedClaims(jweString);

What if your application doesn’t use just a single SecretKey or KeyPair? What if JWEs can be created with different SecretKeys, Passwords or public/private keys, or a combination of all of them? How do you know which key to specify if you can’t inspect the JWT first?

In these cases, you can’t call the JwtParserBuilder's decryptWith method with a single key - instead, you’ll need to use a Key Locator. Please see the Key Lookup section to see how to dynamically obtain different keys when parsing JWSs or JWEs.

The JWT ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, and ECDH-ES+A256KW key algorithms validate JWE input using public key information, even when using PrivateKeys to decrypt. Ordinarily this is automatically performed by JJWT when your PrivateKey instances implement the ECKey or EdECKey (or BouncyCastle equivalent) interfaces, which is the case for most JCA Provider implementations.

However, if your decryption PrivateKeys are stored in a Hardware Security Module (HSM) and/or you use the SunPKCS11 Provider, it is likely that your PrivateKey instances do not implement ECKey.

In these cases, you need to provide both the PKCS11 PrivateKey and it’s companion PublicKey during decryption by using the Keys.builder method. For example:

You then use the resulting jwtParserDecryptionKey (not pair.getPrivate()) with the JwtParserBuilder or as the return value from a custom Key Locator implementation. For example:

Or as the return value from your key locator:

Please see the Provider-constrained Keys section for more information, as well as code examples of how to implement a Key Locator using the Keys.builder technique.

If a JWE is compressed using the DEF (DEFLATE) or GZIP (GZIP) compression algorithms, it will automatically be decompressed after decryption, and there is nothing you need to configure.

If, however, a custom compression algorithm was used to compress the JWE, 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.

If you have a Map<String,?> of name/value pairs that reflect an existing JWK, you add them and build a type-safe Jwk instance:

If you do not provide a PublicKey when creating a PrivateJwk, JJWT will automatically derive the PublicKey from the PrivateKey instance if possible. However, because this can add some computing time, it is typically recommended to provide the PublicKey when possible to avoid this extra work.

For example:

If you have a Java KeyPair instance, then you have both the public and private key material necessary to create a PrivateJwk. For example:

Note that:

• An exception will be thrown when calling rsaKeyPair if the specified KeyPair instance does not contain RSAPublicKey and RSAPrivateKey instances.

• Similarly, an exception will be thrown when calling ecKeyPair if the KeyPair instance does not contain ECPublicKey and ECPrivateKey instances.

• Finally, an exception will be thrown when calling octetKeyPair if the KeyPair instance does not contain X25519, X448, Ed25519, or Ed448 keys (introduced in JDK 11 and 15 or when using BouncyCastle).

Because private JWKs contain public key material, you can always obtain the private JWK’s corresponding public JWK and Java PublicKey or KeyPair. For example:

Because a thumbprint is an order-guaranteed unique digest of a JWK, JWK thumbprints are often used as convenient unique identifiers for a JWK (e.g. the JWK’s kid (Key ID) value). These identifiers can be useful when locating keys for JWS signature verification or JWE decryption, for example.

For example:

However, because Jwk instances are immutable, you can’t set the key id after the JWK is created. For example, the following is not possible:

Instead, you may use the idFromThumbprint methods on the JwkBuilder when creating a Jwk:

Calling either idFromThumbprint method will ensure that calling jwk.getId() equals thumbprint.toString() (which is Encoders.BASE64URL.encode(thumbprint.toByteArray())).

A JWK’s thumbprint’s canonical URI as defined by the JWK Thumbprint URI specification may be obtained by calling the thumbprint’s toURI() method:

Per the RFC specification, if you call canonicalThumbprintURI.toString(), you would see a string that looks like this:

where:

• urn:ietf:params:oauth:jwk-thumbprint: is the URI scheme+prefix

• HASH_ALG_ID is the standard identifier used to compute the thumbprint as defined in the IANA Named Information Hash Algorithm Registry. This is the same as thumbprint.getHashAlgorithm().getId().

• BASE64URL_DIGEST is the Base64URL-encoded thumbprint bytes, equal to jwkThumbprint.toString().

Because it would be incredibly easy to accidentally print key material to System.out.println() or application logs, all Jwk implementations will print redacted values instead of actual secret or private key material.

For example, consider the following Secret JWK JSON example from RFC 7515, Appendix A.1.1:

The k value (AyAyM1SysPpby...) reflects secure key material and should never be accidentally exposed.

If you were to parse this JSON as a Jwk, calling toString() will NOT print this value. It will instead print the string literal <redacted> for any secret or private key data value. For example:

This code would print the following string literal to the System console:

This is true for all secret or private key members in SecretJwk and PrivateJwk (e.g. RsaPrivateJwk, EcPrivateJwk, etc) instances.