H+H Software GmbH

The HAN knowledge base

The HAN knowledge base helps you with smaller problems.


Integration of Shibboleth in HAN 5

Hints on integration of the Shibboleth SP into HAN
Basics and changes as of version 5.2.2


HAN uses a wildcard SSL certificate to provide HTTPS based websites. As a consequence all websites that are made available via HTTPS require a DNS prefix in the DNS name for the certificate to be valid. For all login pages this prefix is "login". For the integration of Shibboleth, it was therefore determined that the service provider can be reached via the prefix "sp". The SP must accordingly as sp. be registered.
For the HAN demo server with the FQDN demo.hh-han.com this would be sp.demo.hh-han.com.

The configuration files used in HAN require this!

Integration of the SP in HAN

The SP is integrated into HAN as a separate "Named Virtual Host" in the HAN web service (Apache). This is necessary because a separate certificate is required for the SP if the existing wildcard certificate is not accepted by the DFN-AAI, for example.

The default HAN configuration files have been modified for this purpose. This has been necessary as with HAN all login components could only be accessed via SSL. Technically, these configurations are all loaded in the context of the existing "Virtual Host" for SSL.
The modules are loaded from the above configuration. However, since the SP itself has to be configured in a virtual host and nesting of virtual hosts is not permitted, the order for loading the individual configurations had to be adjusted.
In addition, it is necessary to set the "ShibCompatValidUser On" variable when using Shibboleth together with alternative login mechanisms (as of version 2.4 of Apache in the root of the web server).

Aufbau der hanshibbolth.conf

When Shibboleth is used (this is controlled via the USESHIBBOLETH on variable in the variables.conf file), a "Named Virtual Host" is created on the name sp.${SERVERNAME}, where ${SERVERNAME} is the FQDN of the HAN server.
The name is bound to this virtual host via the variable ServerName sp.${SERVERNAME}. This ensures that all requests to sp. are sent to this configuration and not to the default SSL Virtual Host.
The own, different certificate is stored within the virtual host.
Furthermore, the Shibboleth module is loaded within this virtual host and all virtual directories are also defined.

This structure of the configuration ensures that all configuration files can always be loaded and no manual reworking after the update will be necessary in the future.
During the initial installation, only the hanshibbolth.conf file needs to be adjusted. This will not be overwritten by updates.

HAN also supports the integration of an SP that does not comply with the naming convention mentioned above.

In the variables-user.conf file, the directive:
determines if it the above-mentioned naming standards are used. If the SP has a different name, then this directive must be deleted!


If this variable is not set, the default hanshibboleth.conf will not be loaded.

Deviating configurations must then be stored in the user.conf file. This ensures that manual adjustments are not overwritten during updates.

Furthermore, the URL for the redirection to the Shibboleth login must be adapted. The default here is:
define HANLoginURL https://sp.${SERVERNAME}/hanshibboleth/login.html
If different, this directive must also be defined in the variables-user.conf file.

The server name in the above URL must correspond to the server name of the SP, otherwise the shibboleth configuration cannot work.