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

For those still running Apache httpd 2.2, you should add a compatibility line. Do not use this with httpd 2.4, or it will throw an error.

ShibCompatWith24 on

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.

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 converting from WRAP to Shibboleth

In all of these examples, remember you should omit the ShibCompatWith24 directive if you are already running on Apache httpd 2.4 or newer.

WRAP allowed any user who could login

Note: WRAP allowed users without Unity accounts to login as Guest. This example config would allow Guest access. There is no Guest account on our NC State Shibboleth IdP.

Old WRAP code:

AuthType WRAP
require valid-user

New Shibboleth code:

AuthType shibboleth
ShibRequestSetting requireSession true
require shib-session

WRAP allowed any NC State users

Old WRAP code:

AuthType WRAP
require affilaition ncsu.edu
require known-user

New Shibboleth code:

AuthType shibboleth
ShibRequestSetting requireSession true
require shib-attr SHIB_AFFILIATION member@ncsu.edu
require shib-attr SHIB_AFFILIATION affiliate@ncsu.edu

WRAP allowed access to specific users

WRAP passed bare UnityID as the REMOTE_USER variable. Shibboleth prefers to use the eduPersonPrincipalName, or EPPN, which is "UnityID@ncsu.edu".

Old WRAP code:

AuthType WRAP
require affilaition ncsu.edu
require user abaker2
require user bcollin3 cdurham4 efitzger

New Shibboleth code:

AuthType shibboleth
ShibRequestSetting requireSession true
require shib-user abaker2@ncsu.edu 
require shib-user bcollin3@ncsu.edu cdurham4@ncsu.edu efitzger@ncsu.edu

WRAPOptional lazy sessions

It is possible to configure Shibboleth to be enabled in a directory while not requiring it to force a login to establish a session. This functionality was provided by WRAP using the WRAPOptional directive.

Old WRAP code:

AuthType WRAPOptional
require nothing

New Shibboleth code:

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.