JwtParser (JSON Web Token support for the JVM 0.7.0 API)

All Known Implementing Classes:

DefaultJwtParser
```
public interface JwtParser
```
A parser for reading JWT strings, used to convert them into a Jwt object representing the expanded JWT.

Since:

0.1

Field Summary

Fields
Modifier and Type Field and Description

static char SEPARATOR_CHAR

Fields
Modifier and Type	Field and Description
`static char`	`SEPARATOR_CHAR`

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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 base64EncodedKeyBytes)` 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.

- Field Detail
  - SEPARATOR_CHAR
```
static final char SEPARATOR_CHAR
```
    See Also:
    
    Constant Field Values
- Method Detail
  - requireId
```
JwtParser requireId(String id)
```
    Ensures that the specified 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.
    
    Parameters:
    
    id -
    
    Returns:
    
    the parser method for chaining.
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - requireSubject
```
JwtParser requireSubject(String subject)
```
    Ensures that the specified 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.
    
    Parameters:
    
    subject -
    
    Returns:
    
    the parser for method chaining.
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - requireAudience
```
JwtParser requireAudience(String audience)
```
    Ensures that the specified 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.
    
    Parameters:
    
    audience -
    
    Returns:
    
    the parser for method chaining.
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - requireIssuer
```
JwtParser requireIssuer(String issuer)
```
    Ensures that the specified 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.
    
    Parameters:
    
    issuer -
    
    Returns:
    
    the parser for method chaining.
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - requireIssuedAt
```
JwtParser requireIssuedAt(Date issuedAt)
```
    Ensures that the specified 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.
    
    Parameters:
    
    issuedAt -
    
    Returns:
    
    the parser for method chaining.
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - requireExpiration
```
JwtParser requireExpiration(Date expiration)
```
    Ensures that the specified 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.
    
    Parameters:
    
    expiration -
    
    Returns:
    
    the parser for method chaining.
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - requireNotBefore
```
JwtParser requireNotBefore(Date notBefore)
```
    Ensures that the specified 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.
    
    Parameters:
    
    notBefore -
    
    Returns:
    
    the parser for method chaining
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - require
```
JwtParser require(String claimName,
                  Object value)
```
    Ensures that the specified 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.
    
    Parameters:
    
    claimName -
    
    value -
    
    Returns:
    
    the parser for method chaining.
    
    See Also:
    
    MissingClaimException, IncorrectClaimException
  - setClock
```
JwtParser setClock(Clock clock)
```
    Sets the Clock that determines the timestamp to use when validating the parsed JWT. The parser uses a DefaultClock instance by default.
    
    Parameters:
    
    clock - a Clock object to return the timestamp to use when validating the parsed JWT.
    
    Returns:
    
    the parser for method chaining.
    
    Since:
    
    0.7.0
  - setAllowedClockSkewSeconds
```
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.
    
    Parameters:
    
    seconds - the number of seconds to tolerate for clock skew when verifying exp or nbf claims.
    
    Returns:
    
    the parser for method chaining.
    
    Since:
    
    0.7.0
  - setSigningKey
```
JwtParser setSigningKey(byte[] key)
```
    Sets the signing key used to verify any discovered JWS digital signature. If the specified JWT string is not a JWS (no signature), this key is not used.
    
    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.
    
    Parameters:
    
    key - the algorithm-specific signature verification key used to validate any discovered JWS digital signature.
    
    Returns:
    
    the parser for method chaining.
  - setSigningKey
```
JwtParser setSigningKey(String base64EncodedKeyBytes)
```
    Sets the signing key used to verify any discovered JWS digital signature. If the specified JWT string is not a JWS (no signature), this key is not used.
    
    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[]).
    
    Parameters:
    
    base64EncodedKeyBytes - the BASE64-encoded algorithm-specific signature verification key to use to validate any discovered JWS digital signature.
    
    Returns:
    
    the parser for method chaining.
  - setSigningKey
```
JwtParser setSigningKey(Key key)
```
    Sets the signing key used to verify any discovered JWS digital signature. If the specified JWT string is not a JWS (no signature), this key is not used.
    
    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[]).
    
    Parameters:
    
    key - the algorithm-specific signature verification key to use to validate any discovered JWS digital signature.
    
    Returns:
    
    the parser for method chaining.
  - setSigningKeyResolver
```
JwtParser setSigningKeyResolver(SigningKeyResolver signingKeyResolver)
```
    Sets the 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.
    Parameters:
    
    signingKeyResolver - the signing key resolver used to retrieve the signing key.
    
    Returns:
    
    the parser for method chaining.
    
    Since:
    
    0.4
  - setCompressionCodecResolver
```
JwtParser setCompressionCodecResolver(CompressionCodecResolver compressionCodecResolver)
```
    Sets the 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.
    
    Parameters:
    
    compressionCodecResolver - the compression codec resolver used to decompress the JWT body.
    
    Returns:
    
    the parser for method chaining.
    
    Since:
    
    0.6.0
  - isSigned
```
boolean isSigned(String jwt)
```
    Returns 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.
    
    Parameters:
    
    jwt - the compact serialized JWT to check
    
    Returns:
    
    true if the specified JWT compact string represents a signed JWT (aka a 'JWS'), false otherwise.
  - parse
```
Jwt parse(String jwt)
   throws ExpiredJwtException,
          MalformedJwtException,
          SignatureException,
          IllegalArgumentException
```
    Parses the specified compact serialized JWT string based on the builder's current configuration state and returns the resulting JWT or JWS instance.
    
    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.
    
    Parameters:
    
    jwt - the compact serialized JWT to parse
    
    Returns:
    
    the specified compact serialized JWT string based on the builder's current configuration state.
    
    Throws:
    
    MalformedJwtException - 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.
    
    See Also:
    
    parse(String, JwtHandler), parsePlaintextJwt(String), parseClaimsJwt(String), parsePlaintextJws(String), parseClaimsJws(String)
  - parse
```
<T> T parse(String jwt,
            JwtHandler<T> handler)
     throws ExpiredJwtException,
            UnsupportedJwtException,
            MalformedJwtException,
            SignatureException,
            IllegalArgumentException
```
    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.
    
    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:
    Parameters:
    
    jwt - the compact serialized JWT to parse
    
    Returns:
    
    the result returned by the JwtHandler
    
    Throws:
    
    MalformedJwtException - 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.
    
    UnsupportedJwtException
    
    Since:
    
    0.2
    
    See Also:
    
    parsePlaintextJwt(String), parseClaimsJwt(String), parsePlaintextJws(String), parseClaimsJws(String), parse(String)
  - parsePlaintextJwt
```
Jwt<Header,String> parsePlaintextJwt(String plaintextJwt)
                              throws UnsupportedJwtException,
                                     MalformedJwtException,
                                     SignatureException,
                                     IllegalArgumentException
```
    Parses the specified compact serialized JWT string based on the builder's current configuration state and returns the resulting unsigned plaintext JWT instance.
    
    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.
    
    Parameters:
    
    plaintextJwt - a compact serialized unsigned plaintext JWT string.
    
    Returns:
    
    the Jwt instance that reflects the specified compact JWT string.
    
    Throws:
    
    UnsupportedJwtException - if the plaintextJwt argument does not represent an unsigned plaintext JWT
    
    MalformedJwtException - if the plaintextJwt string is not a valid JWT
    
    SignatureException - if the plaintextJwt string is actually a JWS and signature validation fails
    
    IllegalArgumentException - if the plaintextJwt string is null or empty or only whitespace
    
    Since:
    
    0.2
    
    See Also:
    
    parseClaimsJwt(String), parsePlaintextJws(String), parseClaimsJws(String), parse(String, JwtHandler), parse(String)
  - parseClaimsJwt
```
Jwt<Header,Claims> parseClaimsJwt(String claimsJwt)
                           throws ExpiredJwtException,
                                  UnsupportedJwtException,
                                  MalformedJwtException,
                                  SignatureException,
                                  IllegalArgumentException
```
    Parses the specified compact serialized JWT string based on the builder's current configuration state and returns the resulting unsigned plaintext JWT instance.
    
    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.
    
    Parameters:
    
    claimsJwt - a compact serialized unsigned Claims JWT string.
    
    Returns:
    
    the Jwt instance that reflects the specified compact JWT string.
    
    Throws:
    
    UnsupportedJwtException - if the claimsJwt argument does not represent an unsigned Claims JWT
    
    MalformedJwtException - if the claimsJwt string is not a valid JWT
    
    SignatureException - if the claimsJwt string is actually a JWS and signature validation fails
    
    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 claimsJwt string is null or empty or only whitespace
    
    Since:
    
    0.2
    
    See Also:
    
    parsePlaintextJwt(String), parsePlaintextJws(String), parseClaimsJws(String), parse(String, JwtHandler), parse(String)
  - parsePlaintextJws
```
Jws<String> parsePlaintextJws(String plaintextJws)
                       throws UnsupportedJwtException,
                              MalformedJwtException,
                              SignatureException,
                              IllegalArgumentException
```
    Parses the specified compact serialized JWS string based on the builder's current configuration state and returns the resulting plaintext JWS instance.
    
    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.
    
    Parameters:
    
    plaintextJws - a compact serialized JWS string.
    
    Returns:
    
    the Jws instance that reflects the specified compact JWS string.
    
    Throws:
    
    UnsupportedJwtException - if the plaintextJws argument does not represent an plaintext JWS
    
    MalformedJwtException - if the plaintextJws string is not a valid JWS
    
    SignatureException - if the plaintextJws JWS signature validation fails
    
    IllegalArgumentException - if the plaintextJws string is null or empty or only whitespace
    
    Since:
    
    0.2
    
    See Also:
    
    parsePlaintextJwt(String), parseClaimsJwt(String), parseClaimsJws(String), parse(String, JwtHandler), parse(String)
  - parseClaimsJws
```
Jws<Claims> parseClaimsJws(String claimsJws)
                    throws ExpiredJwtException,
                           UnsupportedJwtException,
                           MalformedJwtException,
                           SignatureException,
                           IllegalArgumentException
```
    Parses the specified compact serialized JWS string based on the builder's current configuration state and returns the resulting Claims JWS instance.
    
    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.
    
    Parameters:
    
    claimsJws - a compact serialized Claims JWS string.
    
    Returns:
    
    the Jws instance that reflects the specified compact Claims JWS string.
    
    Throws:
    
    UnsupportedJwtException - if the claimsJws argument does not represent an Claims JWS
    
    MalformedJwtException - if the claimsJws string is not a valid JWS
    
    SignatureException - if the claimsJws JWS signature validation fails
    
    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 claimsJws string is null or empty or only whitespace
    
    Since:
    
    0.2
    
    See Also:
    
    parsePlaintextJwt(String), parseClaimsJwt(String), parsePlaintextJws(String), parse(String, JwtHandler), parse(String)

Interface JwtParser

Field Summary

Method Summary

Field Detail

SEPARATOR_CHAR

Method Detail

requireId

requireSubject

requireAudience

requireIssuer

requireIssuedAt

requireExpiration

requireNotBefore

require

setClock

setAllowedClockSkewSeconds

setSigningKey

setSigningKey

setSigningKey

setSigningKeyResolver

setCompressionCodecResolver

Default Support

isSigned

parse

parse

parsePlaintextJwt

parseClaimsJwt

parsePlaintextJws

parseClaimsJws