Virtual hosting issues with Shibboleth

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://spaces.internet2.edu/display/SHIB2/NativeSPConfiguration

and in particular

 https://spaces.internet2.edu/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.

For virtual hosts that are to be registered in the UK federation you won't be able to use self signed certificates and the coresponding keys (as generated at installation or by the keygen script). Instead you'll have to generate keys and obtain appropriate certificates from CAs approved by the federation.

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 require that http://vhost2.example.cam.ac.uk/secure required authentication.

5.4) Immediatly 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="http://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.