Apache HTTPD is generally compatible with Moonshot through the use of an Apache GSS-API module.
In the tables below, the following icons have the following meanings:
- - This version of the software has been tested and verified as supporting Moonshot.
- - This version of the software has been tested and verified as not supporting Moonshot.
- - This version of the software has not yet been tested thoroughly and its status is not known. Let us know if you have tried it and whether it worked or not!
2.2. Compatibility List
Note that accessing supported versions of this software requires a Moonshot compatible client - see the next section for details on which clients are supported.
Any versions not listed below have not yet been tested. If you do so, please let us know!
|Apache 2.4||Using both the Moonshot and the RedHat GSSAPI mod_auth_gssapi modules|
|Apache 2.2||Using the Moonshot mod_auth_gssapi module|
3. Installation & Configuration
How you set up a Moonshot-enabled version of the Apache HTTP server will differ depending on your OS. See the relevant pages for your particular distribution:
4. Client Compatibility
The following clients are known to work with this server software using Moonshot authentication (click on the link to see further information about enabling Moonshot in that client):
- Mozilla Firefox and Debian's Iceweasel
- Google Chrome
- Microsoft Internet Explorer
- Microsoft Edge
- This small python script
5. Next Steps
Once you have installed the software, what happens next?
5.1. Accessing Moonshot attributes
Apache HTTPD can use either the Shibboleth attribute resolver library to map RADIUS and SAML attributes to internal Shibboleth attributes, and then to environment variables, or use it the JSON attribute resolver to map either RADIUS attributes or SAML attributes to environment variables. Read more at Configure a Linux Server's Attribute Resolution about how to configure Shibboleth or the internal JSON attribute resolvers.
To access these attributes, use the
GssapiNameAttributes directive (https://github.com/modauthgssapi/mod_auth_gssapi#gssapinameattributes):
Example accessing the User-Name attribute
This example accesses the RADIUS
User-Name attribute and stores it in the
RADIUS_USER_NAME environment variable where a script can read it.
5.2. Testing Moonshot
The simplest way to test the Apache Moonshot integration is to create a simple script, protected by Moonshot. To do this, do the following:
Create a simple script to protect by creating a directory for cgi scripts.
Create a script in that directory called
hello.cgiwith the following content:
Set the permissions appropriately:
Configure Apache to protect this location, by creating a file at
/etc/apache2/conf.d/moonshot.conf(Alpine Linux) with the following content:
6.1. HTTPS Internet Explorer compatibility
For updated best practice with Internet Explorer connections, you should also read Microsoft's HTTPS and Keep-Alive Connections article.
6.2. RP Proxy configuration
6.2.1. Populating REMOTE_USER
Web services often rely on the
REMOTE_USER Apache environment variable for user information, such as a local user account or a pseudonymous identifier.
REMOTE_USER, update the reply from the RP Proxy with the
User-Name RADIUS attribute in the RP Proxy's
6.2.2. Setting the GSS-Acceptor-Host-Name and GSS-Acceptor-Service-Name attributes (CentOS 6 only)
You may find during testing that you get failures when attempting to authenticate. Run the RP Proxy in debug mode and check the incoming access requests from your webserver. When an access request looks similar to the below, you will notice that the
GSS-Acceptor-Service-Name attributes are not set correctly, or are missing altogether, and you must set them manually.
To set these two vital attributes, you must do the following in your RP Proxy configuration:
- Open the
sites-available/abfab-tlsfile in the FreeRADIUS configuration directory (on RHEL platforms, it's
/etc/raddb, on Debian platforms it's
- Locate the line '
Duplicate the '
client default' block below it and modify the duplicate to suit the requirements as below, then save the file:
You can name the
clientin the block above anything from just a simple entry to its full hostname. To make things easier, you may use the
shortnameconfiguration option in the list of options to set a short name that you can use elsewhere in your FreeRADIUS configuration.
ipaddrconfiguration option also accepts CIDR-formatted IP address blocks if you have multiple servers you want to connect as the same host.
- Open the
sites-available/abfab-tr-idpfile in the FreeRADIUS configuration directory (on RHEL platforms, it's
/etc/raddb, on Debian platforms it's
Locate the line '
psk_authorize'. Insert the following block before that line, then save the file:
This issue should be rectified and no longer necessary from FreeRADIUS 3.0.13 onwards.
Restart your RP Proxy, and re-test. Your entry should now look something more like this:
6.3. Incompatibility with other Apache modules
Currently there is a limited problem with incompatibility between the Moonshot mechanism and other Apache modules, such as
mod_php. The reason seems to be that Apache modules are dynamically loaded using the
RTLD_GLOBAL flag. This then causes duplicated symbol names to be overwritten in memory, resulting in calls to the wrong symbol and thus segmentation faults.
One of the symptoms of this incompatibility is text similar to the below in the Apache error log (
Apache developers acknowledge this bug in the documentation of
We aught to provide an alternative to RTLD_GLOBAL, which is the only supported method of loading DSOs today. (sic)
An alternative (and preferred) way of work-around this issues is to manually patch
libapr to force the usage of the RTDL_DEEPBIND flag (as suggested by the developers in https://bz.apache.org/bugzilla/show_bug.cgi?id=62083#c1). In this case, you need to ensure that the locally installed library is chosen before the system's one. The APR library can be downloaded from https://apr.apache.org/download.cgi.
6.3.1. mod_shib Shibboleth module
Classic Moonshot support (that uses Shibboleth) in either implementation of the
mod_auth_gssapi module is not compatible with the Shibboleth2 service provider Apache module
mod_shib. The primary reason is a fundamental difference in the Shibboleth libraries used by
mod_shib (which makes use of
libshibsp-lite.so) and the Moonshot mechanism (which uses
libshibsp.so). As both libraries provide symbols with the same name but different implementations, Apache fails in either Shibboleth or in Moonshot, depending on the configuration in
To allow the use of both Moonshot and Shibboleth authentication on a web service, use the non-Shibboleth version of the Moonshot GSS-EAP mechanism (packaged as
moonshot-gss-eap-noshib) and configure it using internal JSON attribute resolution.
Additionally, ensure that the following configuration value in the
mod_shib module is configured:
Alternatively, consider the mod_auth_mellon SAML2 module. It has been tested with Moonshot and been found to be compatible. More documentation on how to configure mod_auth_mellon can be found here: https://jdennis.fedorapeople.org/doc/mellon-install/mellon-install-guide.html.
6.3.2. mod_php5 JSON submodule
This module is not compatible with the PHP5 JSON submodule. The reason is that the module is built with
libjson-c.so whereas Moonshot is built with
libjansson.so. Both libraries share symbol names that fail when Apache dynamically loads them.
To resolve this error, disable the PHP5 JSON submodule. In Debian, just delete the
/etc/php5/apache2/conf.d/20-json.ini file. Note that no JSON support will then be available from PHP.
Consider upgrading your PHP installation to at least version 7.1, where this incompatibility does not exist. On Debian and Ubuntu, the standard repositories will contain PHP 7.2. On RedHat, CentOS or Scientific Linux, follow the instructions for the REMI PHP 7.2 repositories.
6.4. AppArmor and SELinux
Ubuntu's AppArmor and the RedHat SELinux systems are also known to interfere with Apache's loading of the Moonshot module. Follow the appropriate operating system's instructions on how to allow Apache to access files outside its assigned directories.