You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.
Introduction
WS-Security is an extension to the SOAP standard which adds security related features to SOAP messages. This enables messages to be (partially) encrypted and decrypted, their content signed using a digital signature and/or timestamped, in order to guard against request tampering and replay attacks of SOAP messages. Blueriq provides support for this standard in both its exposed SOAP services (using Blueriq as a Service) and the AQ_SoapServiceClient service call, allowing you to achieve end-to-end security for all SOAP processing.Configuration for BAAS SOAP services
SOAP services that are exposed as BAAS can be configured to verify WS-Security information of an incoming SOAP message and apply WS-Security profiles on the outgoing response.
Endpoint group configuration
Incoming SOAP messages can be processed using interceptors, which have to be configured per endpoint groups. Endpoint groups allow you to apply different WS-Security processing for different webservices and/or SOAP-Actions, 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 soap-actions for which it should be activated. It is allowed to omit either or both of these properties, enabling you to activate the endpoint for all messages, all messages for certain webservices or all messages with certain SOAP-Action.
For example, the following configuration defines four endpoint groups, with the last group acting as a catch-all condition.
application.properties
blueriq.baas.soap.endpoints[0].webservices=MySoapService,MySoapService2 blueriq.baas.soap.endpoints[0].soap-actions=MyAction,MyAction2 blueriq.baas.soap.endpoints[0].interceptors=MyInterceptor1,MyInterceptor2 blueriq.baas.soap.endpoints[1].soap-actions=MyAction blueriq.baas.soap.endpoints[1].interceptors=MyInterceptor1 blueriq.baas.soap.endpoints[2].webservices=MySoapService blueriq.baas.soap.endpoints[2].interceptors=MyInterceptor2 blueriq.baas.soap.endpoints[3].interceptors=DefaultInterceptor
SOAP-Actions are matched case-sensitive, so please make sure that you configure the soap-actions value using the exact casing.
Registering an interceptor
An interceptor has to be registered by name using properties, as follows:
application.properties
blueriq.baas.soap.interceptors.security.MyInterceptorName.request.accept-unsecured-messages=false blueriq.baas.soap.interceptors.security.MyInterceptorName.request.decryption.enabled=false blueriq.baas.soap.interceptors.security.MyInterceptorName.request.signature.enabled=false blueriq.baas.soap.interceptors.security.MyInterceptorName.request.timestamp.enabled=false blueriq.baas.soap.interceptors.security.MyInterceptorName.response.encryption.enabled=false blueriq.baas.soap.interceptors.security.MyInterceptorName.response.signature.enabled=false blueriq.baas.soap.interceptors.security.MyInterceptorName.response.timestamp.enabled=false
In the above example you can see how each WS-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.
General properties
| Property name | Default value | Description |
|---|---|---|
| Incoming request processing | ||
request.accept-unsecured-messages | false | Whether or not an incoming request without WS-Security headers should be accepted. Note: this option only affects the behavior of this interceptor. |
Encryption/Decryption
| Property name | Default value | Description |
|---|---|---|
| Incoming request processing | ||
request.decryption.enabled | false | Whether or not an incoming request should be decrypted. |
| 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. |
response.encryption.algorithm | http://www.w3.org/2001/04/xmlenc#aes128-cbc | The symmetric encryption algorithm to use. Allowed values: http://www.w3.org/2001/04/xmlenc#aes128-cbc, http://www.w3.org/2001/04/xmlenc#tripledes-cbc, http://www.w3.org/2001/04/xmlenc#aes256-cbc, http://www.w3.org/2001/04/xmlenc#aes192-cbc |
response.encryption.key-identifier | IssuerSerial | The key identifier type to use. Allowed values: IssuerSerial, X509KeyIdentifier, DirectReference, Thumbprint, SKIKeyIdentifier |
response.encryption.parts | Empty, to encrypt full response | The parts that should be encrypted. By default, the content of the SOAP body is encrypted. Please refer to the Parts configuration chapter below for syntax details. |
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. |
| 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. |
response.signature.key-identifier | IssuerSerial | The key identifier type to use. Allowed values: IssuerSerial, DirectReference |
response.signature.parts | Empty, to sign full response | The parts that should be signed. By default, the content of the SOAP body is signed. Please refer to the Parts configuration chapter below for syntax details. |
UsernameToken*
| Property name | Default value | Description |
|---|---|---|
| Incoming request processing | ||
Not supported. It is recommended to use signature-based validation for communication between Blueriq applications instead of using the UsernamePassword profile. | ||
| Outgoing response processing | ||
response.username-token.enabled | false | Indicates whether the UsernameToken profile is applied to the response. |
response.username-token.username | REQUIRED | |
response.username-token.password | REQUIRED | |
response.username-token.password-type | PasswordDigest | Indicates how the password should be encoded. Allowed values: PasswordDigest, PasswordText |
response.username-token.created | false | Only applicable when |
response.username-token.nonce | false | Only applicable when |
* The UsernameToken profile cannot be configured together with signatures, as the signing key would conflict with the username. If both signing and the UsernameToken profile is needed then separate interceptors have to be configured and registered for the endpoint.
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. |
request.timestamp.time-to-live | 300 | Maximum number of seconds that may have passed since the message's created timestamp. If the message is older, it is rejected. |
request.timestamp.future-time-to-live | 60 | Maximum number of seconds that the message's created timestamp may be in the future, to account for potential clock drift between systems. |
| Outgoing response processing | ||
response.timestamp.enabled | false | Indicates whether a creation and expiration timestamp will be added to the response. |
response.timestamp.precision-in-milliseconds | true | Whether the timestamps should include milliseconds. |
Configuration for AQ_SoapServiceClient
The configuration of AQ_SoapServiceClient allows for the exact same properties as documented above for BAAS 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 SOAP Connections Properties.
Registering an interceptor
An interceptor has to be registered by name using properties, as follows:
application.properties
blueriq.soap.interceptors.security.MyInterceptorName.request.encryption.enabled=false blueriq.soap.interceptors.security.MyInterceptorName.request.signature.enabled=false blueriq.soap.interceptors.security.MyInterceptorName.request.timestamp.enabled=false blueriq.soap.interceptors.security.MyInterceptorName.response.accept-unsecured-messages=false blueriq.soap.interceptors.security.MyInterceptorName.response.decryption.enabled=false blueriq.soap.interceptors.security.MyInterceptorName.response.signature.enabled=false blueriq.soap.interceptors.security.MyInterceptorName.response.timestamp.enabled=false
In the above example you can see how each WS-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.
General properties
| Property name | Default value | Description |
|---|---|---|
| Incoming response processing | ||
response.accept-unsecured-messages | false | Whether or not an incoming response without WS-Security headers should be accepted. |
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. The corresponding private key has to be used when decrypting the message. |
request.encryption.algorithm | http://www.w3.org/2001/04/xmlenc#aes128-cbc | The symmetric encryption algorithm to use. Allowed values: http://www.w3.org/2001/04/xmlenc#aes128-cbc, http://www.w3.org/2001/04/xmlenc#tripledes-cbc, http://www.w3.org/2001/04/xmlenc#aes256-cbc, http://www.w3.org/2001/04/xmlenc#aes192-cbc |
request.encryption.key-identifier | IssuerSerial | The key identifier type to use. Allowed values: IssuerSerial, X509KeyIdentifier, DirectReference, Thumbprint, SKIKeyIdentifier |
request.encryption.parts | Empty, to encrypt full request | The parts that should be encrypted. By default, the content of the SOAP body is encrypted. Please refer to the Parts configuration chapter below for syntax details. |
| Incoming response processing | ||
response.decryption.enabled | false | Whether or not an incoming response should be decrypted. |
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. |
request.signature.key-identifier | IssuerSerial | The key identifier type to use. Allowed values: IssuerSerial, DirectReference |
request.signature.parts | Empty, to sign full request | The parts that should be signed. By default, the content of the SOAP body is signed. Please refer to the Parts configuration chapter below for syntax details. |
| Incoming response processing | ||
response.signature.enabled | false | Whether or not the signature of an incoming response should be verified. |
UsernameToken*
| Property name | Default value | Description |
|---|---|---|
| Outgoing request processing | ||
request.username-token.enabled | false | Indicates whether the UsernameToken profile is applied to the request. |
request.username-token.username | REQUIRED | |
request.username-token.password | REQUIRED | |
request.username-token.password-type | PasswordDigest | Indicates how the password should be encoded. Allowed values: PasswordDigest, PasswordText |
request.username-token.created | false | Only applicable when |
request.username-token.nonce | false | Only applicable when |
| Incoming response processing | ||
| Not supported. It is recommended to use signature-based validation for communication between Blueriq applications instead of using the UsernamePassword profile. | ||
* The UsernameToken profile cannot be configured together with signatures, as the signing key would conflict with the username. If both signing and the UsernameToken profile is needed then separate interceptors have to be configured and registered for the service call.
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. |
request.timestamp.precision-in-milliseconds | true | Whether the timestamps should include milliseconds. |
| Incoming response processing | ||
response.timestamp.enabled | false | Indicates whether the creation and expiration timestamp should be verified. |
response.timestamp.time-to-live | 300 | Maximum number of seconds that may have passed since the message's created timestamp. If the message is older then it is rejected. |
response.timestamp.future-time-to-live | 60 | Maximum number of seconds that the message's created timestamp may be in the future, to account for potential clock drift between systems. |
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.
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.
Parts configuration
Some WS-Security aspects can be applied to only a subset of the message. The relevant profiles provide a parts property to configure this, which requires the following syntax:
- multiple part configurations must be separated by a semi-colon
each value may be preceded by a mode specifier, either
{Content}or{Element}. If not specified it defaults to{Content}the mode specifier may be followed by a namespace specifier. If omitted, it defaults to the SOAP namespace.
- the value must contain the name of the element which must be encrypted
For example, the value {Content}{http://example.org/paymentv2}CreditCard;{Element}{None}Username has the following meaning:
- the content of the
CreditCardelement in the http://example.org/paymentv2 namespace will be encrypted. TheCreditCardelement itself is not encrypted, so any attributes on this element will be in plain text - the
Usernameelement with no namespace is encrypted. The element itself is also encrypted, so any attributes will not be visible in plain text.
Overview
Content Tools