Owns the WS-Security (wsse:Security) header of a SOAP message: the validate list consumes the security the peer sent, the secure list applies fresh security for the next hop. Both lists are optional and run in the order they are written; the whole validate list runs first, and the inbound header is removed at that boundary before secure creates a new one. With no validate list the header is emptied of the tokens the peer sent instead of being forwarded unchecked; only its wsu:Timestamp is kept, since a secure signature may cover it. Header blocks targeted at a different actor are left untouched.
Direction is not part of this element: nest it in request or response to say which message it applies to. A gateway commonly validates what a client sent and re-secures for the backend in one element, and mirrors that on the way back. Use two elements with a transformation between them when the body has to change between validating and re-securing.
A failing check answers with a soap:Fault matching the envelope version of the offending message, carrying the WS-Security fault code (wsse:FailedAuthentication, wsse:FailedCheck, and so on); a body that is not SOAP at all answers with Problem Details, since no fault envelope can be produced for it.
Example Configuration
api:
port: 2000
flow:
- request:
- wsSecurity:
keystore:
location: signing.p12
password: secret
truststore:
location: partner-ca.p12
password: secret
validate:
- timestamp:
clockSkew: PT1M
- usernameToken:
username: ${property.apiUser}
password: ${property.apiPassword}
- signature:
requiredReferences:
- by: BODY
- by: TIMESTAMP
- by: USERNAME_TOKEN
secure:
- timestamp:
ttl: PT5M
- signature:
references:
- by: BODY
- by: TIMESTAMP
- xpath: //*[local-name()='order']
api:
port: 2000
flow:
- request:
- wsSecurity:
keystore:
location: signing.p12
password: secret
truststore:
location: partner-ca.p12
password: secret
validate:
- timestamp:
clockSkew: PT1M
- usernameToken:
username: ${property.apiUser}
password: ${property.apiPassword}
- signature:
requiredReferences:
- by: BODY
- by: TIMESTAMP
- by: USERNAME_TOKEN
secure:
- timestamp:
ttl: PT5M
- signature:
references:
- by: BODY
- by: TIMESTAMP
- xpath: //*[local-name()='order']
Syntax
wsSecurity:
'$ref': <string>
actor: <string>
keystore: {}
mustUnderstand: <boolean>
secure:
- <secureParts>
truststore: {}
validate:
- <validateParts>
xmlConfig: {}
wsSecurity:
'$ref': <string>
actor: <string>
keystore: {}
mustUnderstand: <boolean>
secure:
- <secureParts>
truststore: {}
validate:
- <validateParts>
xmlConfig: {}
Attributes
| Name | Required | Default | Description | Examples |
|---|---|---|---|---|
| $ref | false | - | Reference a component defined under components. | - |
| actor | false | - | The SOAP actor (SOAP 1.1) or role (SOAP 1.2) whose wsse:Security header this element owns. When omitted, that is the header addressed to the ultimate receiver, i.e. the one carrying no actor/role attribute. Headers belonging to any other actor are neither validated nor removed. | http://example.com/gateway |
| mustUnderstand | false | true | Whether the wsse:Security header created by secure carries mustUnderstand, which obliges the next hop to either process the header or answer with a fault instead of ignoring it. | - |
Child Structure
| Element | Cardinality | Description |
|---|---|---|
| keystore | 0..1 | Configuration element for a keystore holding private keys and certificates. |
| secureParts | 0..* | The security applied to the outbound message, in order. |
| truststore | 0..1 | Configuration element for a truststore containing trusted CA certificates. |
| validateParts | 0..* | The checks applied to the inbound wsse:Security header, in order. |
| xmlConfig | 0..1 | Declares additional XML namespace prefixes usable in the xpath attribute of an XPATH reference, in any part. soap, wsse, and wsu are always available, even when this is set. |