spring-projects/spring-security · error · IllegalArgumentException

Failed to decode SAMLResponse

Error message

Failed to decode SAMLResponse

What it means

Logout-package EncodingConfigurer checkAcceptable validates that the Base64-decoded SAML logout message contains acceptable characters before parsing, as a hardening measure against decoder-confusion attacks. If isAcceptable(ins) fails it throws IllegalArgumentException "Failed to decode SAMLResponse".

Source

Thrown at saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/authentication/logout/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 parameters are decoded exactly once with the correct Base64 decoder and UTF-8 string conversion
2. Verify no intermediary (proxy, gateway) is corrupting query parameters
3. Reject the request — this validation intentionally blocks non-XML input

Example fix

// before
 String xml = new String(bytes, StandardCharsets.US_ASCII); // drops multibyte chars
// after
 String xml = new String(bytes, StandardCharsets.UTF_8);

String xml = new String(inflated, StandardCharsets.UTF_8);
if (!xml.trim().startsWith("<")) {
    throw new IllegalArgumentException("not XML: reject logout message");
}

try {
    // logout message decoding path
} catch (IllegalArgumentException e) {
    // message contains unacceptable characters: reject request
}

When it happens

Trigger: During logout message decoding, checkAcceptable(ins) is invoked and the decoded string contains disallowed characters — invalid XML content after (optionally inflated) decoding.

Common situations: Malformed or tampered SAMLRequest/SAMLResponse/SAMLLogout parameters; incorrect Base64/URL decoding producing garbage; deliberate attack payloads probing the decoder.

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
• invalid_request
• Unable to deflate string

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