spring-projects/spring-security · error · Saml2Exception

Saml2Exception wrapping exception while initializing…

Error message

Saml2Exception wrapping exception while initializing metadata resolver and signature validation filter

What it means

resourceBackedMetadataResolver builds a ResourceBackedMetadataResolver plus a SignatureValidationFilter (requireSignedRoot) and initializes the filter; any exception in this setup is wrapped in Saml2Exception. Thrown because failing to initialize the metadata resolver/filter leaves the asserting-party metadata unusable and trust cannot be established.

Solutions

1. Verify the metadata Resource exists and is readable at the given location (classpath vs file path mix-ups are common).
2. Either provide the IDP's signing certificate as a trusted credential for the SignatureValidationFilter, or (only in controlled environments) relax requireSignedRoot(false).
3. Validate the metadata XML is well-formed (xmllint) before wiring it into the repository.
4. Inspect the wrapped exception cause for the precise initialization failure (parser pool, filter, or resolver).

Example fix

// before
Resource metadata = new ClassPathResource("idp-metadata.xml"); // file absent -> init fails
// after
Resource metadata = new FileSystemResource("/etc/saml/idp-metadata.xml");
Assert.state(metadata.exists(), "IDP metadata file missing");
repository = new OpenSaml5AssertingPartyMetadataRepository(metadata, credentials);

Assert.state(metadataResource.exists(), "IDP metadata resource must exist and be readable");
Assert.notEmpty(trustedCredentials, "signature validation requires trusted signing credentials");

try {
    OpenSaml5AssertingPartyMetadataRepository repo =
        new OpenSaml5AssertingPartyMetadataRepository(metadataResource, credentials);
} catch (Saml2Exception ex) {
    logger.error("Metadata resolver initialization failed: {}", ex.getCause() != null ? ex.getCause().getMessage() : ex.getMessage());
}

When it happens

Trigger: Calling OpenSaml5AssertingPartyMetadataRepository metadata construction where filter.initialize() or resolver setup throws: unreadable metadata Resource, invalid XML, unsigned metadata root when signature is required, or missing trusted signature-verification credentials.

Common situations: Metadata file/URL resource missing or not readable at startup; IDP metadata not signed while setRequireSignedRoot(true); metadata signature cannot be verified against provided credentials; malformed XML in the metadata resource; classpath vs filesystem resource mix-up.

Related errors

• Cannot encode certificate
• Failed to deserialize payload
• Failed to deserialize payload
• invalid_destination
• Metadata response is missing a SingleSignOnService…

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

Appendix: source

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

		private ResourceBackedMetadataResolver resourceBackedMetadataResolver() {
			Resource resource = this.resourceLoader.getResource(this.metadataLocation);
			try {
				ResourceBackedMetadataResolver metadataResolver = new ResourceBackedMetadataResolver(
						new SpringResource(resource));
				if (this.verificationCredentials.isEmpty()) {
					return metadataResolver;
				}
				SignatureTrustEngine engine = new ExplicitKeySignatureTrustEngine(
						new CollectionCredentialResolver(this.verificationCredentials),
						DefaultSecurityConfigurationBootstrap.buildBasicInlineKeyInfoCredentialResolver());
				SignatureValidationFilter filter = new SignatureValidationFilter(engine);
				filter.setRequireSignedRoot(true);
				metadataResolver.setMetadataFilter(filter);
				filter.initialize();
				return metadataResolver;
			}
			catch (Exception ex) {
				throw new Saml2Exception(ex);
			}
		}

		private MetadataResolver initialize(ResourceBackedMetadataResolver metadataResolver) {
			ParserPool pool = XMLObjectProviderRegistrySupport.getParserPool();
			Assert.notNull(pool, "ParserPool must be configured");
			metadataResolver.setParserPool(pool);
			return BaseOpenSamlAssertingPartyMetadataRepository.initialize(metadataResolver);
		}

		private static final class SpringResource implements net.shibboleth.shared.resource.Resource {

			private final Resource resource;

			SpringResource(Resource resource) {
				this.resource = resource;
			}

View on GitHub (pinned to 96852e8860)