Security library

The Security library provides features for managing security keys and managing JSON web tokens (JWTs) to manage access to other applications.

(These features require version 4.1.7 - please check with support for details of the version you are running.)

Keys

Use the Key Pair to generate and store a public/private key pair.

Instances of this type hold the public key. The private key is held in a node that uses the public key as a folder, with a local reference of private.

The keys are generated by executing the key pair with the "generate" action. This is performed automatically on initialisation.

It is important that private keys are kept private. Do not permit general access to the private keys. Remember that anyone with administrative access to a containing folder can get access to the private keys.

JWT Creator Script

JWT Creator Script provides support for generating JWTs. See the script documentation for details.

Most solutions will want to use the JWT Manager (see below) to manage JWTs using nodes.

JWT Manager

The JWT Manager provides a mechanism for generating JWTs that contain standard claims (properties) defined in the JWT standard. A JWT manager is configured with the following, all of which are optional unless otherwise stated.

Issuer The issuer of the JWT. Used to build the "iss" claim in the JWT. 
Audience The intended audience (receivers) of the token. Used to build the "aud" claim in the JWT. More than one audience can be entered.
Scope A blank-delimited list of scopes (permissions) to be granted.
Payload script Links to a script to be used to process the payload for the JWT. This can build a payload based on passed in parameters or on other nodes accessible from the instance of the JWT manager.
Expiry period (seconds) The period of time in seconds for which the key should be valid. This is used to build the "exp" claim in the JWT.
Key pair Identifies an instance of Key Pair which holds the private key that will be used to sign the JWT. Required.
Refresh indicator

If the refresh indicator is set, a refresh token will be returned, which can be used to re-request a JWT when the current one expires.

Note: this is not currently implemented.
Refresh expiry period (seconds) The period of time in seconds for which a refresh token should be valid. Defaults to 864,000 (10 days). May not be more than 180 days.

Generating JWTs

Executing the JWT manager will create a JWT. The JWT will be generated with the "sub" claim set the the user logon reference of the caller, and the "name" and "email" claims set to their name and email address.

The calling user does not need to have read authority for the private key in the key pair, but the owner of the JWT manager requires this authority.

The generation returns a block of JSON that is compatible with the OAuth 2.0 token grant. The JSON is returned in the <return> element, allowing it to be returned "as is" when used with the /servicejson/ExecuteScript URL.

The JSON has the following structure.

{
  "access_token": "generated jwt",
  "token_type": "bearer",
  "expires_in": expiryPeriod,
  "scope": "scope",
  "refresh_token": "token"
}

The token_type is always set to "bearer". The expires_in will be the same as the Expiry period (seconds). The scope will the scope after the call to the payload script. If a refresh was requested, the refresh_token will contain a string that can be used to re-request an equivalent JWT.

Payload script

A payload script can be specified. This can modify the payload for the JWT. The payload is passed in as a JavaScript object in the "payload" attribute. This object can be updated, or a new one substituted by replacing the "payload" attribute.

The payload script runs under the authortity of the owner of the JWT manager node. It can access a ScriptUser object for the user who will be the subject of the JWT in the "user" attribute.

The issuer, audience and scope will be written into the object before the script is called, using the "iss", "aud" and "scope" claims. "iss" is a simple string, "aud" is an array of strings, and "scope" is a blank-delimited list of tokens (this follows the JWT standard). The scope will be a merge of the scope defined in the JWT manager plus any tokens in the scope parameter.

The script can modify the payload as required. It must not set a "sub" field (used to identify a user). If the expiry option is set on the JWT manager, this will overwrite any "exp" claim added to the payload script.

Calling using Auth 2.0 parameters

The JWT manager is designed to support Auth 2.0 password and refresh grant types. It must be called through the /auth20/service/ExecuteScript end point. When called through this end point, the following parameter name substitutions are made:

  • The username parameter is translated to userLogonReference, allowing a password grant.
  • The refresh_token parameter is translated to sessionToken, allowing a refresh grant.