public interface JwtParserBuilder
JwtParser. Example usage:
Jwts.parserBuilder()
.setSigningKey(...)
.requireIssuer("https://issuer.example.com")
.build()
.parse(jwtString)
| Modifier and Type | Method and Description |
|---|---|
JwtParserBuilder |
base64UrlDecodeWith(Decoder<String,byte[]> base64UrlDecoder)
Perform Base64Url decoding with the specified Decoder
|
JwtParser |
build()
Returns an immutable/thread-safe
JwtParser created from the configuration from this JwtParserBuilder. |
JwtParserBuilder |
deserializeJsonWith(Deserializer<Map<String,?>> deserializer)
Uses the specified deserializer to convert JSON Strings (UTF-8 byte arrays) into Java Map objects.
|
JwtParserBuilder |
require(String claimName,
Object value)
Ensures that the specified
claimName exists in the parsed JWT. |
JwtParserBuilder |
requireAudience(String audience)
Ensures that the specified
aud exists in the parsed JWT. |
JwtParserBuilder |
requireExpiration(Date expiration)
Ensures that the specified
exp exists in the parsed JWT. |
JwtParserBuilder |
requireId(String id)
Ensures that the specified
jti exists in the parsed JWT. |
JwtParserBuilder |
requireIssuedAt(Date issuedAt)
Ensures that the specified
iat exists in the parsed JWT. |
JwtParserBuilder |
requireIssuer(String issuer)
Ensures that the specified
iss exists in the parsed JWT. |
JwtParserBuilder |
requireNotBefore(Date notBefore)
Ensures that the specified
nbf exists in the parsed JWT. |
JwtParserBuilder |
requireSubject(String subject)
Ensures that the specified
sub exists in the parsed JWT. |
JwtParserBuilder |
setAllowedClockSkewSeconds(long seconds)
Sets the amount of clock skew in seconds to tolerate when verifying the local time against the
exp
and nbf claims. |
JwtParserBuilder |
setClock(Clock clock)
Sets the
Clock that determines the timestamp to use when validating the parsed JWT. |
JwtParserBuilder |
setCompressionCodecResolver(CompressionCodecResolver compressionCodecResolver)
Sets the
CompressionCodecResolver used to acquire the CompressionCodec that should be used to
decompress the JWT body. |
JwtParserBuilder |
setSigningKey(byte[] key)
Sets the signing key used to verify any discovered JWS digital signature.
|
JwtParserBuilder |
setSigningKey(Key key)
Sets the signing key used to verify any discovered JWS digital signature.
|
JwtParserBuilder |
setSigningKey(String base64EncodedSecretKey)
Deprecated.
in favor of
setSigningKey(Key) as explained in the above Deprecation Notice,
and will be removed in 1.0.0. |
JwtParserBuilder |
setSigningKeyResolver(SigningKeyResolver signingKeyResolver)
Sets the
SigningKeyResolver used to acquire the signing key that should be used to verify
a JWS's signature. |
JwtParserBuilder requireId(String id)
jti exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.id - the required value of the jti header parameter.MissingClaimException,
IncorrectClaimExceptionJwtParserBuilder requireSubject(String subject)
sub exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.subject - the required value of the sub header parameter.MissingClaimException,
IncorrectClaimExceptionJwtParserBuilder requireAudience(String audience)
aud exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.audience - the required value of the aud header parameter.MissingClaimException,
IncorrectClaimExceptionJwtParserBuilder requireIssuer(String issuer)
iss exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.issuer - the required value of the iss header parameter.MissingClaimException,
IncorrectClaimExceptionJwtParserBuilder requireIssuedAt(Date issuedAt)
iat exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.issuedAt - the required value of the iat header parameter.MissingClaimException,
IncorrectClaimExceptionJwtParserBuilder requireExpiration(Date expiration)
exp exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.expiration - the required value of the exp header parameter.MissingClaimException,
IncorrectClaimExceptionJwtParserBuilder requireNotBefore(Date notBefore)
nbf exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.notBefore - the required value of the npf header parameter.MissingClaimException,
IncorrectClaimExceptionJwtParserBuilder require(String claimName, Object value)
claimName exists in the parsed JWT. If missing or if the parsed
value does not equal the specified value, an exception will be thrown indicating that the
JWT is invalid and may not be used.claimName - the name of a claim that must existvalue - the required value of the specified claimNameMissingClaimException,
IncorrectClaimExceptionJwtParserBuilder setClock(Clock clock)
Clock that determines the timestamp to use when validating the parsed JWT.
The parser uses a default Clock implementation that simply returns new Date() when called.clock - a Clock object to return the timestamp to use when validating the parsed JWT.JwtParserBuilder setAllowedClockSkewSeconds(long seconds) throws IllegalArgumentException
exp
and nbf claims.seconds - the number of seconds to tolerate for clock skew when verifying exp or nbf claims.IllegalArgumentException - if seconds is a value greater than Long.MAX_VALUE / 1000 as
any such value would cause numeric overflow when multiplying by 1000 to obtain
a millisecond value.JwtParserBuilder setSigningKey(byte[] key)
Note that this key MUST be a valid key for the signature algorithm found in the JWT header
(as the alg header parameter).
This method overwrites any previously set key.
key - the algorithm-specific signature verification key used to validate any discovered JWS digital
signature.@Deprecated JwtParserBuilder setSigningKey(String base64EncodedSecretKey)
setSigningKey(Key) as explained in the above Deprecation Notice,
and will be removed in 1.0.0.Note that this key MUST be a valid key for the signature algorithm found in the JWT header
(as the alg header parameter).
This method overwrites any previously set key.
This is a convenience method: the string argument is first BASE64-decoded to a byte array and this resulting
byte array is used to invoke setSigningKey(byte[]).
Deprecation Notice: Deprecated as of 0.10.0, will be removed in 1.0.0
This method has been deprecated because the key argument for this method can be confusing: keys for
cryptographic operations are always binary (byte arrays), and many people were confused as to how bytes were
obtained from the String argument.
This method always expected a String argument that was effectively the same as the result of the following (pseudocode):
String base64EncodedSecretKey = base64Encode(secretKeyBytes);
However, a non-trivial number of JJWT users were confused by the method signature and attempted to
use raw password strings as the key argument - for example setSigningKey(myPassword) - which is
almost always incorrect for cryptographic hashes and can produce erroneous or insecure results.
See this StackOverflow answer explaining why raw (non-base64-encoded) strings are almost always incorrect for signature operations.
Finally, please use the setSigningKey(Key) instead, as this method (and likely the
byte[] variant) will be removed before the 1.0.0 release.
base64EncodedSecretKey - the BASE64-encoded algorithm-specific signature verification key to use to validate
any discovered JWS digital signature.JwtParserBuilder setSigningKey(Key key)
Note that this key MUST be a valid key for the signature algorithm found in the JWT header
(as the alg header parameter).
This method overwrites any previously set key.
key - the algorithm-specific signature verification key to use to validate any discovered JWS digital
signature.JwtParserBuilder setSigningKeyResolver(SigningKeyResolver signingKeyResolver)
SigningKeyResolver used to acquire the signing key that should be used to verify
a JWS's signature. If the parsed String is not a JWS (no signature), this resolver is not used.
Specifying a SigningKeyResolver is necessary when the signing key is not already known before parsing
the JWT and the JWT header or payload (plaintext body or Claims) must be inspected first to determine how to
look up the signing key. Once returned by the resolver, the JwtParser will then verify the JWS signature with the
returned key. For example:
Jws<Claims> jws = Jwts.parser().setSigningKeyResolver(new SigningKeyResolverAdapter() {
@Override
public byte[] resolveSigningKeyBytes(JwsHeader header, Claims claims) {
//inspect the header or claims, lookup and return the signing key
return getSigningKey(header, claims); //implement me
}})
.parseClaimsJws(compact);
A SigningKeyResolver is invoked once during parsing before the signature is verified.
This method should only be used if a signing key is not provided by the other setSigningKey* builder
methods.
signingKeyResolver - the signing key resolver used to retrieve the signing key.JwtParserBuilder setCompressionCodecResolver(CompressionCodecResolver compressionCodecResolver)
CompressionCodecResolver used to acquire the CompressionCodec that should be used to
decompress the JWT body. If the parsed JWT is not compressed, this resolver is not used.
NOTE: Compression is not defined by the JWT Specification, and it is not expected that other libraries (including JJWT versions < 0.6.0) are able to consume a compressed JWT body correctly. This method is only useful if the compact JWT was compressed with JJWT >= 0.6.0 or another library that you know implements the same behavior.
Default Support
JJWT's default JwtParser implementation supports both the
DEFLATE
and GZIP algorithms by default - you do not need to
specify a CompressionCodecResolver in these cases.
However, if you want to use a compression algorithm other than DEF or GZIP, you must implement
your own CompressionCodecResolver and specify that via this method and also when
building JWTs.
compressionCodecResolver - the compression codec resolver used to decompress the JWT body.JwtParserBuilder base64UrlDecodeWith(Decoder<String,byte[]> base64UrlDecoder)
JJWT uses a spec-compliant decoder that works on all supported JDK versions, but you may call this method to specify a different decoder if you desire.
base64UrlDecoder - the decoder to use when Base64Url-decodingJwtParserBuilder deserializeJsonWith(Deserializer<Map<String,?>> deserializer)
If this method is not called, JJWT will use whatever deserializer it can find at runtime, checking for the
presence of well-known implementations such Jackson, Gson, and org.json. If one of these is not found
in the runtime classpath, an exception will be thrown when one of the various parse* methods is
invoked.
deserializer - the deserializer to use when converting JSON Strings (UTF-8 byte arrays) into Map objects.Copyright © 2014–2022 jsonwebtoken.io. All rights reserved.