Using .htaccess files
The official Shibboleth wiki provides these documents:
- SP3 Apache Config - a guide to configuring Apache to use the SP.
- SP3 htaccess - a guide to htaccess syntax.
- SP3 Application Integration - a guide to integrate the Shibboleth SP with an application.
Shibboleth SP 2.5.0 or higher
Apache httpd 2.4 requires a new set of htaccess commands that are slightly different from those used in previous versions. Shibboleth SP 2.5.0 and above support both older and newer formats. They also provide an option to use 2.4 configs with 2.2 or lower servers. We recommend that you use this for forward compatibility in the future.
At a minimum, your htaccess entry should start with these two lines:
AuthType shibboleth ShibRequestSetting requireSession true
For those still running Apache httpd 2.2, you should add a compatibility
IfVersion tags use mod_version to determine if this is an
old version of Apache that needs this tag. This code should be safe to
use on 2.4 servers, where it will be ignored.
<IfVersion < 2.3> ShibCompatWith24 on </IfVersion>
After that, you can add require rules to limit which users are allowed
to use your site. These rules are handled such that any match will allow
the user through. In order to deny a user, they must not match any of
the rules. Note: you must have at least one
require entry on Apache 2.4
servers or the server will return an error.
Rule to allow any user who can login:
Rules to allow any user with a current NC State Unity account:
require shib-attr SHIB_AFFILIATION email@example.com require shib-attr SHIB_AFFILIATION firstname.lastname@example.org
To allow active faculty OR staff at NC State, use:
require shib-attr SHIB_AFFILIATION email@example.com require shib-attr SHIB_AFFILIATION firstname.lastname@example.org
To require multiple rules all be matched, you must combine the rules in a RequireAll block. This feature is not available in httpd 2.2. In this example, the user must be both student and staff:
<RequireAll> require shib-attr SHIB_AFFILIATION email@example.com require shib-attr SHIB_AFFILIATION firstname.lastname@example.org </RequireAll>
To allow specific users, use the eduPersonPrincipalName:
# all five of these users would be permitted # you can do one EPPN per line, or multiple, or mixed require shib-user email@example.com require shib-user firstname.lastname@example.org require shib-user email@example.com firstname.lastname@example.org email@example.com
To allow users from NC State just by UnityID:
require shib-attr SHIB_UID auser1 buser2 cuser3 require shib-attr SHIB_UID mjuser2 jquser3
Note: The examples above assume that you have mapped the SAML attributes to the environment variables following our suggested environment variable names for attributes.
Allow any user who could login
AuthType shibboleth ShibRequestSetting requireSession true require shib-session
Allow any NC State users
AuthType shibboleth ShibRequestSetting requireSession true require shib-attr SHIB_AFFILIATION firstname.lastname@example.org require shib-attr SHIB_AFFILIATION email@example.com
Allow access to specific users
Shibboleth prefers to configure the REMOTE_USER variable to use the eduPersonPrincipalName, or EPPN, which is "UnityID@ncsu.edu".
AuthType shibboleth ShibRequestSetting requireSession true require shib-user firstname.lastname@example.org require shib-user email@example.com firstname.lastname@example.org email@example.com
Lazy sessions - login not required
It is possible to configure Shibboleth to be enabled in a directory while not requiring it to force a login to establish a session.
AuthType shibboleth ShibRequestSetting requireSession false require shibboleth
The "requireSession false" directive tells the SP not to send the user off to login if they do not already have a session. The "require shibboleth" directive is basically a placeholder, it doesn't require anything from the user.
In order to use this effectively, the application will need to link to a Login URL for the user to start their own session manually. For example:
- Login URL using the default IdP: /Shibboleth.sso/Login?target=https://yoursite.ncsu.edu/your/path/
- Login URL using Discovery Service: /Shibboleth.sso/DS?target=https://yoursite.ncsu.edu/your/path/
Apache ignoring htaccess files
This problem came up when debugging a new installation on a Windows-based Apache server, but it can apply to any platform. Our users reported that they had valid .htaccess files in place in the URL directory, but the webserver was still allowing anyone to have access to the files.
The solution was they did not have Apache configured to allow AuthConfig overrides in htaccess files. Where they had something like this in their httpd.conf:
<Directory /web/docs> AllowOverride None </Directory>
They needed to change the None to allow AuthConfig, like this:
<Directory /web/docs> AllowOverride AuthConfig </Directory>
After restarting the Apache httpd service, the configuration found in their .htaccess files was obeyed properly.
Shibboleth using lazy sessions, gets stuck in a login loop
This problem usually occurs on a WordPress site using the NCSU Mars plugin for authentication. The issue is usually one of two things:
- Lazy sessions are not configured
The Mars plugin install should update the .htaccess file with the correct rules for lazy sessions. If it did not, the plugin will not be able to see the login information passed by Shibboleth. Check your .htaccess file to make sure the lazy session configuration is in place.
- Lazy sessions are used with IP restrictions
See the Apache 2.4 Require All Granted Problem page for details and solution.