What causes "Saml2Exception wrapping exception while signing XMLObject" in spring-projects/spring-security?

Inspect ex.getCause() for the underlying signing failure (KeyException, NoSuchAlgorithmException, etc.)

spring-projects/spring-security · error · Saml2Exception

Saml2Exception wrapping exception while signing XMLObject

Error message

Saml2Exception wrapping exception while signing XMLObject

What it means

The template's sign(SignableXMLObject) method resolves SignatureSigningParameters and delegates to OpenSAML's SignatureSupport.signObject; any exception during signing is wrapped in this Saml2Exception. Root causes are usually credential problems (wrong key type, inaccessible private key) or invalid/unsupported signature algorithm configuration.

Source

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

		OpenSaml5SignatureConfigurer(Collection<Saml2X509Credential> credentials) {
			this.credentials = credentials;
		}

		@Override
		public OpenSaml5SignatureConfigurer algorithms(List<String> algs) {
			this.algs = algs;
			return this;
		}

		@Override
		public <O extends SignableXMLObject> O sign(O object) {
			SignatureSigningParameters parameters = resolveSigningParameters();
			try {
				SignatureSupport.signObject(object, parameters);
			}
			catch (Exception ex) {
				throw new Saml2Exception(ex);
			}
			return object;
		}

		@Override
		public Map<String, String> sign(Map<String, String> params) {
			SignatureSigningParameters parameters = resolveSigningParameters();
			this.components.putAll(params);
			Credential credential = parameters.getSigningCredential();
			Assert.notNull(credential, "credential cannot be null when signing a SAML payload");
			String algorithmUri = parameters.getSignatureAlgorithm();
			Assert.notNull(algorithmUri, "algorithmUri cannot be null when signing a SAML payload");
			this.components.put(Saml2ParameterNames.SIG_ALG, algorithmUri);
			UriComponentsBuilder builder = UriComponentsBuilder.newInstance();
			for (Map.Entry<String, String> component : this.components.entrySet()) {
				builder.queryParam(component.getKey(),
						UriUtils.encode(component.getValue(), StandardCharsets.ISO_8859_1));
			}

View on GitHub (pinned to 96852e8860)

Solutions

Inspect ex.getCause() for the underlying signing failure (KeyException, NoSuchAlgorithmException, etc.)
Verify the signing credential contains a private key and the password/keystore config is correct
Confirm the configured signature algorithm URI is supported by the JVM's crypto providers
Ensure SignatureSigningParametersResolver returns a complete parameter set (credential + signatureAlgorithm + signatureCanonicalizationAlgorithm + KeyInfoGeneratorManager)

Example fix

// before
signingCredential = new BasicCredential(cert); // no private key
// after
signingCredential = new BasicCredential(cert, privateKey); // credential must include private key for signing

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure credential is signing-capable before sign()
Assert.notNull(privateKey, "Signing credential must contain a private key");
Assert.isTrue(SignatureSupport.isCompatibleSignatureAlgorithms(algorithmUri, credential.getPublicKey()),
    "Algorithm incompatible with key");

Try / catch

try {
    return template.sign(signableObject);
} catch (Saml2Exception ex) {
    logger.error("Signing failed: " + ex.getCause(), ex);
    throw ex;
}

Prevention

Verify the keystore password and private key access at startup, not at first sign
Match signature algorithm URI to the key type (RSA vs EC)
Test signing in CI with the production-equivalent credential

When it happens

Trigger: Calling sign(signableObject) when resolveSigningParameters yields parameters with a signing credential that cannot be used (e.g. credential lacks a private key), an unsupported signature algorithm URI, or keystore access fails inside signObject.

Common situations: Signing credential loaded from a JKS/PKCS12 keystore with wrong password; certificate/key pair mismatch; configuring a signature algorithm the JVM provider does not support; OpenSAML SignatureSigningParameters misconfigured by a custom resolver.

Related errors

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