spring-projects/spring-security · error · Saml2Exception

Metadata response is missing the necessary IDPSSODescriptor

Error message

Metadata response is missing the necessary IDPSSODescriptor element

What it means

OpenSamlAssertingPartyDetails.withEntityDescriptor converts an OpenSAML EntityDescriptor into an asserting-party builder. SAML 2.0 metadata must contain an IDPSSODescriptor for the SAML 2.0 protocol namespace; when the descriptor is absent the method cannot extract keys/endpoints and throws this Saml2Exception.

Source

Thrown at saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/registration/OpenSamlAssertingPartyDetails.java:87

	 * {@link org.springframework.security.saml2.provider.service.registration.RelyingPartyRegistration.AssertingPartyDetails}.
	 * @return the {@link EntityDescriptor}
	 */
	public EntityDescriptor getEntityDescriptor() {
		return this.descriptor;
	}

	/**
	 * Use this {@link EntityDescriptor} to begin building an
	 * {@link org.springframework.security.saml2.provider.service.registration.RelyingPartyRegistration.AssertingPartyDetails}.
	 * @param entity the {@link EntityDescriptor} to use
	 * @return the
	 * {@link org.springframework.security.saml2.provider.service.registration.OpenSamlAssertingPartyDetails.Builder}
	 * for further configurations
	 */
	public static OpenSamlAssertingPartyDetails.Builder withEntityDescriptor(EntityDescriptor entity) {
		IDPSSODescriptor idpssoDescriptor = entity.getIDPSSODescriptor(SAMLConstants.SAML20P_NS);
		if (idpssoDescriptor == null) {
			throw new Saml2Exception("Metadata response is missing the necessary IDPSSODescriptor element");
		}
		List<Saml2X509Credential> verification = new ArrayList<>();
		List<Saml2X509Credential> encryption = new ArrayList<>();
		for (KeyDescriptor keyDescriptor : idpssoDescriptor.getKeyDescriptors()) {
			if (UsageType.SIGNING.equals(keyDescriptor.getUse())) {
				List<X509Certificate> certificates = certificates(keyDescriptor);
				for (X509Certificate certificate : certificates) {
					verification.add(Saml2X509Credential.verification(certificate));
				}
			}
			if (UsageType.ENCRYPTION.equals(keyDescriptor.getUse())) {
				List<X509Certificate> certificates = certificates(keyDescriptor);
				for (X509Certificate certificate : certificates) {
					encryption.add(Saml2X509Credential.encryption(certificate));
				}
			}
			if (UsageType.UNSPECIFIED.equals(keyDescriptor.getUse())) {
				List<X509Certificate> certificates = certificates(keyDescriptor);

View on GitHub (pinned to 96852e8860)

Solutions

Obtain correct IdP metadata that includes an IDPSSODescriptor for the SAML 2.0 protocol namespace
Verify you selected the correct entityID when metadata contains multiple entities
Check the IdP's metadata URL is the SAML 2.0 endpoint, not a SAML 1.x one
If parsing aggregates, filter to entities that contain the IdP SSO role before conversion
Regenerate the metadata from the IdP if it is stale or hand-edited

Example fix

// before
var builder = OpenSamlAssertingPartyDetails.withEntityDescriptor(wrongEntity);
// after: guard on role presence
if (entity.getIDPSSODescriptor(SAMLConstants.SAML20P_NS) == null) {
    throw new Saml2Exception("entity " + entity.getEntityID() + " has no SAML 2.0 IDPSSODescriptor");
}
var builder = OpenSamlAssertingPartyDetails.withEntityDescriptor(entity);

Defensive patterns

Strategy: validation

Validate before calling

boolean hasIdpSsoDescriptor(EntityDescriptor e) {
    return e != null && e.getIDPSSODescriptor(SAMLConstants.SAML20P_NS) != null;
}

Try / catch

try {
    var builder = OpenSamlAssertingPartyDetails.withEntityDescriptor(entity);
} catch (Saml2Exception ex) {
    logger.error("Entity {} lacks SAML 2.0 IDPSSODescriptor", entity.getEntityID());
    throw ex;
}

Prevention

Verify IdP metadata contains IDPSSODescriptor with the SAML20P_NS namespace before conversion
When consuming aggregates, filter entities by IDPSSODescriptor role first
Ensure you fetch SAML 2.0 metadata, not SAML 1.1, from the IdP

When it happens

Trigger: Calling withEntityDescriptor with metadata whose EntityDescriptor lacks an IDPSSODescriptor element in the SAML20P_NS namespace — e.g. SP-only metadata, SAML 1.x-only metadata, or role descriptors under a different namespace.

Common situations: IdP publishes metadata containing only SPSSODescriptor or AttributeAuthorityDescriptor; fetching the wrong entity's metadata from an aggregate; SAML 1.1 IdP metadata supplied to a SAML 2.0 configuration; manually crafted/stale metadata files.

Related errors

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