Class SamlAssertionValidator

java.lang.Object
org.apache.juneau.rest.server.auth.saml.SamlAssertionValidator

public class SamlAssertionValidator extends Object
Validates a SAML 2.0 <samlp:Response> document and produces a ClaimsPrincipal marked with issuerType=SAML.

Wraps OpenSAML 5.x's parser, unmarshaller, signature validator, and (optionally) assertion decrypter. The validator enforces:

  • Mandatory assertion signature — every assertion must carry its own enveloped signature. A response that signs only the <Response> envelope (and not the assertion) is rejected as unsigned; response-envelope-level signatures are not supported.
  • Strict signature-algorithm allowlist — only rsa-sha256 and ecdsa-sha256 are accepted out of the box. SHA-1 is permanently rejected. The reference DigestMethod is separately allowlisted (SHA-256/384/512), so a SHA-1 digest is rejected even under a SHA-256 signature.
  • Response status — the <samlp:Status> must report the Success status code.
  • Clock skew — defaults to 60 seconds tolerance on NotBefore / NotOnOrAfter; capped at 300 seconds.
  • Audience restriction — <AudienceRestriction> must list the configured SP entity ID.
  • Bearer subject confirmation — always enforced. The ACS URL configured with SamlAssertionValidator.Builder.recipient(String) is required, and the assertion must carry a bearer <SubjectConfirmation> whose <SubjectConfirmationData> names exactly that Recipient, is within its NotBefore/NotOnOrAfter window (the NotOnOrAfter is mandatory), and satisfies the configured Address expectation. The recipient is never taken from the request. When the response carries a Destination, it must equal the configured ACS URL.
  • Request binding — a confirmation carrying InResponseTo must reference an authentication request ID previously registered with rememberAuthnRequest(String); each ID is accepted once. A confirmation with no InResponseTo (an IdP-initiated response) is rejected unless SamlAssertionValidator.Builder.allowIdpInitiated() was set.
  • One-time use — each assertion ID is recorded in a ReplayCache and a second presentation of the same ID is rejected. The check is fail-closed: if the cache cannot answer, the assertion is rejected. An assertion whose validity window is unbounded — carrying neither a Conditions/NotOnOrAfter nor a bearer SubjectConfirmationData/NotOnOrAfter — is rejected outright, and the cache record is retained until the resolved NotOnOrAfter (plus clock skew) rather than a short default window that would later expire and re-open replay.
  • Encrypted assertions — if the response contains <EncryptedAssertion>, a decryptionCredential must be configured. Only RSA-OAEP key transport and AES-GCM content encryption are accepted, and every decryption problem is reported with the same generic error.

Marker claim

The returned ClaimsPrincipal is annotated with issuerType=SAML so downstream code can distinguish SAML-derived principals from JWT-derived principals without resorting to a subclass:

if ("SAML".equals(principal.getClaim("issuerType", String.class).orElse(null))) { // SAML-issued principal }

Builder usage

The ACS URL is mandatory. Register each outgoing authentication request ID with rememberAuthnRequest(String) so the response can be bound to it.

var validator = SamlAssertionValidator.create() .metadataResolver(SamlMetadataResolvers.url("https://idp.example.com/metadata")) .spEntityId("https://sp.example.com") .expectedIssuer("https://idp.example.com") .recipient("https://sp.example.com/saml/acs") .build();

See Also:

Since:
10.0.0