Shibboleth at NC State » Technical Documentation » Advanced SP Configuration » Bypass Endpoint Checks in Metadata

Bypass Endpoint Checks in Metadata

The Problem

The Shibboleth Identity Provider receives a login request from a Service Provider. That request is a SAML message that contains the SP's entity ID, and a handler URL where it wants the authentication SAML message to be delivered. The IdP is programmed to check the metadata from for the SP to make sure the handler URL is among the list of allowed URLs. If the handler URL doesn't exactly match the list, the login request will be refused.

The problem arises when SPs are used to protect sites with multiple virtual hosts. Each vhost must use its own domain name in its handler URLs. In order for those URLs to match the metadata, each domain must be enumerated in the metadata when it is registered. This leads to multiple metadata updates each time a new vhost is added, and to longer and longer metadata files.

Now consider the case of a wildcard hosting system, like WordPress Multisite. The domain *.domain.ncsu.edu is registered to the server IP. Subdomain hosts can be added to the system at will. But they will not work with Shibboleth, because there is no way to put *.domain.ncsu.edu into the endpoint URLs. They will not be exact matches, and the IdP will refuse all requests. We are left with devising some system to dynamically add endpoints to the registered metadata every time a new site is started. There has to be a better way.

It turns out, there is one.

The Solution

In IdP v2.4.0, they added an IdP Profile configuration option called skipEndpointValidationWhenSigned. When this is set true by the IdP, the handler URL check is changed:

If the login request SAML message was signed by the SP key, then the IdP will accept the handler URL as passed, without checking it against the metadata endpoint list.

If the login request SAML message was not signed, the handler URL must match an existing endpoint in the metadata. Just like normal.

Under the original system, the IdP trusts the metadata, and only accepts endpoints found in the metadata. Under this option, the IdP checks the SP signature using the certificate found in the metadata, and then accepts the passed endpoint as valid.

Implementation

Identity Provider (SPs can skip this part)

The IdP must be running v3.0.0 or higher, and must be configured to set the skipEndpointValidationWhenSigned option as "true". We have already done this on our IdP servers for all SP entities found in our NCSU Federation.

If someone from another IdP wants to refer to the configuration, here is an excerpt from our v3.4.1 relying-party.xml file:

<!-- this is the for the default relying party -->
<bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
    <property name="profileConfigurations">
        <list>
            <!-- other beans here don't change -->
            <bean parent="SAML2.SSO" 
                  p:skipEndpointValidationWhenSigned="true"
                  p:postAuthenticationFlows="attribute-release" />
            <!-- other beans here don't change -->
        </list>
    </property>
</bean>

Service Providers

The key configuration item on the SP side is to be certain the Service Provider is configured to sign requests using your SP key. This entry is located in your shibboleth2.xml file, as follows:

<ApplicationDefaults 
        entityID="https://your.entity.ncsu.edu/sp/shibboleth"
        signing="true" 
        encryption="false"
        REMOTE_USER="SHIB_EPPN eppn persistent-id targeted-id">

The piece you need is signing="true". If you used our Sample 2.5.x shibboleth2.xml file when setting up your SP, this option should already be in place. If not, the file provided by the shibboleth package does not have this option, and you will need to include it.

On a single server with mutliple vhosts, it should be sufficient to check these settings in the one shibboleth2.xml file. If you are sharing your SP entity on multiple servers, make sure this setting is made correctly in each instance of your shibboleth2.xml file.

Testing

When you stand up a host using a shared Service Provider entity, go ahead and follow the instructions to Test the Service Provider without adding the new host to the metadata. If your SP if configured correctly, it should just work.

If it doesn't work, and you get the "No peer endpoint available to which to send SAML response" error message, then your SP probably didn't send a signed request. Contact us with the URL for your test site on the new host. We can help trace the SAML messages and see what caused the error.