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-format PKCS#8 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, the following are set:
    • 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/>
  <nodeVersionReferenceKeyPair/>
</CreateJWT>

The key can either be passed in using PEM encoding in the <privateKey> element, or as a node that identifies a public/private key pair in the node identified by <nodeVersionReferenceKeyPair>. An error is raised if both are passed. The identified key should contain the public key in the system.NODE_DATA field, and should act as a folder for the private key node which has a local reference of private, and contains the private key field in system.NODE_DATA. If nodeVersionIdentifierKeyPair is set, the "kid" header claim is automatically set to the node version reference of the key pair.

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