You are viewing the documentation for Blueriq 16. Documentation for other versions is available in our documentation directory.

Introduction

In line with WS security requirements are placed on securing REST calls not only by a secure https tunnel, but also by encrypting, signing, and timestamping individual REST messages themselves. Despite the lack of a standard, this capability is available and is based on Jose.

Implementation details

The current implementation has the following specification:

  • Uses an asymmetric RSA-OAEP-256 encryption algorithm with a A128CBC-HS256 encryption method. 
  • Only the message body and response are secured, not on the URN.
  • Error-responses (HTTP-4xx and HTTP-5xx) are not secured.
  • Mimetype of request and response must be the same

Configuration

Endpoint configuration

Incoming REST messages can be processed using interceptors, which have to be configured using endpoint groups. Endpoint groups allow you to apply different REST security processing for different webservices, which may be desirable if only a subset of endpoints have to apply a certain interceptor.

Endpoint groups have to be configured in property files as lists. The list enables you to configure multiple endpoint groups, where each endpoint group is matched in order: the first endpoint that matches an incoming message is used to determine the set of interceptors that are being used. Each endpoint group can specify the name(s) of webservices and/or operations for which it should be activated. It is allowed to omit the operations property , enabling you to activate the endpoint for all operations for certain webservices.

For example, the following configuration defines two endpoint groups

application.properties
blueriq.baas.rest.endpoints[0].webservices=MyRestService,MyRestService2
blueriq.baas.rest.endpoints[0].operations=MyOperation,MyOperation2
blueriq.baas.rest.endpoints[0].interceptors=MyInterceptor1
  
blueriq.baas.rest.endpoints[1].webservices=MyRestService
blueriq.baas.rest.endpoints[1].interceptors=MyInterceptor2

All names are matched case-sensitive

Registering an interceptor

An interceptor has to be registered by name using properties, as follows:

application.properties
blueriq.rest.interceptor.server.security.MyInterceptorName.request.decryption.enabled=false
blueriq.rest.interceptor.server.security.MyInterceptorName.request.signature.enabled=false
blueriq.rest.interceptor.server.security.MyInterceptorName.request.timestamp.enabled=false
blueriq.rest.interceptor.server.security.MyInterceptorName.response.encryption.enabled=false
blueriq.rest.interceptor.server.security.MyInterceptorName.response.signature.enabled=false
blueriq.rest.interceptor.server.security.MyInterceptorName.response.timestamp.enabled=false

In the above example you can see how each REST security profile can be enabled/disabled. A profile is disabled by default, so the above enabled  properties are redundant and are only shown to clarify the configuration. Properties that are marked as REQUIRED only have to be provided when the corresponding group is enabled.

Encryption/Decryption

Property nameDefault valueDescription
Incoming request processing
request.decryption.enabledfalseWhether or not an incoming request should be decrypted.
request.decryption.key-aliasREQUIREDThe name of the private key in the configured keystore (see Keystore chapter below) which should be used to encrypt the message.
Outgoing response processing
response.encryption.enabledfalseIndicates whether the response will be encrypted.
response.encryption.key-alias

REQUIRED

The name of the public key in the configured keystore (see Keystore chapter below) which should be used to encrypt the message. The corresponding private key has to be used when decrypting the message.

Signing

Property nameDefault valueDescription
Incoming request processing
request.signature.enabledfalseWhether or not the signature of an incoming request should be verified.
request.signature.key-aliasREQUIREDThe name of the private key in the configured keystore (see Keystore chapter below) which should be used to sign the message. The corresponding public key can be used to verify the signature.
Outgoing response processing
response.signature.enabledfalseIndicates whether the response will be signed.
response.signature.key-alias

REQUIRED

The name of the private key in the configured keystore (see Keystore chapter below) which should be used to sign the message. The corresponding public key can be used to verify the signature.

Timestamp

Property nameDefault valueDescription
Incoming request processing
request.timestamp.enabledfalseWhether or not the timestamp of an incoming request should be verified. The expiration time is included in the message
request.timestamp.max-clock-skew300

Maximum number of seconds the clock of the other system is allowed to deviate from the receiving system.

Introduced in Blueriq 18.6.1. In Blueriq 18.6.0, the value would always be 0, which might cause problems when clocks are not exactly synchronized.

request.timestamp.max-ttl300

Maximum time to live: maximum allowed number of seconds between the message's created and expires timestamp. If this number is greater than the specified max ttl, it is rejected.

Introduced in Blueriq 18.6.1. In Blueriq 18.6.0, the value would always be 300.

Outgoing response processing
response.timestamp.enabledfalseIndicates whether a creation and expiration timestamp will be added to the response.
request.timestamp.ttl300

Time to live: maximum number of seconds that may have passed since the message's created timestamp. If the message is older, it should be rejected by the receiver.

Configuration for AQ_RestServiceClient

The configuration of AQ_RestServiceClient allows for the exact same properties as documented above for BAARS webservices, however the request and response properties have been swapped.

Connection configuration

Security interceptors can be configured on a per-connection basis as described in the Connection properties

Registering an interceptor

An interceptor has to be registered by name using properties, as follows:

application.properties
blueriq.rest.interceptor.client.security.MyInterceptorName.request.encryption.enabled=false
blueriq.rest.interceptor.client.security.MyInterceptorName.request.signature.enabled=false
blueriq.rest.interceptor.client.security.MyInterceptorName.request.timestamp.enabled=false
blueriq.rest.interceptor.client.security.MyInterceptorName.response.accept-unsecured-messages=false
blueriq.rest.interceptor.client.security.MyInterceptorName.response.decryption.enabled=false
blueriq.rest.interceptor.client.security.MyInterceptorName.response.signature.enabled=false
blueriq.rest.interceptor.client.security.MyInterceptorName.response.timestamp.enabled=false

In the above example you can see how each REST security profile can be enabled/disabled. A profile is disabled by default, so the above enabled  properties are redundant and are only shown to clarify the configuration. Properties that are marked as REQUIRED only have to be provided when the corresponding group is enabled.

Encryption/Decryption

Property nameDefault valueDescription
Outgoing request processing
request.encryption.enabledfalseIndicates whether the request will be encrypted.
request.encryption.key-alias

REQUIRED

The name of the public key in the configured keystore (see Keystore chapter below) which should be used to encrypt the message. 
Incoming response processing
response.decryption.enabledfalseWhether or not an incoming response should be decrypted.
response.decryption.key-alias

REQUIRED

The name of the private key in the configured keystore (see Keystore chapter below) which should be used to encrypt the message. 

Signing

Property nameDefault valueDescription
Outgoing request processing
request.signature.enabledfalseIndicates whether the request will be signed.
request.signature.key-alias

REQUIRED

The name of the private key in the configured keystore (see Keystore chapter below) which should be used to sign the message. The corresponding public key can be used to verify the signature.
Incoming response processing
response.signature.enabledfalseWhether or not the signature of an incoming response should be verified.
response.signature.key-alias


REQUIREDThe name of the public key in the configured keystore (see Keystore chapter below) which should be used to sign the message. The corresponding private key is used to sign the message.

Timestamp

Property nameDefault valueDescription
Outgoing request processing
request.timestamp.enabledfalseIndicates whether a creation and expiration timestamp will be added to the request.
response.timestamp.ttl300

Time to live: maximum number of seconds that may have passed since the message's created timestamp. If the message is older, it should be rejected by the receiver.

Incoming response processing
response.timestamp.enabledfalseIndicates whether the creation and expiration timestamp should be verified.
response.timestamp.max-clock-skew300

Maximum number of seconds the clock of the other system is allowed to deviate from the receiving system.

Introduced in Blueriq 18.6.1. In Blueriq 18.6.0, the value would always be 0, which might cause problems when clocks are not exactly synchronized.

response.timestamp.max-ttl300

Maximum time to live: maximum allowed number of seconds between the message's created and expires timestamp. If this number is greater than the specified max ttl, it is rejected.

Introduced in Blueriq 18.6.1. In Blueriq 18.6.0, the value would always be 300.

Keystore configuration

Since WS-Security is based on symmetric cryptography operations, a public/private key pair is used to encrypt/decrypt and to perform signing and signature validation. These keys have to be stored in a keystore in JKS format (Java KeyStore, .jks extension) or PKCS #12 format (.p12 extension) , which has to be configured as follows:

blueriq.security.keystore.location=file://client.jks
blueriq.security.keystore.password=

Password encryption

The configured passwords can be encrypted using the property encryption tool.

How to replace implementation with custom implementation

Because there is no standard defined for rest message security, is is possible that customers define and use their own. In order to facilitate this, this implementation can be overridden with a custom implementation. In this custom implementation both the client and server components need to be replaced.

For the client the custom runtime needs to contain its own implementation of  com.blueriq.component.api.restsecurity.ISecureMessageInterceptorFactory Bean. This bean must override the default implementation by annotating it as @Primary..

For the server the custom implementation must implement a new Spring Filter and register this component for the url /server/rest/* with an order of 400.