Page Comparison

...

...

...

...

...

...

...

...

...

...

...

...

...

Apache 2.4 Support

Half of Shibboleth runs within the web server. For Apache, this half is implemented in a module called mod_shib_13.so, mod_shib_20.so, mod_shib_22.so, or mod_shib_24.so depending on the Apache version. Like all Apache modules, the initial configuration is controlled with Apache's configuration file(s), but one of the primary options there (normally implicit/defaulted) is to point the module at the overall SP configuration file (shibboleth2.xml) where a lot of the options not specific to Apache are controlled.

At runtime, the module has the ability to process both a variety of Apache commands and rules specified in the SP configuration and make sense of both. This allows for a choice of approaches based on the need for native integration with Apache or for portability between web servers. Native integration using Apache commands is the better choice and is more secure.

Prepping Apache

It's critical that you correctly configure the virtual hosts you will be using with the SP module by setting the ServerName command to the appropriate value. With Apache 2.x, you use this command to establish the proper hostname as well as the logical scheme and port the virtual host appears to run on from the client's point of view. If you fail to perform this step, the redirects generated by the module will be incorrect and various problems will ensue. Other related commands (varying by version) include UseCanonicalName and UseCanonicalPhysicalPort. Before you do anything with the SP, do the work to get these commands working for you to enable proper generation of redirects.

...

Most of the primary options needed to make the module usable are compiled into the code when you build it. This allows the module to run silently in most cases simply by loading it (the exact path will vary):

Apache 2.2 Example

LoadModule mod_shib /opt/shibboleth-sp/lib/shibboleth/mod_shib_22.so

You're free to load the module anywhere in your Apache configuration layout that you prefer. The software includes a number of template files, one for each Apache version, that include the command above, a useful Alias setup that allows the default error templates to access an example style sheet, and a simple <Location> example that protects a single directory.

Properly Routing Handler URLs

For certain Apache configurations, such as using the wsgi_module to run Python applications (like django), the URL paths that Shibboleth handlers rely on (e.g. /Shibboleth.sso, see here) may not get properly routed to mod_shib by Apache, because another module has already claimed that namespace. To ensure this routing, you will need to set a Location directive within Apache's configuration file specifying routing to mod_shib. For the default path used by the handler (/Shibboleth.sso), this directive is:

Apache SetHandler

<Location /Shibboleth.sso>
  SetHandler shib
</Location>

You would have to vary the location in this directive if you change the handlerURL attribute of the <Sessions> setting in shibboleth2.xml, but this isn't common.

...

There are a handful of global options that apply to the module's overall configuration and are usually left out in favor of the values generated at compile time. They also correspond to a number of environment variables that can be used in place of commands. They are generally needed only when the software is run out of a different directory from the build path.

There's an additional Apache 2.x-only environment variable called SHIBSP_APACHE_PREREQ, which can be set to the name of a module that needs to run before the authentication hook runs. This is an experimental setting that was created as a possible fix for issues with module order, in particular the setting of additional response headers for, e.g., cross-origin use cases. There has been little reproduction of these problems or any clear sign of what the solution is, and this option hasn't really gotten much testing.

Server / VirtualHost Options

AuthConfig Options

The rest of the options supported by the module are what Apache calls "AuthConfig" options. This means they are meant to appear inside Apache content-control sections like <Directory>, <File>, or <Location>, or in .htaccess files (if the "AuthConfig" override is enabled).

A summary of the various commands follows:

Enabling the Module for Authentication

One of the "quirks" (I would say "bugs") in Apache is that it requires a complicated set of inter-related general commands to be in place in order for an "auth" module to actually "see" a request. Just because you load the module doesn't mean Apache will ever call on it to do any work. This can make things confusing; if you see Apache just serving up content and the SP seems to be ignoring the requests, the lack of these commands in place is is usually the problem.

...

If you're using the module to protect specific content on the server, and you expect the module to step in and force the user to login automatically, you can place the following commands inside any appropriate content block or .htaccess file:

...

Enabling the Module for Specific Content

AuthType shibboleth
ShibRequestSetting requireSession 1
Require valid-user

...

To exclude a specific path from the directory above add a Location override like this:

Exclude a directory from authentication

<Location /public>
 AuthType Shibboleth
 ShibRequestSetting requireSession false
 Require shibboleth
 </Location>

Another common trick is to enable the module across an entire server or at least virtual host, but leave specific rules for authentication and access to commands in other places. This introduces a bit of inefficiency, but does simplify the rest of your configuration:

...

...

Enabling the Module Globally (Overrides other Authentication Rules)

<Location />
AuthType shibboleth
Require shibboleth
</Location>

The difference here is that unless some other option is introduced, the module won't actually do anything, but it's always going to be minimally active. The special keyword "shibboleth" on the Require command is a way of telling the module that it should be active, but not actually block any access by default.

Authorization

The SP contains a plugin interface for Access Control and includes a pair of implementations, one that's portable and one that enables "familiar" use of the Apache Require command in the usual places, including .htaccess files.

...

ShibRequestSetting applicationId foo

The general use of Apache commands should be self-explanatory (or at least should be explained by reading/learning about Apache configuration). For more information about using the <RequestMapper> feature, refer to the How to do Request Mapping in the SP topic.