Package org.apache.juneau.rest.server.auth.saml

Class SamlMetadataResolvers

java.lang.Object
org.apache.juneau.rest.server.auth.saml.SamlMetadataResolvers
public final class SamlMetadataResolvers extends Object
Convenience factories for building MetadataResolver instances backed by an OpenSAML implementation.

Juneau ships convenience factories only — no bundled default MetadataResolver singleton. Applications either:

  • Call file(File) for a local SAML metadata file (typical dev/staging setup).
  • Call url(String) for a remote /metadata endpoint (typical production setup).
  • Build their own MetadataResolver directly using OpenSAML APIs (advanced).

Both factories return resolvers that are already initialized — ready to hand to SamlAssertionValidator.Builder.metadataResolver(MetadataResolver) immediately.

Notes:

The URL factory uses the JDK HttpClient (Java 17) to fetch the metadata blob once at construction time and wraps the parsed DOM in a DOMMetadataResolver. No background refresh is performed; applications that need periodic refresh should construct their own HTTPMetadataResolver (from opensaml-saml-impl) with an Apache HttpClient + refresh policy.

Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static org.opensaml.saml.metadata.resolver.MetadataResolver
    file(File file)
    Creates a MetadataResolver that loads SAML 2.0 metadata from the given file.
    static org.opensaml.saml.metadata.resolver.MetadataResolver
    file(Path path)
    Creates a MetadataResolver that loads SAML 2.0 metadata from the given Path.
    static org.opensaml.saml.metadata.resolver.MetadataResolver
    url(String url)
    Creates a MetadataResolver that fetches SAML 2.0 metadata from the given URL once and serves it from an in-memory DOM.
    static org.opensaml.saml.metadata.resolver.MetadataResolver
    url(String url, X509Certificate metadataSigningCert)
    Creates a MetadataResolver that fetches SAML 2.0 metadata from the given URL and verifies the metadata's XML signature against the supplied pinned certificate before trusting it.
    static org.opensaml.saml.metadata.resolver.MetadataResolver
    url(String url, X509Certificate metadataSigningCert, long maxMetadataBytes)
    Creates a MetadataResolver that fetches SAML 2.0 metadata from the given URL, verifies the metadata's XML signature against the supplied pinned certificate (when provided), and bounds the fetched response body to maxMetadataBytes.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • file

      public static org.opensaml.saml.metadata.resolver.MetadataResolver file(File file) throws IOException
      Creates a MetadataResolver that loads SAML 2.0 metadata from the given file.

      The file is parsed at construction time and re-parsed on disk modification by the underlying FilesystemMetadataResolver.

      Parameters:
      file - The metadata XML file on the local filesystem. Must exist and be readable.
      Returns:
      An initialized MetadataResolver.
      Throws:
      IOException - If the file cannot be parsed or initialized.

    • url

      public static org.opensaml.saml.metadata.resolver.MetadataResolver url(String url) throws IOException
      Creates a MetadataResolver that fetches SAML 2.0 metadata from the given URL once and serves it from an in-memory DOM.

      Fetch happens on the calling thread with a 30-second connect/request timeout. Applications that need periodic refresh should construct an OpenSAML HTTPMetadataResolver directly with an Apache HttpClient.

      Transport:

      The metadata blob supplies the trust-anchor signing certificate, so the transport must not be downgradeable by a network intermediary. The URL must therefore use "https" or target a loopback host ("localhost"/"127.0.0.1"/"::1", for local development); a plaintext "http" URL aimed at any other host is rejected. When the IdP offers signed metadata, prefer url(String, X509Certificate) so the metadata's own XML signature is verified against a pinned certificate independently of the transport.

      Parameters:
      url - The metadata URL. Must use HTTPS or target a loopback host.
      Returns:
      An initialized MetadataResolver.
      Throws:
      IOException - If the URL cannot be fetched or the metadata is malformed.

    • url

      public static org.opensaml.saml.metadata.resolver.MetadataResolver url(String url, X509Certificate metadataSigningCert) throws IOException
      Creates a MetadataResolver that fetches SAML 2.0 metadata from the given URL and verifies the metadata's XML signature against the supplied pinned certificate before trusting it.

      This is the strongest option: the metadata document's own enveloped signature is validated against metadataSigningCert, so a substituted or tampered metadata blob is rejected regardless of the transport used to fetch it. The same transport rule as url(String) still applies.

      The response body is bounded to SamlAuthFilter.DEFAULT_MAX_INFLATED_BYTES (1 MiB); use url(String, X509Certificate, long) to override that cap.

      Parameters:
      url - The metadata URL. Must use HTTPS or target a loopback host.
      metadataSigningCert - The certificate whose public key signed the metadata document. When null, no signature validation is performed (equivalent to url(String)).
      Returns:
      An initialized MetadataResolver.
      Throws:
      IOException - If the URL cannot be fetched, the metadata is malformed, or its signature does not verify against the pinned certificate.

    • url

      public static org.opensaml.saml.metadata.resolver.MetadataResolver url(String url, X509Certificate metadataSigningCert, long maxMetadataBytes) throws IOException
      Creates a MetadataResolver that fetches SAML 2.0 metadata from the given URL, verifies the metadata's XML signature against the supplied pinned certificate (when provided), and bounds the fetched response body to maxMetadataBytes.

      A malicious or compromised metadata endpoint must not be able to exhaust heap by returning an unbounded response. The cap is enforced both against a declared Content-Length header (rejected up front) and against the actual streamed byte count (aborted mid-fetch), so a missing or lying Content-Length cannot bypass it.

      Parameters:
      url - The metadata URL. Must use HTTPS or target a loopback host.
      metadataSigningCert - The certificate whose public key signed the metadata document. When null, no signature validation is performed.
      maxMetadataBytes - The maximum number of response bytes to accept before aborting the fetch.
      Returns:
      An initialized MetadataResolver.
      Throws:
      IOException - If the URL cannot be fetched, the response exceeds maxMetadataBytes, the metadata is malformed, or its signature does not verify against the pinned certificate.

    • file

      public static org.opensaml.saml.metadata.resolver.MetadataResolver file(Path path) throws IOException
      Creates a MetadataResolver that loads SAML 2.0 metadata from the given Path.

      Convenience overload of file(File); useful for callers that have a Path on hand.

      Parameters:
      path - The metadata XML file as a Path.
      Returns:
      An initialized MetadataResolver.
      Throws:
      IOException - If the file cannot be parsed or initialized.