The Shibboleth V2 IdP and SP software have reached End of Life and are no longer supported. This documentation is available for historical purposes only. See the IDP v4 and SP v3 wiki spaces for current documentation on the supported versions.

NativeSPWontProtect

A common early problem with SP configuration is getting it to "run" and actively protect content. There are a lot of different reasons the filter/module might not appear to be doing anything, depending on the platform.

Usually, you can isolate this up front based on whether shibd is runnable or not. This can be done from the command line by running the shibd command (it's in sbin) using the -check (Windows) or -t (Unix) option. If you get reasonable output, then there's a pretty good chance the filter/module is "working", it's just not configured to do what you want yet. If not, then you need to fix the shibd problem first, usually by correcting configuration file syntax.

Otherwise, move on by platform...

IIS

Before getting too far into debugging, please make sure to read the NativeSPIISConfig topic thoroughly and make sure you understand it and that you've done the necessary setup work.

Check Permissions

With IIS, the first thing to do is to check the Windows Event Log. If you access a site with the filter installed, you should get event log messages saying that the filter initialized. If so, the filter is running, and there's a decent chance permissions are ok. If not, I'd start by making sure that the anonymous IIS user (IUSR_<machine>) has read access the \opt\shibboleth-sp tree. There may be other accounts that need access if you have ASP.NET AppPool identities configured.

You should also make sure those accounts can write to the \opt\shibboleth-sp\var\log\shibboleth folder. Otherwise you won't get a native.log file created. If that file's there, you should see additional information about the health of the filter.

Green Arrow

All those steps should lead to the wondrous "green arrow". Once you access a web page on a site with the filter installed, you should get the arrow in the IIS GUI on the Filters tab. If there's no arrow, or it's red, or Unknown status, something's not right. But that only matters if you've accessed the site. Until you do, restarting will leave the filter in an Unknown state on IIS 6+.

Unfortunately, if the problem isn't permissions, and shibd is running as a service, things get messy. You could try restarting the machine or IIS, but ultimately, you'll have to play with it and hope. One thing I find is that you often need to install the filter directly on the web site. Sometimes installing it up above doesn't work well.

Once you get that green arrow, the rest is going to be SP configuration work.

Check Application Pool 32-bit Application Support

If you are using the 32-bit library on 64-bit Windows, you'll need to activate support for 32-bit applications. In the Application Pools list, select the application pool for your site(s), and view Advanced Settings. In the (General) group, set "Enable 32-Bit Applications" to True.

Site and Request Mapping

The first thing to check is for the proper <Site> elements defined in the <ISAPI> configuration element. You MUST create them for each web site you're using the filter with by mapping from the IIS Site Instance ID to the right hostname(s). You can find the ID on the GUI in the list of Web Sites. It's often a large number on IIS 6.

The rest of the protection trickery is in the <RequestMapper>. If you did all the above, but it's still not triggering for you, you've got something wrong in the map. Make sure you have the requireSession="true" attribute placed into the right <Host> or <Path> element for your choice of host or directory names.

Logging

If you still have no joy, the next step is to try collecting some logging detail. You need to raise the native logging level to DEBUG by editing native.logger and changing the default INFO level to DEBUG. Then you'll want to restart IIS. You should get more verbose information in the native.log file

It will include a line each time you access the site that tells you what URL has been "mapped" by the filter. If it doesn't look right, you should get a hint on what to fix. If you get nothing, despite raising the level to DEBUG, then the filter isn't running, or isn't configured to process requests for the affected site.

Apache

Before getting into debugging, please make sure to read the NativeSPApacheConfig topic thoroughly and make sure you understand it and that you've done the necessary setup work.

Apache is much simpler when it comes to getting at least initial interception to function, but it depends on how you choose to configure it. If you use .htaccess files, things are pretty automatic, you just have to do:

AuthType shibboleth
ShibRequestSetting requireSession 1
require valid-user

If you're relying on the <RequestMapper> instead, then you'll run into issues based on server name configuration details. The Apache ServerName command MUST be set to match what you put in the map's <Host> element and you'll need to make sure UseCanonicalName On is set. But additionally you'll need to get the module running for those requests by globally activating the module for those resources, using this kind of approach:

<Location />
AuthType shibboleth
require shibboleth
</Location>

This activates the module in a passive mode for all requests, while allowing specific content to force a session using the <RequestMapper> or an Apache command someplace else.