Virtual hosting issues with Shibboleth

We're working on improving Raven resources for developers and site operators.

Try out the new Raven documentation for size.

Simple web servers just implement a single web site that is addressed by a single host name (often that assigned to the computer on which the site's web server runs). The example Shibboleth configurations provided are largely targeted at servers like this.

However more complicated web servers will serve multiple web sites from a single machine, with sites being selected either by name or based on the IP address and/or port used to connect to them. Some web servers may operate in 'clusters' for greater throughput and some will operate behind front-end systems which might also take responsibility for terminating SSL network connections.

The Internet2 Shibboleth software is very configurable and it should be possible to get it to work in most situations. However configuration work will be required (mainly in the shibboleth2.xml file) and, given the range of possible requirements, it's difficult to give cookbook examples of what to do. A careful reading of the Internet2 documenation starting at

 https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration

and in particular

 https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApplication

is likely to be required; past traffic on the SHIBBOLETH-USERS mailing list can also be a useful resource, as can the list itself if all else fails (though do check its archives before jumping in).

For a fairly straightforward machine implementing multiple virtual hosts that all require similar authentication and authorisation services, areas of shibboleth2.xml that may need attention include:

• (For IIS only) The <ISAPI> element of the <InProcess> element which will need additional mappings of IIS's internal ids to the host names, schemes, and ports used by the various virtual hosts.
• The RequestMapper will need appropriate <ReqestMap>s to map incoming requests onto appropriate 'Application IDs'
• 'Application ID's then need to be mapped into apropriate configurations using the <ApplicationDefaults> element and perhaps one or more <ApplicationOverride> elements.

Note that it's common for Shib-protected web sites to use https (and this is required for sites that will be registered in the UK federation). Remember that name-based virtual hosting isn't possible for https sites so each will require its own IP address.

Simple vhost configuration

The following approach should work for the common case of a single web server running multiple separate virtual hosts. The intention is to configure each virtual host as a seperate Shibboleth entity, each with its own Metadata and keypair. Using a seperate key pair, which seems to be unusual in the Shib community, makes it easier to move the virtual host between web servers without having to also update its Metadata.

1) Choose one of the virtual hosts. It doesn't matter which one, but if any one of them is more important or primary then choose that for convenience. For example we'll call it vhost1.example.cam.ac.uk.

2) Starting from the Shibboleth2.xml - internal use skeleton (or similar), configure the SP as if this virtual host was the one and only host name known to the server. In particular, base the entityID on this host name. Check this works.

3) In the same directory as shibboleth2.xml, find the files called sp-cert.pem and sp-key.pem. Rename them to something based on the host name - perhaps vhost1.example.cam.ac.uk-cert.pem and vhost1.example.cam.ac.uk-key.pem. Edit shibboleth2.xml and make matching changes to the <CredentialResolver> element towards to bottom of the file. Test that things still work.

4) If you plan to register this host then generate metadata for it using the virtual host's host name.

5) Then, for each additional virtual host:

5.1) Change to the same directory as shibboleth2.xml. Run the script keygen.sh (Unix/MacOS) or keygen.bat (Windows) with the -h argument supplying the virtual host's host name. E.g.

 ./keygen.sh -h vhost2.example.cam.ac.uk
 keygen.bat -h vhost2.example.cam.ac.uk

This will create files called sp-cert.pem and sp-key.pem. Rename them to something based on the host name - perhaps vhost2.example.cam.ac.uk-cert.pem and vhost2.example.cam.ac.uk-key.pem.

5.2) (For IIS only) Add an appropriate <Site> element to the <ISAPI> element of the <InProcess> element to map the virtual host's instance id to the host name. For example:

 <Site id="2" name="vhost2.example.cam.ac.uk"/>

5.3) Add a new <Host> element to the <ReqestMap> element within the <RequestMapper> element. This <Host> element should include the virtual host's name as the value of its 'name' attribute and an arbitrary name as the value of its 'applicationId' attribute. It's easier if you base this name on the host's host name. Access control statements can, but need not, appear within this <Host> element.

For example:

 <Host name="vhost2.example.cam.ac.uk" applicationId="vhost2">
     <Path name="secure" authType="shibboleth" requireSession="true"/>
 </Host>

would setup vhost2.example.cam.ac.uk and specify that http://vhost2.example.cam.ac.uk/secure required authentication.

5.4) Immediately before the end of the <ApplicationDefaults> element, add an <ApplicationOverride> element. This should include the name assigned to applicationId above as the value of its 'id' attribute, and the entityID for the new site as the value of its 'entityID' attribute. It should have a single child element - a <CredentialResolver> selecting the key and certificate files created in step 5.1 above. For example:

 <ApplicationOverride id="vhost2" entityID="https://vhost2.example.cam.ac.uk/shibboleth">
   <CredentialResolver type="File" key="vhost2.example.cam.ac.uk-key.pem" certificate="vhost2.example.cam.ac.uk-cert.pem"/>
 </ApplicationOverride>

5.5) If you plan to register this host then generate metadata for it using the virtual host's host name.

5.6) Test that the new virtual host works. Note that a browser message of "Internal Server Error. Please contact the site administrator." together with "could not process error template (session)" logged in .../var/log/httpd/native.log suggests that the SP could not find an <ApplicationDefaults> or <ApplicationOverride> entry that matches the 'applicationId' declared in the <Host> element. Check the spelling of the 'applicationId' and 'id' attribute values.

Even simpler vhost configuration

An even simpler vhost configuration is possible where all hosts share the same key. For this you skip steps 3 and 5.1 above, and for 5.4 the <ApplicationOverride> element need only look like this

<ApplicationOverride id="vhost2" entityID="https://vhost2.example.cam.ac.uk/shibboleth"/>

The downside with this approach is that if you ever want tot move a virtual site to a different host you'll either have to copy the keys (which could become a security issue if a number of hosts, and perhaps administrators, were involved), or you'd need to update the corresponding metadata to include a new key before you moved the site.