public interface JwtParser
Jwt object representing the expanded JWT.| Modifier and Type | Field and Description |
|---|---|
static char |
SEPARATOR_CHAR |
| Modifier and Type | Method and Description |
|---|---|
JwtParser |
base64UrlDecodeWith(Decoder<String,byte[]> base64UrlDecoder)
Perform Base64Url decoding with the specified Decoder
|
JwtParser |
deserializeJsonWith(Deserializer<Map<String,?>> deserializer)
Uses the specified deserializer to convert JSON Strings (UTF-8 byte arrays) into Java Map objects.
|
boolean |
isSigned(String jwt)
Returns
true if the specified JWT compact string represents a signed JWT (aka a 'JWS'), false
otherwise. |
Jwt |
parse(String jwt)
Parses the specified compact serialized JWT string based on the builder's current configuration state and
returns the resulting JWT or JWS instance.
|
<T> T |
parse(String jwt,
JwtHandler<T> handler)
Parses the specified compact serialized JWT string based on the builder's current configuration state and
invokes the specified
handler with the resulting JWT or JWS instance. |
Jws<Claims> |
parseClaimsJws(String claimsJws)
Parses the specified compact serialized JWS string based on the builder's current configuration state and
returns
the resulting Claims JWS instance.
|
Jwt<Header,Claims> |
parseClaimsJwt(String claimsJwt)
Parses the specified compact serialized JWT string based on the builder's current configuration state and
returns
the resulting unsigned plaintext JWT instance.
|
Jws<String> |
parsePlaintextJws(String plaintextJws)
Parses the specified compact serialized JWS string based on the builder's current configuration state and
returns
the resulting plaintext JWS instance.
|
Jwt<Header,String> |
parsePlaintextJwt(String plaintextJwt)
Parses the specified compact serialized JWT string based on the builder's current configuration state and
returns
the resulting unsigned plaintext JWT instance.
|
JwtParser |
require(String claimName,
Object value)
Ensures that the specified
claimName exists in the parsed JWT. |
JwtParser |
requireAudience(String audience)
Ensures that the specified
aud exists in the parsed JWT. |
JwtParser |
requireExpiration(Date expiration)
Ensures that the specified
exp exists in the parsed JWT. |
JwtParser |
requireId(String id)
Ensures that the specified
jti exists in the parsed JWT. |
JwtParser |
requireIssuedAt(Date issuedAt)
Ensures that the specified
iat exists in the parsed JWT. |
JwtParser |
requireIssuer(String issuer)
Ensures that the specified
iss exists in the parsed JWT. |
JwtParser |
requireNotBefore(Date notBefore)
Ensures that the specified
nbf exists in the parsed JWT. |
JwtParser |
requireSubject(String subject)
Ensures that the specified
sub exists in the parsed JWT. |
JwtParser |
setAllowedClockSkewSeconds(long seconds)
Sets the amount of clock skew in seconds to tolerate when verifying the local time against the
exp
and nbf claims. |
JwtParser |
setClock(Clock clock)
Sets the
Clock that determines the timestamp to use when validating the parsed JWT. |
JwtParser |
setCompressionCodecResolver(CompressionCodecResolver compressionCodecResolver)
Sets the
CompressionCodecResolver used to acquire the CompressionCodec that should be used to
decompress the JWT body. |
JwtParser |
setSigningKey(byte[] key)
Sets the signing key used to verify any discovered JWS digital signature.
|
JwtParser |
setSigningKey(Key key)
Sets the signing key used to verify any discovered JWS digital signature.
|
JwtParser |
setSigningKey(String base64EncodedSecretKey)
Sets the signing key used to verify any discovered JWS digital signature.
|
JwtParser |
setSigningKeyResolver(SigningKeyResolver signingKeyResolver)
Sets the
SigningKeyResolver used to acquire the signing key that should be used to verify
a JWS's signature. |
static final char SEPARATOR_CHAR
JwtParser 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 - MissingClaimException,
IncorrectClaimExceptionJwtParser 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 - MissingClaimException,
IncorrectClaimExceptionJwtParser 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 - MissingClaimException,
IncorrectClaimExceptionJwtParser 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 - MissingClaimException,
IncorrectClaimExceptionJwtParser 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 - MissingClaimException,
IncorrectClaimExceptionJwtParser 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 - MissingClaimException,
IncorrectClaimExceptionJwtParser 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 - MissingClaimException,
IncorrectClaimExceptionJwtParser 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 - value - MissingClaimException,
IncorrectClaimExceptionJwtParser 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.JwtParser setAllowedClockSkewSeconds(long seconds)
exp
and nbf claims.seconds - the number of seconds to tolerate for clock skew when verifying exp or nbf claims.JwtParser 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.JwtParser setSigningKey(String base64EncodedSecretKey)
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[]).
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 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.JwtParser 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.JwtParser 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.JwtParser 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.
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.JwtParser 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-decodingJwtParser 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.boolean isSigned(String jwt)
true if the specified JWT compact string represents a signed JWT (aka a 'JWS'), false
otherwise.
Note that if you are reasonably sure that the token is signed, it is more efficient to attempt to parse the token (and catching exceptions if necessary) instead of calling this method first before parsing.
jwt - the compact serialized JWT to checktrue if the specified JWT compact string represents a signed JWT (aka a 'JWS'), false
otherwise.Jwt parse(String jwt) throws ExpiredJwtException, MalformedJwtException, SignatureException, IllegalArgumentException
This method returns a JWT or JWS based on the parsed string. Because it may be cumbersome to determine if it
is a JWT or JWS, or if the body/payload is a Claims or String with instanceof checks, the
parse(String,JwtHandler) method allows for a type-safe callback approach that
may help reduce code or instanceof checks.
jwt - the compact serialized JWT to parseMalformedJwtException - if the specified JWT was incorrectly constructed (and therefore invalid).
Invalid
JWTs should not be trusted and should be discarded.SignatureException - if a JWS signature was discovered, but could not be verified. JWTs that fail
signature validation should not be trusted and should be discarded.ExpiredJwtException - if the specified JWT is a Claims JWT and the Claims has an expiration time
before the time this method is invoked.IllegalArgumentException - if the specified string is null or empty or only whitespace.SignatureExceptionparse(String, JwtHandler),
parsePlaintextJwt(String),
parseClaimsJwt(String),
parsePlaintextJws(String),
parseClaimsJws(String)<T> T parse(String jwt, JwtHandler<T> handler) throws ExpiredJwtException, UnsupportedJwtException, MalformedJwtException, SignatureException, IllegalArgumentException
handler with the resulting JWT or JWS instance.
If you are confident of the format of the JWT before parsing, you can create an anonymous subclass using the
JwtHandlerAdapter and override only the methods you know are relevant
for your use case(s), for example:
String compactJwt = request.getParameter("jwt"); //we are confident this is a signed JWS
String subject = Jwts.parser().setSigningKey(key).parse(compactJwt, new JwtHandlerAdapter<String>() {
@Override
public String onClaimsJws(Jws<Claims> jws) {
return jws.getBody().getSubject();
}
});
If you know the JWT string can be only one type of JWT, then it is even easier to invoke one of the following convenience methods instead of this one:
jwt - the compact serialized JWT to parseJwtHandlerMalformedJwtException - if the specified JWT was incorrectly constructed (and therefore invalid).
Invalid JWTs should not be trusted and should be discarded.SignatureException - if a JWS signature was discovered, but could not be verified. JWTs that fail
signature validation should not be trusted and should be discarded.ExpiredJwtException - if the specified JWT is a Claims JWT and the Claims has an expiration time
before the time this method is invoked.IllegalArgumentException - if the specified string is null or empty or only whitespace, or if the
handler is null.UnsupportedJwtExceptionSignatureExceptionparsePlaintextJwt(String),
parseClaimsJwt(String),
parsePlaintextJws(String),
parseClaimsJws(String),
parse(String)Jwt<Header,String> parsePlaintextJwt(String plaintextJwt) throws UnsupportedJwtException, MalformedJwtException, SignatureException, IllegalArgumentException
This is a convenience method that is usable if you are confident that the compact string argument reflects an unsigned plaintext JWT. An unsigned plaintext JWT has a String (non-JSON) body payload and it is not cryptographically signed.
If the compact string presented does not reflect an unsigned plaintext JWT with non-JSON string body,
an UnsupportedJwtException will be thrown.
plaintextJwt - a compact serialized unsigned plaintext JWT string.Jwt instance that reflects the specified compact JWT string.UnsupportedJwtException - if the plaintextJwt argument does not represent an unsigned plaintext
JWTMalformedJwtException - if the plaintextJwt string is not a valid JWTSignatureException - if the plaintextJwt string is actually a JWS and signature validation
failsIllegalArgumentException - if the plaintextJwt string is null or empty or only whitespaceSignatureExceptionparseClaimsJwt(String),
parsePlaintextJws(String),
parseClaimsJws(String),
parse(String, JwtHandler),
parse(String)Jwt<Header,Claims> parseClaimsJwt(String claimsJwt) throws ExpiredJwtException, UnsupportedJwtException, MalformedJwtException, SignatureException, IllegalArgumentException
This is a convenience method that is usable if you are confident that the compact string argument reflects an
unsigned Claims JWT. An unsigned Claims JWT has a Claims body and it is not cryptographically
signed.
If the compact string presented does not reflect an unsigned Claims JWT, an
UnsupportedJwtException will be thrown.
claimsJwt - a compact serialized unsigned Claims JWT string.Jwt instance that reflects the specified compact JWT string.UnsupportedJwtException - if the claimsJwt argument does not represent an unsigned Claims JWTMalformedJwtException - if the claimsJwt string is not a valid JWTSignatureException - if the claimsJwt string is actually a JWS and signature validation
failsExpiredJwtException - if the specified JWT is a Claims JWT and the Claims has an expiration time
before the time this method is invoked.IllegalArgumentException - if the claimsJwt string is null or empty or only whitespaceSignatureExceptionparsePlaintextJwt(String),
parsePlaintextJws(String),
parseClaimsJws(String),
parse(String, JwtHandler),
parse(String)Jws<String> parsePlaintextJws(String plaintextJws) throws UnsupportedJwtException, MalformedJwtException, SignatureException, IllegalArgumentException
This is a convenience method that is usable if you are confident that the compact string argument reflects a plaintext JWS. A plaintext JWS is a JWT with a String (non-JSON) body (payload) that has been cryptographically signed.
If the compact string presented does not reflect a plaintext JWS, an UnsupportedJwtException
will be thrown.
plaintextJws - a compact serialized JWS string.Jws instance that reflects the specified compact JWS string.UnsupportedJwtException - if the plaintextJws argument does not represent an plaintext JWSMalformedJwtException - if the plaintextJws string is not a valid JWSSignatureException - if the plaintextJws JWS signature validation failsIllegalArgumentException - if the plaintextJws string is null or empty or only whitespaceSignatureExceptionparsePlaintextJwt(String),
parseClaimsJwt(String),
parseClaimsJws(String),
parse(String, JwtHandler),
parse(String)Jws<Claims> parseClaimsJws(String claimsJws) throws ExpiredJwtException, UnsupportedJwtException, MalformedJwtException, SignatureException, IllegalArgumentException
This is a convenience method that is usable if you are confident that the compact string argument reflects a
Claims JWS. A Claims JWS is a JWT with a Claims body that has been cryptographically signed.
If the compact string presented does not reflect a Claims JWS, an UnsupportedJwtException will be
thrown.
claimsJws - a compact serialized Claims JWS string.Jws instance that reflects the specified compact Claims JWS string.UnsupportedJwtException - if the claimsJws argument does not represent an Claims JWSMalformedJwtException - if the claimsJws string is not a valid JWSSignatureException - if the claimsJws JWS signature validation failsExpiredJwtException - if the specified JWT is a Claims JWT and the Claims has an expiration time
before the time this method is invoked.IllegalArgumentException - if the claimsJws string is null or empty or only whitespaceSignatureExceptionparsePlaintextJwt(String),
parseClaimsJwt(String),
parsePlaintextJws(String),
parse(String, JwtHandler),
parse(String)Copyright © 2020. All rights reserved.