spring-projects/spring-security · error · Saml2Exception

Failed to deserialize payload

Error message

Failed to deserialize payload

What it means

OpenSaml5Template.deserialize() wraps any non-Saml2Exception failure — XML parse errors, unmarshalling failures — from parsing or unmarshalling the payload in this Saml2Exception, preserving the cause. It means the input string is not well-formed XML or cannot be unmarshalled into an OpenSAML object tree.

Source

Thrown at saml2/saml2-service-provider/src/opensaml5Main/java/org/springframework/security/saml2/provider/service/registration/OpenSaml5Template.java:160

	@Override
	public <T extends XMLObject> T deserialize(InputStream serialized) {
		try {
			ParserPool pool = XMLObjectProviderRegistrySupport.getParserPool();
			Assert.notNull(pool, "ParserPool must be configured");
			Document document = pool.parse(serialized);
			Element element = document.getDocumentElement();
			UnmarshallerFactory factory = XMLObjectProviderRegistrySupport.getUnmarshallerFactory();
			Unmarshaller unmarshaller = factory.getUnmarshaller(element);
			if (unmarshaller == null) {
				throw new Saml2Exception("Unsupported element of type " + element.getTagName());
			}
			return (T) unmarshaller.unmarshall(element);
		}
		catch (Saml2Exception ex) {
			throw ex;
		}
		catch (Exception ex) {
			throw new Saml2Exception("Failed to deserialize payload", ex);
		}
	}

	@Override
	public OpenSaml5SerializationConfigurer serialize(XMLObject object) {
		Marshaller marshaller = XMLObjectProviderRegistrySupport.getMarshallerFactory().getMarshaller(object);
		Assert.notNull(marshaller, "Marshaller for " + object.getElementQName() + " must be configured");
		try {
			return serialize(marshaller.marshall(object));
		}
		catch (MarshallingException ex) {
			throw new Saml2Exception(ex);
		}
	}

	@Override
	public OpenSaml5SerializationConfigurer serialize(Element element) {
		return new OpenSaml5SerializationConfigurer(element);

View on GitHub (pinned to 96852e8860)

Solutions

1. Decode the input first: new String(Base64.getMimeDecoder().decode(b64), StandardCharsets.UTF_8) before calling deserialize
2. Inspect ex.getCause() to see the exact parse/unmarshall failure and fix the payload accordingly
3. Validate the payload is well-formed XML (e.g. parse with a plain DOM parser) before handing it to the template
4. Reject HTML/error responses from the IdP early instead of attempting to deserialize them

Example fix

// before
Response response = template.deserialize(request.getParameter("SAMLResponse"));
// after
String xml = new String(Base64.getMimeDecoder().decode(request.getParameter("SAMLResponse")), StandardCharsets.UTF_8);
Response response = template.deserialize(xml);

boolean isBase64Xml(String b64) {
    try {
        String xml = new String(Base64.getMimeDecoder().decode(b64), StandardCharsets.UTF_8);
        return xml.trim().startsWith("<");
    } catch (IllegalArgumentException e) { return false; }
}

try {
    return template.deserialize(input);
} catch (Saml2Exception ex) {
    logger.warn("Failed to deserialize payload; cause=" + ex.getCause(), ex);
    throw new BadSamlMessageException(ex);
}

When it happens

Trigger: template.deserialize(String) receiving malformed XML (unclosed tags, bad encoding, base64-decoding done wrong so the string is garbage), an XML document that fails schema-level unmarshalling, or IO/parser configuration errors from the ParserPool.

Common situations: Forgetting to Base64-decode a SAMLResponse form parameter before deserializing; IdP returning an HTML error page; truncated or whitespace-corrupted SAML POST payload; XML with undeclared entity/namespace prefixes.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Failed to deserialize payload
• Failed to deserialize payload
• Failed to deserialize payload
• Failed to deserialize payload
• Unsupported element of type

AI-assisted analysis of spring-projects/spring-security@96852e8860 (2026-09-10). Data as JSON: /api/errors/86fe4ac53d93583e. Report an issue: GitHub.