REST Service Security (JAD-I-430)

In earlier releases, RESTful web services APIs were not able to be secured; that is, anyone with the URL could consume it without providing authentication.

JADE now provides the ability to restrict JADE REST APIs so that only clients with a valid bearer token can consume the API. In addition, an API developer can customize the rules on what constitute a valid token to meet your requirements.

REST service security allows for the validation of token signatures, including asymmetrical tokens (for example, RS256) signed from third‑party Auth providers. It also allows for the generation of symmetrical tokens (for example, HS256) and the association of required claims such as access level or token expiry against specific REST service methods.

The supported token is JSON Web Token (JWT) – an open standard tracked by RFC 7519. The JWT standard defines a compact and self‑contained way for securely transmitting information between parties represented as a JSON object.

The new Add JSON Web Token Claims dialog enables you to specify the claims that must be present in a JSON Web Token in order to access a JADE REST API method. As long as one or more required claims are associated with a method, any incoming REST request must include a JSON Web Token in the authorization header of the HTTP request; that is, it must include a header of the form Authorization: Bearer <Token>. For details, see "Associating Required JSON Web Token Claims with REST API Methods" under "REST Service Security", in Chapter 2 of the JADE Object Manager Guide.

The new REST security classes are summarized in the following table. (For details, see Volume 1 of the JADE Encyclopaedia of Classes.)

Class	Description
JadeRequiredClaimAnnotation	Abstract class that represents an annotation on a JadeRestService REST API method, requiring a claim to be present in a JSON Web Token (JWT) and the claim to fulfill the validateToken method so that a client can access the associated REST method
JadeRequiredDelegateClaimAnnotation	Represents an annotation on a JadeRestService REST API method, validating the token is done by calling the method referenced by the delegateMethod property
JadeRequiredOneOfValueClaimAnnotation	Represents an annotation on a JadeRestService REST API method, validating the token by comparing the claim in the JWT to each of the values in the allowedValues property
JadeRequiredSingleValueClaimAnnotation	Represents an annotation on a JadeRestService REST API method, validating the token by comparing the claim in the JWT to the value contained in the expectedValue property
JadeJWTModel	Abstract grouping class for JSON Web Token (JWT) classes
JadeJWKSAuthProviderResponse	Can be used as the first parameter to the parse method of the JadeJson class
JadeJWTClaim	Represents one claim in a JSON Web Token
JadeJWTParser	Contains type methods used for parsing JSON Web Tokens
JadeJWTValidator	Contains type methods used for validating the signature claims of JSON Web tokens
JadeJsonWebKeySetReader	Provides methods to obtaining the public key from a JSON Web Key Set that is used to validate asymmetrically‑signed JSON Web Tokens (JWTs)
JadeJsonWebToken	Represents a symmetrically-signed JSON Web Token that can be used by a JADE REST service to generate authorization tokens for its clients

To increase REST service security, use one of the following jadeDevelopmentFunctionSelected function security hooks.

Task Name	Entity Name	Description
applyRestSecurity	Schema‑name::type‑name::method‑name	Applies security to a REST Service method
importOpenAPI	Schema-name	Imports (adds) an OpenAPI specification
removeOpenAPI	Schema-name	Removes an OpenAPI specification

In addition, the:

• JadeRestService class now provides the following methods

  • addBearerToken, which adds a bearer token (for example, a JSON Web Token) to the REST request

  • fetchJWT, which returns the bearer token from the Authorization: Bearer HTTP header of the incoming REST request

  • fetchSecret, which returns the secret with which to validate symmetrically‑signed tokens

  • getTargetMethod, which gets the name of the method targeted by the incoming REST request

  • validateShadowMethod, which returns true if the method is a valid shadow method of a REST service method

  • validateToken, which validates a JSON Web Token against the required claims associated with the specified method

• JadeRestService class now provides the following class constants

  • EncryptionAlg_HS256

  • EncryptionAlg_HS384

  • EncryptionAlg_HS512

  • EncryptionAlg_RS256

  • ServerVariable_AllHttp

  • ServerVariable_AllRaw

  • ShadowMethodPrefix

• JadeHTTPConnection class now provides the following class constants

  • AuthType_Basic

  • AuthType_Bearer

  • HttpResponse_Created

  • HttpResponse_Forbidden

  • HttpResponse_NotFound

  • HttpResponse_Success

  • HttpResponse_Unauthorized

• TimeStamp primitive type now provides the following constant and methods.

  • UnixEpoch constant

  • getSecondsFromUnixEpoch method, which returns the number of seconds between the Unix epoch and the TimeStamp

  • setFromUnixEpoch method, which sets the TimeStamp by adding the specified number of seconds to the Unix epoch