You are viewing the documentation for Blueriq 15. 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

Since Blueriq 14.9 you can configure SOAP services that are exposed as BAAS 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 nameDefault valueDescription
Incoming request processing
request.accept-unsecured-messagesfalse

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 nameDefault valueDescription
Incoming request processing
request.decryption.enabledfalseWhether or not an incoming request should be decrypted.
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.
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-identifierIssuerSerialThe key identifier type to use.

Allowed values:

IssuerSerial, X509KeyIdentifier, DirectReference, Thumbprint, SKIKeyIdentifier 
response.encryption.partsEmpty, 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 nameDefault valueDescription
Incoming request processing
request.signature.enabledfalseWhether or not the signature of an incoming request should be verified.
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.
response.signature.key-identifierIssuerSerialThe key identifier type to use.

Allowed values:

IssuerSerial, DirectReference
response.signature.partsEmpty, 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 nameDefault valueDescription
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.enabledfalseIndicates whether the UsernameToken profile is applied to the response.
response.username-token.username

REQUIRED


response.username-token.password

REQUIRED


response.username-token.password-typePasswordDigestIndicates how the password should be encoded.

Allowed values:

PasswordDigest, PasswordText
response.username-token.createdfalse

Only applicable when PasswordText is used. With PasswordText, a wsu:Created element is omitted by default unless this property is set to true.

response.username-token.noncefalse

Only applicable when PasswordText is used. With PasswordText, a wsu:Nonce element is omitted by default unless this property is set to true.

* 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 nameDefault valueDescription
Incoming request processing
request.timestamp.enabledfalseWhether or not the timestamp of an incoming request should be verified.
request.timestamp.time-to-live300Maximum 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-live60Maximum 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.enabledfalseIndicates whether a creation and expiration timestamp will be added to the response.
response.timestamp.precision-in-millisecondstrueWhether 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 nameDefault valueDescription
Incoming response processing
response.accept-unsecured-messagesfalseWhether or not an incoming response without WS-Security headers should be accepted.

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. 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-identifierIssuerSerialThe key identifier type to use.

Allowed values:

IssuerSerial, X509KeyIdentifier, DirectReference, Thumbprint, SKIKeyIdentifier 
request.encryption.partsEmpty, 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.enabledfalseWhether or not an incoming response should be decrypted.

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.
request.signature.key-identifierIssuerSerialThe key identifier type to use.

Allowed values:

IssuerSerial, DirectReference
request.signature.partsEmpty, 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.enabledfalseWhether or not the signature of an incoming response should be verified.

UsernameToken*

Property nameDefault valueDescription
Outgoing request processing
request.username-token.enabledfalseIndicates whether the UsernameToken profile is applied to the request.
request.username-token.username

REQUIRED


request.username-token.password

REQUIRED


request.username-token.password-typePasswordDigestIndicates how the password should be encoded.

Allowed values:

PasswordDigest, PasswordText
request.username-token.createdfalse

Only applicable when PasswordText is used. With PasswordText, a wsu:Created element is omitted by default unless this property is set to true.

request.username-token.noncefalse

Only applicable when PasswordText is used. With PasswordText, a wsu:Nonce element is omitted by default unless this property is set to true.

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 nameDefault valueDescription
Outgoing request processing
request.timestamp.enabledfalseIndicates whether a creation and expiration timestamp will be added to the request.
request.timestamp.precision-in-millisecondstrueWhether the timestamps should include milliseconds.
Incoming response processing
response.timestamp.enabledfalseIndicates whether the creation and expiration timestamp should be verified.
response.timestamp.time-to-live300Maximum 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-live60Maximum 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 CreditCard element in the http://example.org/paymentv2 namespace will be encrypted. The CreditCard element itself is not encrypted, so any attributes on this element will be in plain text 
  • the Username element with no namespace is encrypted. The element itself is also encrypted, so any attributes will not be visible in plain text.