Class SamlAssertionValidator
<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-sha256andecdsa-sha256are accepted out of the box. SHA-1 is permanently rejected. The referenceDigestMethodis 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 theSuccessstatus 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 abearer<SubjectConfirmation>whose<SubjectConfirmationData>names exactly thatRecipient, is within itsNotBefore/NotOnOrAfterwindow (theNotOnOrAfteris mandatory), and satisfies the configuredAddressexpectation. The recipient is never taken from the request. When the response carries aDestination, it must equal the configured ACS URL. - Request binding — a confirmation carrying
InResponseTomust reference an authentication request ID previously registered withrememberAuthnRequest(String); each ID is accepted once. A confirmation with noInResponseTo(an IdP-initiated response) is rejected unlessSamlAssertionValidator.Builder.allowIdpInitiated()was set. - One-time use — each assertion ID is recorded in a
ReplayCacheand 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 aConditions/NotOnOrAfternor a bearerSubjectConfirmationData/NotOnOrAfter— is rejected outright, and the cache record is retained until the resolvedNotOnOrAfter(plus clock skew) rather than a short default window that would later expire and re-open replay. - Encrypted assertions — if the response contains
<EncryptedAssertion>, adecryptionCredentialmust 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:
Builder usage
The ACS URL is mandatory. Register each outgoing authentication request ID with
rememberAuthnRequest(String) so the response can be bound to it.
See Also:
- Since:
- 10.0.0
-
Nested Class Summary
Nested Classes -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringMarker claim name on the returnedClaimsPrincipal.static final StringMarker claim value identifying the principal as SAML-issued. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotectedConstructor. -
Method Summary
Modifier and TypeMethodDescriptioncreate()Static creator.Returns the configured signature algorithm allowlist.Returns the configured clock-skew tolerance.Returns the expected IdP<Issuer>value.Returns the SP entity ID this validator enforces in<AudienceRestriction>.voidRegisters the ID of an authentication request this SP sent, so a response answering it can be accepted.Validates the supplied SAML 2.0<samlp:Response>XML and returns the resolved principal.
-
Field Details
-
ISSUER_TYPE_CLAIM
Marker claim name on the returnedClaimsPrincipal.- See Also:
-
ISSUER_TYPE_SAML
Marker claim value identifying the principal as SAML-issued.- See Also:
-
-
Constructor Details
-
SamlAssertionValidator
Constructor.- Parameters:
b- The builder to read configuration from.
-
-
Method Details
-
create
Static creator.- Returns:
- A new builder.
-
getSpEntityId
Returns the SP entity ID this validator enforces in<AudienceRestriction>.- Returns:
- The configured SP entity ID.
-
getExpectedIssuer
Returns the expected IdP<Issuer>value.- Returns:
- The expected issuer.
-
getAlgorithms
Returns the configured signature algorithm allowlist.- Returns:
- The unmodifiable allowlist.
-
getClockSkew
Returns the configured clock-skew tolerance.- Returns:
- The clock skew.
-
rememberAuthnRequest
Registers the ID of an authentication request this SP sent, so a response answering it can be accepted.Each registered ID is accepted once and expires after the configured request lifetime. The registry is the
AuthnRequestStoresupplied toSamlAssertionValidator.Builder.authnRequestStore(AuthnRequestStore)(in-memory by default).- Parameters:
id- TheIDattribute of the outgoing<AuthnRequest>. Must not benull or blank.- Throws:
IllegalStateException- If the store cannot accept more outstanding requests.
-
validate
Validates the supplied SAML 2.0<samlp:Response>XML and returns the resolved principal.- Parameters:
xml- The full XML payload (already base64-decoded; already URL-decoded and inflated for the REDIRECT binding). Must be a<samlp:Response>envelope.- Returns:
- A
ClaimsPrincipalcarrying the IdP-supplied claims plus theissuerType=SAMLmarker. - Throws:
AuthenticationException- If the response cannot be parsed or validation fails.
-