This is an automated email from the ASF dual-hosted git repository.
coheigea pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ws-wss4j.git
The following commit(s) were added to refs/heads/master by this push:
new d656ae463 Docs update for SAML audience
d656ae463 is described below
commit d656ae46353b1e389b13b3c023d9d7dc3d6fa671
Author: Colm O hEigeartaigh <[email protected]>
AuthorDate: Mon Sep 21 11:16:52 2026 +0100
Docs update for SAML audience
---
THREAT-MODEL.md | 13 +++++++++++++
src/site/asciidoc/best_practice.adoc | 20 ++++++++++++++++++++
2 files changed, 33 insertions(+)
diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md
index d49e08e08..1d649457a 100644
--- a/THREAT-MODEL.md
+++ b/THREAT-MODEL.md
@@ -331,6 +331,7 @@ subset:
| `ENABLE_REVOCATION` | `false` *(documented)* | optional CRL checking |
inbound certificate revocation |
| `ENABLE_SIGNATURE_CONFIRMATION` | `false` *(documented)* | tunable | enables
WS-Security SignatureConfirmation flow |
| `VALIDATE_SAML_SUBJECT_CONFIRMATION` | `true` *(documented)* | hardened |
inbound SAML SubjectConfirmation validation |
+| SAML audience restrictions | empty — no configuration tag; set through
`RequestData.setAudienceRestrictions` or
`WSSSecurityProperties.setAudienceRestrictions` *(documented:
`src/site/asciidoc/best_practice.adoc` §"Restrict the audience of a SAML
assertion")* | strongly recommended; an empty list means an
`AudienceRestriction` condition is not checked at all | which audience URIs an
inbound assertion may name |
| `NONCE_CACHE_INSTANCE` / `TIMESTAMP_CACHE_INSTANCE` /
`SAML_ONE_TIME_USE_CACHE_INSTANCE` | No WSS4J-core default;
`EHCacheReplayCache` supplied by integrations such as CXF *(documented)* |
replay protection on by default for CXF inbound recipient messages; direct
WSS4J callers must configure a cache | replay cache for UsernameToken nonces,
Timestamps, SAML OneTimeUse |
| `PASSWORD_ENCRYPTOR_INSTANCE` | `JasyptPasswordEncryptor` *(documented)* |
tunable | decryption of encrypted passwords in Crypto properties files |
| `merlin.keystore.password` | `"security"` *(documented:
`src/site/asciidoc/config.adoc`)* | **maintainer ruling required** — this is a
*default for the property file*; production deployments override *(inferred —
§14 Q12)* | Merlin keystore password |
@@ -837,6 +838,18 @@ The embedding SOAP stack / application **must**:
`SIG_SUBJECT_CERT_CONSTRAINTS`.** Any cert any CA in the truststore
issued is admitted *(documented:
`src/site/asciidoc/best_practice.adoc`)*.
+- **Accepting a SAML assertion without stating which audience the
+ service will accept.** `SamlAssertionWrapper.checkAudienceRestrictions`
+ returns without checking anything when the supplied list is empty, and
+ it is empty unless the caller sets it — there is no configuration tag,
+ only `RequestData.setAudienceRestrictions` and
+ `WSSSecurityProperties.setAudienceRestrictions`. Any assertion the
+ configured issuer signed is then accepted, including one minted for a
+ different service. Apache CXF sets the list by default for SOAP
+ endpoints, to the request URL and the service QName, so this bites a
+ deployment that drives the WSS4J engine itself *(documented:
+ `src/site/asciidoc/best_practice.adoc` §"Restrict the audience of a
+ SAML assertion")*.
- **Re-enabling RSA v1.5 (`ALLOW_RSA15_KEY_TRANSPORT_ALGORITHM=true`)
for interop with a legacy peer.** Re-introduces the Bleichenbacher
oracle path even though WSS4J's own defense exists.
diff --git a/src/site/asciidoc/best_practice.adoc
b/src/site/asciidoc/best_practice.adoc
index 24345e3ea..2e35d0146 100644
--- a/src/site/asciidoc/best_practice.adoc
+++ b/src/site/asciidoc/best_practice.adoc
@@ -109,6 +109,26 @@ certificate of this issuer will pass trust validation. See
http://coheigea.blogspot.ie/2012/08/subject-dn-certificate-constraint.html[here]
for more information.
+=== Restrict the audience of a SAML assertion
+
+A SAML assertion says who the subject is, not who it was meant for. An
assertion
+that one of your services issued, or accepted, is a perfectly valid assertion
+anywhere else that trusts the same issuer, so a service that does not state
which
+audience it is willing to accept will honour an assertion minted for a
different
+one. Where the assertion carries an AudienceRestriction condition, WSS4J
checks it
+against the list of audience URIs the receiving side supplies - and only
against
+that list. The list is empty unless it is set, and an empty list means the
+condition is not checked at all.
+
+There is no configuration tag for this: set it programmatically, with
+RequestData.setAudienceRestrictions for the DOM code or
+WSSSecurityProperties.setAudienceRestrictions for the streaming code. A web
+services stack may do it for you - Apache CXF supplies the request URL and the
+service QName by default for SOAP endpoints, through
+SecurityConstants.AUDIENCE_RESTRICTIONS, and validates against them unless
+security.validate.audience-restriction is turned off - but a deployment calling
+the WSS4J engine directly gets nothing unless it sets the list itself.
+
=== Specify signature algorithm on receiving side
When not using WS-SecurityPolicy (see point above about favouring the
WS-SecurityPolicy
