Testing htaccess on a Hosted Server

OIT provides Shibboleth SP service on our AFS-based and cPanel-based hosting platforms. If your domains is hosted on these platforms, you will not need to setup or install a Shibboleth SP. You may want to setup a test directory to verify that Shibboleth has been installed correctly and works for your domain.

Pre-requisites

Your domain should be hosted on an OIT hosted AFS or cPanel server. We have already installed the Shibboleth SP software on these servers. We have already configured SSL for all of our hosts.

Non-OIT hosting:

Other departments may setup and provide a Shibboleth SP for their servers. If they do, this test should still work for you.
Your domain must have SSL available and properly configured. The Shibboleth handler URL is expected to use https for its transactions. You may still use Shibboleth on non-SSL URLs within your site, but the handler must have https available.

Testing htaccess on a directory

For this test, we will make a directory that will require a Shibboleth login to access it. We will create an .htaccess file with the necessary Shibboleth directives in it. And, we will create an index file to demonstrate that Shibboleth is working when it is viewed.

Zip-file demo

For a quick test, you can simply:

Download this file: shibdemo.zip

Unpack the zip creating a shibdemo directory with two files.

unzip shibdemo.zip
creating: shibdemo/
inflating: shibdemo/index.php      
inflating: shibdemo/.htaccess

Copy the directory and two files up to your webserver.

Creating the files

If you prefer to create the test directory for yourself, follow these steps:

Make a subdirectory on your server, suggested name: shibdemo

Edit a new .htaccess file in your directory, at shibdemo/.htaccess

Cut and paste these lines into that file:

AuthType shibboleth
ShibRequestSetting requireSession true
require shib-session

Edit a new index.php file in your directory, at shibdemo/index.php

Open the example page, then cut and paste those lines into your index.php file

Test the directory

Visit the url for this directory, something like http://yoursite.ncsu.edu/shibdemo/

You should be redirected to the NC State IdP to login. You should see the page https://shib.ncsu.edu/idp/Authn/UserPassword where you are asked to enter your Unity ID and Password.

Assuming you reached the login page, enter your own Unity credentials and submit them. Since this is the first time you've logged in to the new SP, you should be presented with the uApprove page which lists that attributes that will be released to your site. Click "Confirm" on that page to proceed.

If all goes well, your browser will be redirected back to your site's test url. You should now be logged in, and you should see the output of the the index page that you installed earlier.

The example page shows something like this:

Login Success!

Welcome! Your EPPN is unityid@ncsu.edu,
and your affiliation is staff@ncsu.edu;member@ncsu.edu.

Environment Dump
Array
(
[SHIB_AFFILIATION] => staff@ncsu.edu;member@ncsu.edu
[SHIB_EPPN] => unityid@ncsu.edu
[SHIB_UID] => unityid
[REMOTE_USER] => unityid@ncsu.edu
[AUTH_TYPE] => shibboleth
... additional output omitted ...
)

Errors in testing

If you see any of these errors on an OIT AFS or cPanel server, please contact us to fix the problem.

Internal Server Error

When you first visit your test url, you may get this error. If you do, it probably means there is a problem with the .htaccess file. Common problems are:

AuthType shibboleth - is not recognized, which mean the server does not have the Shibboleth SP properly installed. If you can, check for an explanation in your error_log.
ShibCompatWith24 On - If your provider is already running Apache 2.4.x or higher, this directive is not necessary. Remove it from the .htaccess file and retry the URL. OIT servers are still running Apache 2.2.x.

https://yoursite.ncsu.edu/Shibboleth.sso webpage is not available

Your site tried to use this SSL URL to your site's Shibboleth handler, and it could not find the page. You probably do not have SSL configured on your site.

Untrusted certificate

If your site has a self-signed SSL certificate installed, your browser may try to stop you from using the handler URL during the shibboleth login. You may ignore the warning while testing, but we recommend that you get properly signed certificates as soon as possible.

Mismatched certificate

This error is common on cPanel sites where the wrong server name may appear in the site certificate when the handler is accessed. This means your sites certificate has not been configured correctly so the cPanel server is defaulting to use the certificate from another domain.

https://yoursite.ncsu.edu/Shibboleth.sso/... returns 404 error

This is most often found when the root level of your website is using a CMS like Wordpress or Drupal that has a set of rewrite rules to map URLs to pages inside the CMS. In that case, the Shibboleth handler URL located at /Shibboleth.sso is being grabbed by the rewrite rule instead of being handled by the Shibboleth module.

To fix this for your own site, you will need to add an exclusion rule to the rewrites provided by your CMS. For example, the top-level .htaccess file on a Wordpress site should contain a block like the one below. You will need to add the entry for Shibboleth.sso as seen in this example. It should appear as the first rule after the RewriteBase.

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^Shibboleth\.sso.* - [L]
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

This directive says, "for any URL that comes in for /Shibboleth.sso, leave the URL unchanged, and do not process any rules later in this list." That will effectively leave the request intact so the Shibboleth hander can grab it.

We already have a similar exclusion applied globally to the OIT cPanel servers. You should not run into this problem on those sites. However, if your .htaccess file uses the rule "RewriteOptions inherit", we have observed that this can cause our global rule to be ignored. Considered removing RewriteOptions inherit if you do not actually to use it.

For anyone trying to provide cPanel hosting with Shibboleth, we've implemented this code in our pre-virtualhost-include block on our servers:

<Location /Shibboleth.sso>
  Satisfy Any
  Allow from all
  RewriteEngine On
  RewriteRule ^/Shibboleth.sso.* - [L]
</Location>

Other errors

See the documentation that describes how to Test the SP installation, and on Using .htaccess files.