SAML Metadata support

[twenzel]

When moving from RSK.Saml to Duende the Metadata feature is missing.
It should be possible to define a metadata url from the SAML IdentityProvider on the SAML ServiceProvider. This metadata url should be used to retrieve the IDP metadata (SSO urls, certificates, etc). This metadata should be refreshed every X days.

[maartenba]

Thanks! This one is being tracked.

[omon77]

Hi @maartenba , was there any movement on this and is there an ETA?

[maartenba]

To answer your question on ETA: metadata support is part of a larger set of SAML improvements we're working on. There's no official release date yet.

If you need it sooner, you will need to do this yourself. IdentityServer resolves service providers through ISamlServiceProviderStore, so you can fetch the SP metadata, map it to a SamlServiceProvider, and serve that from your own store. Below is a simplified sample that could help with metadata parsing, to get you started. Use it with caution (not production-hardened), and keep in mind this snippet is not supported by Duende (it's a temporary workaround).

Parsing SP metadata

The following is (slightly naive) metadata parser:

using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.Xml.Linq;
using Duende.IdentityServer.Models;

public static class SpMetadataParser
{
    private static readonly XNamespace Md = "urn:oasis:names:tc:SAML:2.0:metadata";
    private static readonly XNamespace Ds = "http://www.w3.org/2000/09/xmldsig#";

    private const string HttpPost = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST";
    private const string HttpRedirect = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect";

    private const int MaxDocumentSize = 1_048_576; // 1 MB

    public static SamlServiceProvider Parse(string xml, string? entityId = null)
    {
        // Metadata is untrusted input: no DTDs, no external entities, bounded size.
        var settings = new XmlReaderSettings
        {
            DtdProcessing = DtdProcessing.Prohibit,
            XmlResolver = null,
            MaxCharactersFromEntities = 0,
            MaxCharactersInDocument = MaxDocumentSize,
            IgnoreProcessingInstructions = true
        };

        using var reader = XmlReader.Create(new StringReader(xml), settings);
        var root = XDocument.Load(reader).Root
            ?? throw new InvalidOperationException("Empty metadata document.");

        // Accept either a single EntityDescriptor or an EntitiesDescriptor (aggregate).
        var entity = (root.Name == Md + "EntityDescriptor"
                ? new[] { root }
                : root.Descendants(Md + "EntityDescriptor"))
            .Where(e => e.Element(Md + "SPSSODescriptor") is not null)
            .FirstOrDefault(e => entityId is null || (string?)e.Attribute("entityID") == entityId)
            ?? throw new InvalidOperationException("No matching SPSSODescriptor found.");

        var sp = entity.Element(Md + "SPSSODescriptor")!;

        var acs = sp.Elements(Md + "AssertionConsumerService")
            .Where(e => (string?)e.Attribute("Binding") == HttpPost && IsHttpUrl((string?)e.Attribute("Location")))
            .Select(e => new IndexedEndpoint
            {
                Location = (string)e.Attribute("Location")!,
                Binding = SamlBinding.HttpPost,
                Index = (int?)e.Attribute("index") ?? 0,
                IsDefault = (bool?)e.Attribute("isDefault") ?? false
            })
            .ToList();

        if (acs.Count == 0)
        {
            throw new InvalidOperationException("No HTTP-POST AssertionConsumerService found.");
        }

        var slo = sp.Elements(Md + "SingleLogoutService")
            .Where(e => IsHttpUrl((string?)e.Attribute("Location")))
            .Select(e => (Binding: MapBinding((string?)e.Attribute("Binding")), Location: (string)e.Attribute("Location")!))
            .Where(e => e.Binding is not null)
            .Select(e => new SamlEndpointType { Location = e.Location, Binding = e.Binding!.Value })
            .ToList();

        var certificates = sp.Elements(Md + "KeyDescriptor")
            .SelectMany(kd => kd.Elements(Ds + "KeyInfo").Elements(Ds + "X509Data").Elements(Ds + "X509Certificate")
                .Select(c => new ServiceProviderCertificate
                {
                    Certificate = X509CertificateLoader.LoadCertificate(
                        Convert.FromBase64String(string.Concat(c.Value.Where(ch => !char.IsWhiteSpace(ch))))),
                    Use = (string?)kd.Attribute("use") switch
                    {
                        "signing" => KeyUse.Signing,
                        "encryption" => KeyUse.Encryption,
                        _ => KeyUse.Both
                    }
                }))
            .ToList();

        return new SamlServiceProvider
        {
            EntityId = (string)entity.Attribute("entityID")!,
            AssertionConsumerServiceUrls = acs,
            SingleLogoutServiceUrls = slo,
            Certificates = certificates,
            RequireSignedAuthnRequests = (bool?)sp.Attribute("AuthnRequestsSigned") ?? false
        };
    }

    private static bool IsHttpUrl(string? value) =>
        Uri.TryCreate(value, UriKind.Absolute, out var uri) &&
        (uri.Scheme == Uri.UriSchemeHttps || uri.Scheme == Uri.UriSchemeHttp);

    private static SamlBinding? MapBinding(string? urn) => urn switch
    {
        HttpPost => SamlBinding.HttpPost,
        HttpRedirect => SamlBinding.HttpRedirect,
        _ => null
    };
}

And here's how to use it:

using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.Xml.Linq;
using Duende.IdentityServer.Models;

const string xml = """
.... should contain SPSSODescriptor ....
""";

try
{
    var sp = SpMetadataParser.Parse(xml);
    Console.WriteLine($"EntityId: {sp.EntityId}");
    Console.WriteLine($"RequireSignedAuthnRequests: {sp.RequireSignedAuthnRequests}");
    foreach (var a in sp.AssertionConsumerServiceUrls) Console.WriteLine($"ACS [{a.Index}{(a.IsDefault ? ", default" : "")}] {a.Binding}: {a.Location}");
    foreach (var s in sp.SingleLogoutServiceUrls) Console.WriteLine($"SLO {s.Binding}: {s.Location}");
    foreach (var c in sp.Certificates ?? []) Console.WriteLine($"Cert ({c.Use}): {c.Certificate.Subject} {c.Certificate.Thumbprint} valid until {c.Certificate.NotAfter:u}");
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Could not parse SP metadata: {ex.Message}");
}

Note that metadata only covers endpoints and certificates. Settings such as AllowedScopes, ClaimMappings, SigningBehavior and DisplayName still come from your own configuration, so merge the parsed result into your existing SP definition instead of using it as is.

Refreshing the metadata

A few ways to handle the "refresh every X days" part, and some further thoughts if you want to implement this yourself:

• Background refresh into a cache. Run a BackgroundService (or a scheduled job) that downloads the metadata for each configured SP on an interval, parses it, and stores the result in an in-memory or distributed cache. Your custom ISamlServiceProviderStore reads from that cache and combines it with your local settings. This keeps network calls out of the sign-in path.
• Respect the metadata's own hints. EntityDescriptor can carry validUntil and cacheDuration attributes. Use them to decide when to refresh, and fall back to your own interval when they're missing.
• Keep the last good copy. If a download or parse fails, log it and keep serving the previously cached metadata instead of dropping the SP.
• Only fetch from URLs you configure. Use HTTPS, set a timeout and a response size limit on the HttpClient, and don't let metadata content decide where to fetch from next.
• Verify the metadata signature if the SP signs it. If you fetch over the network, check the XML signature against a certificate you've pinned for that SP (for example with SignedXml). Otherwise anyone who can tamper with the response can swap in their own certificate.
• Watch certificate rollover. SPs often publish the new certificate alongside the old one before switching. Keeping all published certificates handles this without downtime.

[omon77]

@maartenba , thank you so much for the response and the code snippets!