SPWontProtect

The most common early problem with the SP most people have is getting it to "run". 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 errors.

Otherwise, move on by platform...

IIS

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 also, 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, I can't tell you what to try. 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.

One other thing you can do that helps sanity check things is access the special extension URL that the code responds to via the Script Mapping. Try accessing /Shibboleth.sso/Foo on your web site. That should spit back a Shibboleth error page. If not, or you get a "Filter not initialized" error or something ugly, then that's a sign the filter isn't running safely yet.

Once you get that nicer error page or the green arrow, the rest is pretty much going to be Shibboleth configuration work.

Site and Request Mapping

The first thing to check is for the proper <Site> elements defined in ShibbolethXml in the <ISAPI> 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 RequestMap. If you did all the above, but it's still not triggering for you, you've got something wrong in the RequestMap. Make sure you have the requireSession="true" attribute placed into the right <Host> or <Path> element for your choice of hostname and directory names.

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 etc\shibboleth\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 might get some hints on what to change.

Apache

Apache is much simpler when it comes to getting at least initial redirection 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
require valid-user

If you're relying on the RequestMap, then you'll run into issues based on server name configuration details. The Apache ServerName command has to be set to match what you put in the RequestMap 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, perhaps 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 ShibbolethXml file.