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

collectionFromMetadata parses the metadata and builds builders only from EntityDescriptors that contain an IDPSSODescriptor. If the document yielded no usable builders (no IdP role descriptors found, or only SP descriptors), Spring Security throws this Saml2Exception because no asserting party can be derived.

Source

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

	 * for signing AuthnRequests.
	 * @param source the {@link InputStream} source containing the asserting party
	 * metadata
	 * @return the {@link Collection} of {@link RelyingPartyRegistration.Builder}s for
	 * further configuration
	 * @since 5.7
	 */
	public static Collection<RelyingPartyRegistration.Builder> collectionFromMetadata(InputStream source) {
		Collection<RelyingPartyRegistration.Builder> builders = new ArrayList<>();
		for (EntityDescriptor descriptor : OpenSamlMetadataUtils.descriptors(source)) {
			if (descriptor.getIDPSSODescriptor(SAMLConstants.SAML20P_NS) != null) {
				OpenSamlAssertingPartyDetails assertingParty = OpenSamlAssertingPartyDetails
					.withEntityDescriptor(descriptor)
					.build();
				builders.add(RelyingPartyRegistration.withAssertingPartyMetadata(assertingParty));
			}
		}
		if (builders.isEmpty()) {
			throw new Saml2Exception("Metadata response is missing the necessary IDPSSODescriptor element");
		}
		return builders;
	}

}

View on GitHub (pinned to 96852e8860)

Solutions

1. Verify the metadata contains <md:IDPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> elements for the entities you expect
2. Use the correct aggregate or per-entity IdP metadata URL that includes IdP role descriptors
3. Check that server-side scoping/filters aren't returning empty EntitiesDescriptor content for your request
4. Fall back to per-IdP metadata URLs (fromMetadataLocation) instead of an aggregate that lacks IdP descriptors

Example fix

// before: aggregate contains only SPs
collectionFromMetadataLocation("https://federation.example.org/sp-aggregate")
// after: IdP aggregate or explicit entity
collectionFromLocation("https://federation.example.org/idp-aggregate")
// or: fromMetadataLocation("https://idp.example.com/saml/metadata")

Document doc = parseXml(metadataBytes);
NodeList idp = doc.getElementsByTagNameNS("urn:oasis:names:tc:SAML:2.0:metadata", "IDPSSODescriptor");
if (idp.getLength() == 0) throw new IllegalArgumentException("Metadata contains no IDPSSODescriptor");

try {
    return RelyingPartyRegistrations.collectionFromMetadataLocation(location);
} catch (Saml2Exception ex) {
    if (ex.getMessage() != null && ex.getMessage().contains("IDPSSODescriptor")) {
        throw new IllegalStateException("Aggregate has no IdP descriptors — use IdP-specific metadata", ex);
    }
    throw ex;
}

When it happens

Trigger: Calling RelyingPartyRegistrations.collectionFromMetadata/collectionFromMetadataLocation on metadata whose EntityDescriptors lack IDPSSODescriptor role elements — e.g. SP-only aggregates, or EntitiesDescriptor entries that are organization/affiliate descriptors.

Common situations: Pointing at a federation aggregate and filtering entityIDs, but the target entities are SPs not IdPs; metadata version/role mismatch (SSO descriptor under a different namespace or protocol version, e.g. SAML 1.x only); empty EntitiesDescriptor returned by the server for an unauthorized scope.

Related errors

• Metadata response is missing verification certificates, nece
• Metadata response is missing a SingleSignOnService, necessar
• Unsupported element type:
• registration not found
• invalid_destination

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