spring-projects/spring-security · error · IllegalArgumentException

Failed to decode SAMLResponse

Error message

Failed to decode SAMLResponse

What it means

Identical acceptability check to the authentication-side Saml2Utils, but in the logout package: after base64-decoding an incoming SAML logout message, the decoded content must start with '<' and contain only acceptable characters, otherwise IllegalArgumentException('Failed to decode SAMLResponse') is thrown. The message text is legacy even though this path handles logout messages.

Source

Thrown at saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/web/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. Verify the IDP's SingleLogoutService binding matches the SP's configured binding (POST sends plain base64 XML)
2. Manually base64-decode the offending parameter and check the leading byte is '<'
3. Check URL-encoding integrity of the form/query parameter through any proxies
4. Regenerate IDP metadata so bindings are negotiated correctly

byte[] decoded = Base64.getDecoder().decode(sloParam);
if (decoded.length == 0 || decoded[0] != '<') {
    throw new IllegalArgumentException("SLO message is not base64-encoded XML");
}

try { /* logout processing */ } catch (IllegalArgumentException ex) {
    log.warn("Malformed SAML logout message", ex);
    response.sendError(HttpServletResponse.SC_BAD_REQUEST);
}

When it happens

Trigger: A SAMLLogoutRequest/SAMLLogoutResponse/SLO parameter whose base64-decoded bytes do not begin with '<' — double-encoded, deflated-but-not-decoded mismatch, corrupted form field, or wrong parameter posted to the logout endpoint.

Common situations: Misconfigured IDP SingleLogout binding (Redirect-style deflated+encoded value sent via POST); corrupted SLO messages through proxies; test tools posting the wrong parameter name.

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
• SAML payload exceeded maximum size of
• relying_party_registration_not_found

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