Shibboleth at NC State » Technical Documentation » Using .htaccess files

Using .htaccess files

The official Shibboleth wiki provides these documents:

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

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:

require shib-session

Rules to allow any user with a current NC State Unity account:

require shib-attr SHIB_AFFILIATION member@ncsu.edu
require shib-attr SHIB_AFFILIATION affiliate@ncsu.edu

To allow active faculty OR staff at NC State, use:

require shib-attr SHIB_AFFILIATION faculty@ncsu.edu
require shib-attr SHIB_AFFILIATION staff@ncsu.edu

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 student@ncsu.edu
  require shib-attr SHIB_AFFILIATION staff@ncsu.edu
</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 mjuser2@ncsu.edu
require shib-user jquser3@ncsu.edu
require shib-user auser1@ncsu.edu buser2@ncsu.edu cuser3@ncsu.edu

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.

Examples

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 member@ncsu.edu
require shib-attr SHIB_AFFILIATION affiliate@ncsu.edu

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 abaker2@ncsu.edu 
require shib-user bcollin3@ncsu.edu cdurham4@ncsu.edu efitzger@ncsu.edu

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:

For a working example in our environment, see our Lazy Session demo. See also the SWITCH Lazy Sessions demo site.

Common Problems

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:

  1. 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.

  1. Lazy sessions are used with IP restrictions

See the Apache 2.4 Require All Granted Problem page for details and solution.