Create JWT

Description

Create a JSON Web Token (JWT), signed with a private key. The private key should have been generated with the GenerateKeys service, and is passed in as a PEM-encoded string.

The payload for the JWT is a JSON string with properties known as "claims". It is created in the following manner:

  • Start with the payload parameter, which should be a JSON object. If there is no payload parameter, start with an empty object.
  • Add a "jti" claim set to a generates unique identifier, if the payload does not already contain a "jti" claim.
  • Add a "iat" claim set to the current timestamp, if the payload does not already contain an "iat" claim.
  • If the "aud" parameter is passed, add it as an "aud" claim. The aud parameter only supports a single audience. If you want to specify multiple audiences, pass in an  aud" array in the payload and do not specify the aud parameter.
  • If the "iss" parameter is passed, add it as an "iss" claim.
  • If the "scope" parameter is passed, add it as a "scope" claim.
  • If the "user" parameter is passed, it should hold a user logon reference. If so, set the following:
    • Set the "sub" claim to the user logon reference.
    • Set the "name" claim to the user's name.
    • Set the "email" claim to the user's email.
  • If the "expiry" parameter is passed, it is a number of seconds for which the JWT should be valid. Calculate this time in the future and set the "exp" claim to this timestamp. This is calculated relative to the iat claim. If the iat has been passed in with the payload, the exp claim will be calculated from this.

The aud, iss, scope and user parameters are added as a convenience. The corresponding claims can be passed in the payload instead. However, unlike the jti and iat, these claims will overwrite any already in the payload.

The "sub" claim may not be passed in the payload. The only way of setting the "sub" claim is to pass in a user parameter.

The iat and exp timestamps are coded as "numeric dates", which is the number of seconds since the start of 1970.

The "aud", "iss" and "scope" can be passed in the JSON object in payload parameter or as parameters in their own right. They are available as parameters as a convenience, and for consistency with the ValidateJWT service.

The service would typically be called by the owner of the key, on behalf of another user. If the caller wants to identify themselves as the subject of the JWT, they must pass their own userLogonReference as the user parameter.

Input

<CreateJWT>
<userLogonReference>userid</userLogonReference>
<password>password</password>
<payload/>
<aud/>
<iss/>
<scope/>
<user/>
<expiry/>
<privateKey/>
</CreateJWT>

Output

<CreateJWT>
<errorNumber>0</errorNumber>
<jwt/>
</CreateJWT>

The JWT is returned as a string in the jwt element.

Errors

101 - Not authorised
102 - Not found (this would be user not found)
103 - Parameter error
100 - General error, for example an invalid key

Class

com.metrici.xerula.CreateJWTService