Automatic Metadata Lookup

The Rock Solid Knowledge SAML Service Provider (SP) component supports two methods of setting Identity Provider (IdP) options when configuring a Service Provider.

• Manual entry of required Identity Provider options using IdentityProviderOptions during component configuration
• Automatic lookup of metadata from the IdentityProviderMetadataAddress provided during component configuration

Manual Configuration

To manually configure Identity Provider options, IdentityProviderOptions is set with an IdpOptions object with the required values during component configuration. If this method of configuration is used, any value specified for IdentityProviderMetadataAddress will be ignored, and no attempt will be made to retrieve metadata automatically.

.AddSaml2p("saml2p", options =>
{
    // Other configuration code removed for brevity

    options.IdentityProviderOptions = new IdpOptions
    {
        EntityId = "https://localhost:5000",
        SingleSignOnEndpoint = new SamlEndpoint("https://localhost:5000/saml/sso", SamlBindingTypes.HttpRedirect),
        SingleLogoutEndpoint = new SamlEndpoint("https://localhost:5000/saml/slo", SamlBindingTypes.HttpRedirect),
        SigningCertificates = {new X509Certificate2("signingcertificate.cer")}
    };
});

Automatic Configuration

We support the automatic retrieval of IdP metadata from HTTP/S URLs and local files. The metadata is retrieved on application startup and then periodically retrieved based on the given IdentityProviderMetadataRefreshInterval. By default, the IdentityProviderMetadataRefreshInterval is set to 12 hours.

If the metadata retrieval fails on the first attempt, the application startup will fail with an exception. However, if the metadata retrieval fails later, the previously cached metadata will be used.

Automatic Configuration From a HTTP(s) URL

Identity Providers typically host their metadata document at a well-known endpoint. This allows you to configure your SP to retrieve an up-to-date configuration of the IdP automatically.

To configure automatic retrieval of Identity Provider options, a value must be specified for IdentityProviderMetadataAddress during component configuration. This property should be set to point to the SAML metadata endpoint of the IdP. If this property is set to an HTTP/HTTPS URL and IdentityProviderOptions is left null, then the component will attempt to automatically lookup and retrieve the IdP options from the metadata document at the URL specified.

.AddSaml2p("saml2p", options =>
{
    // Other configuration code removed for brevity

    options.IdentityProviderMetadataAddress = "https://localhost:5000/saml/metadata";

});

By default, the automatic metadata lookup uses HTTPS. To allow the use of HTTP during development, the IdentityProviderMetadataRequireHttps property must be set to false. This is not recommended for production use as HTTP is insecure.

.AddSaml2p("saml2p", options =>
{
    // Other configuration code removed for brevity

    options.IdentityProviderMetadataAddress = "http://localhost:5000/saml/metadata";
    options.IdentityProviderMetadataRequireHttps = false;

});

Automatic Configuration From a File

To configure automatic retrieval of Identity Provider options from a file, a value must be specified for IdentityProviderMetadataAddress during component configuration. If this property is set to a file path and IdentityProviderOptions is left null, then the component will attempt to automatically look up and retrieve the IdP options from the metadata document at the path specified.

The IdentityProviderMetadataAddress must be set to a local file path on disk.

.AddSaml2p("saml2p", options =>
{
    // Other configuration code removed for brevity

    options.IdentityProviderMetadataAddress = "C:\metadata.xml";
    // options.IdentityProviderMetadataAddress = "..\metadata.xml";
});