You are viewing the documentation for Blueriq 17. 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 name | Default value | Description |
|---|---|---|
| Incoming request processing | ||
request.decryption.enabled | false | Whether or not an incoming request should be decrypted. |
request.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. |
| Outgoing response processing | ||
response.encryption.enabled | false | Indicates 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 name | Default value | Description |
|---|---|---|
| Incoming request processing | ||
request.signature.enabled | false | Whether or not the signature of an incoming request should be verified. |
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. |
| Outgoing response processing | ||
response.signature.enabled | false | Indicates 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 name | Default value | Description |
|---|---|---|
| Incoming request processing | ||
request.timestamp.enabled | false | Whether or not the timestamp of an incoming request should be verified. The expiration time is included in the message |
request.timestamp.max-clock-skew | 300 | 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-ttl | 300 | 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.enabled | false | Indicates whether a creation and expiration timestamp will be added to the response. |
request.timestamp.ttl | 300 | 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 name | Default value | Description |
|---|---|---|
| Outgoing request processing | ||
request.encryption.enabled | false | Indicates 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.enabled | false | Whether 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 name | Default value | Description |
|---|---|---|
| Outgoing request processing | ||
request.signature.enabled | false | Indicates 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.enabled | false | Whether or not the signature of an incoming response should be verified. |
response.signature.key-alias | REQUIRED | The 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 name | Default value | Description |
|---|---|---|
| Outgoing request processing | ||
request.timestamp.enabled | false | Indicates whether a creation and expiration timestamp will be added to the request. |
response.timestamp.ttl | 300 | 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.enabled | false | Indicates whether the creation and expiration timestamp should be verified. |
response.timestamp.max-clock-skew | 300 | 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-ttl | 300 | 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.
Overview
Content Tools