spring-projects/spring-security · error · IllegalArgumentException

Failed to decode SAMLResponse

Error message

Failed to decode SAMLResponse

What it means

Thrown by the EncodingConfigurer's checkAcceptable when a Base64-decoded SAML input contains characters not acceptable in a SAML XML document. The library validates the decoded string against an acceptability predicate to block invalid/hostile input before parsing; IllegalArgumentException "Failed to decode SAMLResponse" signals the decoded content is not acceptable XML content.

Source

Thrown at saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/authentication/Saml2Utils.java:189

					}
				}

				// in cases of an incomplete final chunk, ensure the unused bits are zero
				switch (goodChars % 4) {
					case 0:
						return true;
					case 2:
						return (lastGoodCharVal & 0b1111) == 0;
					case 3:
						return (lastGoodCharVal & 0b11) == 0;
					default:
						return false;
				}
			}

			void checkAcceptable(String ins) {
				if (!isAcceptable(ins)) {
					throw new IllegalArgumentException("Failed to decode SAMLResponse");
				}
			}

		}

	}

	static class CappedOutputStream extends OutputStream {

		private static final long MAX_SIZE = 1024 * 1024;

		private final OutputStream delegate;

		private int size;

		CappedOutputStream(OutputStream delegate) {
			this.delegate = delegate;
		}

View on GitHub (pinned to 96852e8860)

Solutions

1. Ensure the SAMLResponse is Base64-decoded exactly once with the correct decoder before decoding to string
2. Ensure the decoded XML is valid UTF-8 without control/binary characters
3. Check for proxies/gateways mangling the SAMLResponse query parameter
4. If it appears during a security test, expect the rejection — this check intentionally blocks non-XML input

Example fix

// before
 String xml = new String(Base64.getDecoder().decode(param), StandardCharsets.ISO_8859_1); // wrong charset
// after
 String xml = new String(inflate(Base64.getDecoder().decode(param)), StandardCharsets.UTF_8);

// pre-validate decoded SAML content looks like XML
String xml = new String(inflated, StandardCharsets.UTF_8);
boolean acceptable = xml.startsWith("<") && xml.chars().noneMatch(c -> c < 0x20 && c != '\t' && c != '\n' && c != '\r');

try {
    String xml = Saml2Utils.withDecoded(decoded).checkAcceptable(...);
} catch (IllegalArgumentException e) {
    // reject request: decoded content is not acceptable SAML XML
}

When it happens

Trigger: Saml2Utils.withDecoded(...).checkAcceptable(ins) is called during redirect-binding decoding; isAcceptable(ins) returns false (disallowed characters/encoding tricks) so an IllegalArgumentException with message "Failed to decode SAMLResponse" is thrown.

Common situations: SAMLResponse parameter URL-decoded or Base64-decoded incorrectly (wrong decoder, double decoding) producing garbage; malicious request attempting XML/decoder confusion attacks (the check is a hardening measure); non-UTF8 bytes introduced before inflation.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Failed to decode SAMLResponse
• Failed to decode SAMLResponse
• Failed to decode SAMLResponse
• Failed to decode SAMLResponse
• Failed to decode SAMLResponse

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