Automatic metadata generation is enabled by including the following filter in the Spring Security configuration:

<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>

This filter is automatically invoked as part of the first request to a URL processed by Spring Security. In case there is no service provider metadata already specified (meaning property hostedSPName of the metadata bean is empty) filter will generate a new one.

By default metadata will be generated with the following values which can be customized by setting properties of the metadataGenerator bean:

In case property entityBaseURL is not specified, it will be automatically generated based on values in the first HTTP request. Generated value can be normalized to exclude standard 80/443 ports for http/https schemes by setting property normalizeBaseUrl of the MetadataGeneratorFilter to true. It is recommended to provide the value explicitly in the configuration.

Providing an empty collection or null value to properties bindingsSSO, bindingsHoKSSO and bindingsSLO will disable and remove the given profile. For example the following setting removes the holder-of-key profile from the generated metadata, forces artifact binding for single sign-on and redirect binding for single logout:

<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
	<property name="bindingsSSO"><list><value>artifact</value></list></property>
	<property name="bindingsSLO"><list><value>redirect</value></list></property>
	<property name="bindingsHoKSSO"><list/></property>
</bean>

By default generated metadata will not be digitally signed. Digital signature can be enabled using property signMetadata of the extendedMetdata bean.

In case application is deployed behind a reverse-proxy or other mechanism which makes the URL at the application server different from the URL seen by client at least property entityBaseURL should be set to a value e.g. https://www.server.com:8080 For details about load balancing see Section 10.1, “Reverse proxies and load balancers”.

In some situations it is beneficial to provide static version of the metadata document instead of the automatic generation. Need for manual changes in the metadata or fixing of production settings are some of those. A custom metadata document describing local SP application can be added by updating the metadata bean with correct ExtendedMetadata. Please follow these steps in order to do so:

Same instance of your application can include multiple statically declared local service providers each differentiated by its own unique alias and entity ID, see Section 7.4, “Multi-tenancy and entity alias” for details. In case your application defines multiple local service providers, set property hostedSPName of the metadata bean to the entity ID of the default one.

The file with pre-configured metadata doesn't need to include digital signature. Metadata will be automatically signed during runtime when property signMetadata is set to true.

For details about available settings of the ExtendedMetadata see Section 7.3, “Extended metadata”.

Metadata describing the default local application can be downloaded from URL:

https://www.server.com:8080/context/saml/metadata

In case the application is configured to contain multiple service providers metadata for each can be loaded by adding the alias:

https://www.server.com:8080/context/saml/login/alias/defaultAlias

URL for metadata download can be disabled by removing filter metadataDisplayFilter from the securityContext.xml.

Metadata is also available in the sample application's administration UI under Metadata information -> selected SP.

File-based provider loads metadata from a file available in the filesystem or classpath.

<bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
	<constructor-arg>
		<bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
			<constructor-arg>
				<value type="java.io.File">classpath:security/idp.xml</value>
			</constructor-arg>
			<property name="parserPool" ref="parserPool"/>
		</bean>
	</constructor-arg>
	<constructor-arg>
		<bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
	</constructor-arg>
</bean>

Metadata is automatically refreshed in intervals specified by properties minRefreshDelay and maxRefreshDelay of the MetadataProvider bean.

HTTP-based provider loads metadata from an URL.

<bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
	<constructor-arg>
		<bean class="org.opensaml.saml2.metadata.provider.HTTPMetadataProvider">
			<constructor-arg>
				<value type="java.lang.String">http://idp.ssocircle.com/idp-meta.xml</value>
			</constructor-arg>
			<constructor-arg>
				<!-- Timeout for metadata loading in ms -->
				<value type="int">5000</value>
			</constructor-arg>
			<property name="parserPool" ref="parserPool"/>
		</bean>
	</constructor-arg>
	<constructor-arg>
		<bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
	</constructor-arg>
</bean>

Metadata is automatically refreshed in intervals specified by properties minRefreshDelay and maxRefreshDelay of the MetadataProvider bean.

Alternatively class org.opensaml.saml2.metadata.provider.FileBackedHTTPMetadataProvider can be used to provide a backup in case URL is temporarily unavailable. File to use as backup is specified as third argument in the MetadataProvider bean constructor.

By default, loading of metadata using the HTTP-based provider over HTTPS performs trust verification configured in your JDK. In case you'd like to use certificates in your keyStore, add the following bean which changes the socketFactory used by the HTTP Client:

<bean class="org.springframework.security.saml.trust.httpclient.TLSProtocolConfigurer"/>

The TLSProtocolConfigurer instantiates TLSProtocolSocketFactory and registers is as a default socket factory for https protocol inside the HTTP Client used for metadata loading. The socket factory uses all public certificates present in the keyStore as trust anchors for PKIX validation. The used keys can be constrained with property trustedKeys.

The socket factory configured in this fashion is used for all metadata providers. It is possible to customize metadata loading on a per-provider basis by adding a configured HttpClient instance to the HTTPMetadataProvider constructor.

Importing of digitally signed metadata requires verification of signature's validity and trust. Metadata is not required to be signed by default. When present, signature is verified with PKIX algorithm and uses all public keys present in the configured keyManager as trust anchors. Make sure to include root CA certificate and intermediary CA certificates of the signature in your keyStore. For details see Section 8.1.3, “Importing public keys”.

You can limit certificates used to peform the verification by setting property metadataTrustedKeys of the ExtendedMetadataDelegate bean. The provided collection should contain aliases of keys to be used as trust anchors.

Signature verification can be disabled by setting property metadataTrustCheck to false in the ExtendedMetadataDelegate bean. Setting metadataRequireSignature to true will reject metadata unless it's digitally signed.