Verify JWT

Description

Verify a JSON Web Token (JWT).

The JWT is verified against a public key passed in as a PEM-encoded string.

In addition to verifying the JWT signature, the service performs the following checks:

  • That the jwt has not expired. If passed, the clockSkew value can be set to a number of additional seconds to allow an expired token, to make up for clockSkew, or for the time taken for a token to be passed to a service.
  • The the JWT "aud" claim, if present, matches the "aud" parameter.
  • If the "iss" parameter is passed, that it matches the "iss" claim in the JWT.
  • If the "scope" parameter is passed, it is treated as a blank-delimited list of scopes and the service checks that each scope is listed in the "scope" claim of the JWT. The scopes do not have to be in order and the JWT may list more scopes. Scopes are case sensitive.

The treatment of aud and iss (and scope) is different. Issuers are only validated if requested (because they are implicitly validated by the key). Audiences are always validated.

The service does not require authorisation.

Input

<VerifyJWT>
<jwt/>
<publicKey/>
<clockSkew/>
<aud/>
<iss/>
<scope/>
</VerifyJWT>

Output

<VerifyJWT>
<errorNumber>0</errorNumber>
<return/>
<scope/>
<sub/>
<name/>
<email/>
</VerifyJWT>

The payload is returned in the return element. (Using the return element provides compatibility with the web service interface that returns JSON, allowing the service to be called directly to parse and validate a JWT and return just the payload.)

The payload is not returned if the JWT fails validation.

As a convenience, the service returns the scope, sub, name and email claims from the payload, but these are only returned if the JWT passes validation. So, for example, you can use the presence of a "sub" field to check for a validated user, and ignore the error field.

Errors

100 - General error. For example, an invalid JWT.
101 - Not authorised. Unlike most services, 101 may return a meaningful user message in the errorMessage field.
103 - Parameter error.

Class

com.metrici.xerula.VerifyJWTService