Shibboleth Plugin Installation

This document is old and may be out of date. We recommend that you use one of the NCSU Plugins for campus logins instead.

Download the plugin files

We will be installing a copy of the standard WordPress Shibboleth plugin. The copy we developed contains a few small changes to ensure the code will run in all of our PHP hosting environments. You are welcome to use the official version over our copy, but be warned that it may break with some planned PHP upgrades that we will be making in OIT.

Get the modified copy

Click this link to download the modified shibboleth.1.6.ncsu.zip.
Unzip the file to create a directory named "shibboleth" containing all of the plugin files.
Move or upload the shibboleth directory to your wp-content/plugins directory.

This copy can also be viewed directly on github. See the github cjbnc/shibboleth repo. There you can easily review the modifications to the official source.

If you prefer the standard copy

Go to the Shibboleth plugin page at WordPress.
Find the button on the right side labeled "Download version 1.6". Click that to download shibboleth.1.6.zip.
Unzip the file to create a directory named "shibboleth" containing all of the plugin files.
Move or upload the shibboleth directory to your wp-content/plugins directory.
Double check your User Profile Data settings below if you are running on a redirected version of PHP.

Activate the plugin

Login to your site and an administrator and go to your Dashboard.
Click the menu to open the Plugins page.
You should see an entry for the Shibboleth plugin. Click on the Activate link to turn it on.

Now, the documentation for the plugin will tell you that Shibboleth needs to be configured to use lazy sessions. It will also try to configure lazy sessions in your .htaccess file. It will add these lines:

# BEGIN Shibboleth
AuthType shibboleth
Require shibboleth
# END Shibboleth

That should work correctly. If it failed to add those lines because of permissions, go ahead and put them into the .htaccess file manually.

Configure the plugin

While still on the Dashboard site, open the menu option Settings. There should be a new entry for Shibboleth, open that page. Now you should see the Shibboleth Options page, which contains three sections. This guide will cover the suggested settings for each section.

Shibboleth options

Session Initiator URL - The plugin will try to fill this in for you automatically, but it will make mistakes if your site is not using SSL or if your site is installed in a subdirectory of your main site. The correct url for your site should look like this:
- https://your.site.ncsu.edu/Shibboleth.sso/Login
- Make sure you have an "https" URL.
- Make sure the Shibboleth.sso path is not in a subdirectory.
Logout URL - The plugin may make the same mistakes here. The correct URL should look like this:
- https://your.site.ncsu.edu/Shibboleth.sso/Logout
Password Change URL - This is optional. If you want to set it, use:
- https://www.ncsu.edu/password
Password Reset URL - This is optional. If you want to set it, we suggest this documentation page:
- https://oit.ncsu.edu/unityid/
Shibboleth is default login - Your choice.
- If checked, the local login dialog for WordPress will not be used. All users must login via Shibboleth.
- If not checked, the local login dialog will still be used. A link will be added to allow users to login via Shibboleth.
Shibboleth automatic login - Your choice.
- If checked, the lazy sessions setup will automatically check for an existing Shibboleth session, and will log that user into WordPress if one is found.
- If not checked, the user must click a login link even if they have an an existing Shibboleth session.
- If your WordPress site is the only thing found on this domain, odds are the user will not have a Shibboleth session until they've logged in to this WordPress. This setting will have noticable effect.

User Profile Data

These are the settings that you need to map our Shibboleth suggested [attribute mappings] to the entries used by the plugin.

Username = SHIB_EPPN
First name = SHIB_GIVENNAME
Last name = SHIB_SN
Nickname = SHIB_EPPN *We don't pass a nickname on our IdP. The default setting suggests using EPPN here.
Display name = SHIB_DISPLAYNAME
Email address = SHIB_MAIL *We pass the user's preferred email address. You may prefer to use SHIB_EPPN which will always return unityid@ncsu.edu.

If you check the "Managed" box next to each field, that field will always be copied from the Shibboleth login. The user will not be allowed to change that value on the WordPress account.

User Profile Data settings for redirected PHP

If you are running the standard plugin, and your PHP service is not using mod_php, you may have problems with these settings as written. The webserver may be changing your attribute mappings by adding 'REDIRECT_' to the front of the variables when they are passed. If this is the case on your server, use these variable names instead:

Username = REDIRECT_SHIB_EPPN
First name = REDIRECT_SHIB_GIVENNAME
Last name = REDIRECT_SHIB_SN
Nickname = REDIRECT_SHIB_EPPN
Display name = REDIRECT_SHIB_DISPLAYNAME
Email address = REDIRECT_SHIB_MAIL

User Role Mappings

Our IdP doesn't pass entitlements that can be used for these settings. We do pass affiliations, but they are very broad categories that should probably not be used for most sites.

Role Mappings - You should probably clear all of these to start.
Default Role - Use "Subscriber" unless you want to give higher access to everyone that can login via Shibboleth.
Update User Roles - This won't do anything if you've cleared all the mappings as suggested.
- If checked, and if you have any mappings setup, then the user will automatically update their roles each time they login to Shibboleth.

Once you've made all of your updates on this page, be sure to click the "Save Changes" button on the bottom of the page.

Testing the site

Start with a fresh browser, or use a new Incognito window to get a window with no cookies or logins saved.
Visit your WordPress URL.
Find the META Log In link in your sidebar and click it.
- This should take you to our Shibboleth login page directly, or
- It might take you to the local login form with a link to login with Shibboleth. If so, click that link.
Login to Shibboleth.
You should be returned to your WordPress site.
- If you have not registered your Shibboleth account in your WordPress before, you will probably land on the page to fill in your account information.
- If your Shibboleth account was already created, you should return to the homepage or dashboard for your site.

Common problems

Page not found for Shibboleth.sso handler

Check the URL on your browser.
- https://your.site.ncsu.edu/some/subdir/Shibboleth.sso - This means you have the wrong setting for the "Session Initiator URL" in your plugin options. The handler must be the first entry in the path after the hostname.
- https://your.site.ncsu.edu/Shibboleth.sso - This means you have a problem with the SP setup on your server. Either the handler has not been instaled correctly, or there may be a top-level mod_rewrite rule that is trying to map the handler URL to a WordPress page.
If your WordPress is installed at the top level directory for your domain, you may need to add a rewrite exception to your top-level .htaccess file. Something like this:
```
RewriteEngine On
RewriteBase /
RewriteRule Shibboleth.sso - [L]
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
```
In this example, the "Shibboleth.sso" rule was added inside the standard WordPress rewrites. The rule says if the URL asks for Shibboleth.sso, then don't rewrite it. Just let it pass through to the handler like it is supposed to.