WS-Security
UsernameToken, X.509 and SAML for SOAP - inbound enforcement on channels and outgoing headers from one definition.
Overview
A WS-Security definition describes credentials that travel inside a SOAP envelope's wsse:Security header rather than in HTTP headers - the security model of classic enterprise SOAP stacks. One definition serves both directions of traffic:
- Channels - Zato enforces the configured token on SOAP requests before any service code runs.
- Outgoing - Zato adds the
wsse:Securityheader to the envelopes an outgoing SOAP connection sends.
Definitions are managed in the dashboard under Security > WS-Security. Changes take effect immediately, without server restarts.
Definition fields
Each definition is in one of three modes, selected in the create and edit forms, and the mode decides which fields apply.
Fields shared by all modes:
| Field | Notes |
|---|---|
| Name | A unique name for the definition |
| Mode | One of Username token, X.509 or SAML |
| Username | The username inside the token |
Username token mode:
| Field | Notes |
|---|---|
| Password digest | When checked, the password travels as Base64(SHA-1(nonce + created + password)) per the UsernameToken profile - otherwise it travels as clear text, which assumes TLS |
| Password | Set through the definition's change-password action after it is created |
X.509 mode:
| Field | Notes |
|---|---|
| Sign | Whether to sign the envelope's body and timestamp |
| Encrypt | Whether to encrypt the envelope for the peer |
| Signing key | Path to the PEM private key that signs |
| Signing certificate chain | Path to the PEM chain sent along with the signature |
| Decryption key | Path to the PEM private key that decrypts inbound envelopes |
| Peer certificate | Path to the peer's PEM certificate that encryption is for |
| Trust anchors | Path to the PEM CA bundle inbound signatures must chain up to |
A definition in X.509 mode must ask for signing or encryption - one with neither is refused.
SAML mode:
| Field | Notes |
|---|---|
| Issuer | The saml:Issuer of the assertion |
| Subject | The assertion's subject |
| Audience | The audience restriction the assertion carries |
| Sign | Whether the assertion is signed with the X.509 material above |
The definition is exported and imported with enmasse under the security key, with type: wss - the fields are in the enmasse reference.
SOAP channels
Assign a definition to a SOAP channel by selecting WS-Security/<name> in the channel's security dropdown. From then on, every envelope arriving at that channel must carry a wsse:Security header that satisfies the definition, and everything else receives a 401 response.
For a Username token definition, enforcement checks more than the password:
- The password type must be the configured one - a clear-text password sent to a definition that expects a digest is refused, and the other way around.
- With digests, the
wsu:Createdtimestamp must be recent - the default window is 300 seconds, with 60 seconds of allowance for clock skew. - Each nonce may be used once - replayed nonces are refused for the length of the window.
Outgoing connections
The same definition drives outgoing calls. When an outgoing SOAP connection uses a WS-Security definition, Zato builds the wsse:Security header for every envelope the connection sends - a Username token with a fresh nonce and timestamp, a signed or encrypted envelope in X.509 mode, or a SAML assertion - with nothing to add in service code.