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.
- If the "authenticate" parameter is set to true, the "sub" (subject) claim must be present and it is assumed to contain a user logon reference. A check is made that the calling user is permitted to authorise the subject user. If there is no calling user, the authority check is made using the owner of the key pair identified by the nodeVersionReferenceKeyPair parameter or the "kid" claim. If there is no authorising user, or if they are not capable of authorising the subject user, an authorisation error is raised. These checks prevent a key owner from manually generating a JWT with a "sub" claim and then using that to gain unauthorised access.
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.
User credentials are required if the key pair is passed in as a node or to check the sub claim. In most cases these should not be passed.
The public key can be found in one of three ways:
- By passing it in the publicKey.
- By reading it from the system.NODE_DATA field of the node identified by nodeVersionReferenceKeyPair.
- By reading it from the system.NODE_DATA field of the node identified the reference held in the "kid" header claim of the jwt.
The "kid" header claim is only used if neither the public key or node version reference key pair is passed.
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.
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.
102 - Not found, typically because the key node cannot be found.
103 - Parameter error.