spring-projects/spring-security · error · Saml2AuthenticationException

internal_validation_error

internal_validation_error

Error message

internalValidationError(ex.getMessage())

What it means

BaseOpenSamlAuthenticationProvider wraps any unexpected Exception raised during SAML response processing into a Saml2AuthenticationException with the internal_validation_error code. It is a catch-all for bugs or unexpected conditions (not standard SAML validation failures), preserving the original exception's message as the cause.

Source

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

	@Override
	public Authentication authenticate(Authentication authentication) throws AuthenticationException {
		try {
			Saml2AuthenticationToken token = (Saml2AuthenticationToken) authentication;
			String serializedResponse = token.getSaml2Response();
			Response response = parseResponse(serializedResponse);
			process(token, response);
			AbstractAuthenticationToken authenticationResponse = this.responseAuthenticationConverter
				.convert(new ResponseToken(response, token));
			if (authenticationResponse != null) {
				authenticationResponse.setDetails(authentication.getDetails());
			}
			return authenticationResponse;
		}
		catch (Saml2AuthenticationException ex) {
			throw ex;
		}
		catch (Exception ex) {
			throw new Saml2AuthenticationException(Saml2Error.internalValidationError(ex.getMessage()), ex);
		}
	}

	@Override
	public boolean supports(Class<?> authentication) {
		return Saml2AuthenticationToken.class.isAssignableFrom(authentication);
	}

	private Response parseResponse(String response) throws Saml2Exception, Saml2AuthenticationException {
		try {
			return this.saml.deserialize(response);
		}
		catch (Exception ex) {
			throw new Saml2AuthenticationException(Saml2Error.malformedResponseData(ex.getMessage()), ex);
		}
	}

	private void process(Saml2AuthenticationToken token, Response response) {

View on GitHub (pinned to 96852e8860)

Solutions

1. Read the wrapped cause (ex.getCause()) — the real fix targets it, not this wrapper
2. Verify RelyingPartyRegistration is fully configured (metadata, IDP entity ID, SSO URL, decryption/signing credentials)
3. Ensure OpenSAML is initialized (OpenSAMLInitializationService.initialize()) in your environment
4. Check that your Spring Security and OpenSAML versions are compatible; upgrade both together

Example fix

// before
RelyingPartyRegistration reg = RelyingPartyRegistration.withRegistrationId("idp").build(); // incomplete
// after
RelyingPartyRegistrations.fromMetadataLocation("https://idp/metadata")
    .registrationId("idp")
    .build();

Assert.notNull(registration.getMetadataLocation(), "metadataLocation required");
Assert.hasText(registration.getEntityId(), "entityId required");
Assert.notEmpty(registration.getAssertionConsumerServiceLocation() != null
    ? List.of(registration.getAssertionConsumerServiceLocation()) : List.of(), "ACS required");
OpenSAMLInitializationService.initialize();

try {
    Authentication result = provider.authenticate(token);
} catch (Saml2AuthenticationException e) {
    if (Saml2ErrorCodes.INTERNAL_VALIDATION_ERROR.equals(e.getError().getErrorCode())) {
        logger.error("SAML internal error", e.getCause()); // fix targets the cause
        throw e;
    }
}

When it happens

Trigger: Any non-Saml2AuthenticationException escaping the try block in authenticate(): e.g. NullPointerException from a misbuilt RelyingPartyRegistration, ClassCastException, or an OpenSAML library error during response evaluation. Standard validation failures instead use their specific error codes.

Common situations: Incomplete RelyingPartyRegistration configuration (missing metadata/IDP info) causing NPEs; incompatible OpenSAML initialization (missing OpenSAMLInitializationService call); version mismatches between Spring Security and OpenSAML; custom converters/validators throwing runtime exceptions.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• malformed_response_data
• decryption_error
• Metadata response is missing verification certificates, nece
• Metadata response is missing a SingleSignOnService, necessar
• Unsupported element type:

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