Shibboleth Primer

Overview

The page contains information on getting a Shibboleth Provider installed, registered and configured at Iowa State. The information assumes a Red Hat Enterprise Linux (RHEL) 6 or 7 environment and may need to be adjusted for other distributions and versions. Be sure to understand the terms and concepts in the Shibboleth Glossary.

Getting Started

An outline of the process:

Installation Prerequisites
Install Apache
Install Shibboleth
Register Service Provider(s)
Install Downloaded Shibboleth Configuration
Configure Apache
Testing
Going Further

Installation Prerequisites

SSL Certificate

If you do not already have one, you will need an SSL Web Server Certificate. You can Request an SSL Web Server Certificate using ASW. Please see the guidance on choosing a certificate type.

NTP

Shibboleth will not work if your system's time drifts too far from the actual time. If you haven't done so already, you will need to install ntpdate and ntpd to insure your system's time stays closely synched with reality:

    yum install ntpdate ntpd
    systemctl enable ntpdate ntpd
    systemctl ntpdate start
    systemctl ntpd start

Firewall

If you are running a firewall (iptables under RHEL6 or firewalld under RHEL7) you will need to insure that the appropriate ports are not blocked. Under RHEL7, the default configuration blocks the https port. To open it do:

    firewall-cmd --permanent --add-port=443/tcp
    firewall-cmd --reload

SELinux

If you are using SELinux, please consult the Shibboleth SELinux help page.

Install Apache

    yum install httpd mod_ssl

Install Shibboleth

Download the shibboleth.repo configuration file appropriate to your OS version into the /etc/yum.repos.d directory:

    cd /etc/yum.repos.d
    curl -O https://asw.iastate.edu/shibboleth/yum/RHEL6/shibboleth.repo
        or
    cd /etc/yum.repos.d
    curl -O https://asw.iastate.edu/shibboleth/yum/RHEL7/shibboleth.repo

Then install shibboleth as appropriate to your OS version:

    yum install shibboleth
        or
    yum install shibboleth.x86_64

(if you are asked about downloading a key from download.opensuse.org, answer y)

Register Service Provider(s)

Complete the form to create an Service Provider on ASW.

This process will culminate with the download a file of configuration data.

Install Downloaded Shibboleth Configuration

tar xvpCf /etc/shibboleth /path/to/downloaded/etc_shibboleth.tar

Configure Apache

If you are using RHEL7, the default Apache config seems to listen only on IPv6 which is problematic. To change to IPv4, edit the Listen directives to include 0.0.0.0, for example:

    Listen 0.0.0.0:443

Shibboleth uses the host's name to locate which configuration to use. For this reason it is important that Apache always use the correct canonical name when generating redirects to shibboleth:

    ServerName server.name.you.used.in.asw.to.generate.config
    UseCanonicalName On

If your base configuration file does not contain a wildcard include like:

    Include conf.d/*.conf

you will need to specifically include the shibboleth configuration file:

    Include conf.d/shib.conf

Typically, you will create a configuration section similar to this:

    <Location /directory>
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        Require shibboleth
    </Location>

If you were previously using Pubcookie, you will also want to remove any Pubcookie configuration directives such as:

    <Location /directory>
        PubcookieInactiveExpire -1
        PubcookieAppID protected
        AuthType getcred
        require valid-user
    </Location>

If you are using Drupal, you will need to edit the top-level .htaccess file to keep Drupal from interfering with Shibboleth. Locate the Rewrite section and add a RewriteCond to exclude Shibboleth URLs from being munged

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_URI} !=/favicon.ico

    RewriteCond %{REQUEST_URI} !^/Shibboleth.sso(|/)

    RewriteRule ^ index.php [L]

Additional information is available at:
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPApacheConfig
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPhtaccess
https://github.com/isubit/pubcookie

Whenever you make a change to apache's config, be sure to restart apache and shibd:

    /sbin/service httpd restart
    /sbin/service shibd restart

Testing

The default /etc/httpd/conf.d/shibd.conf configuration file comes with a configuration to protect the location /secure, which you can use for testing:

    cd /var/www/html
    mkdir -m 0750 secure
    chgrp apache secure
    echo "This file is protected" > secure/index.html

Now browse to https://yoursite.yourdept.iastate.edu/secure If you are not already logged in, you should get the weblogin page. After entering a valid NetID and password, you should see "This file is protected".

Going Further

One of the strengths of Shibboleth is that in addition to providing basic authentication (e.g., setting REMOTE_USER) is that it can provide a set of attributes to your web server (and any cgi programs there). At ISU we provide shibboleth attributes for all the attributes stored in the public directory server which you may use for authorization decisions and so on. Please consult the List of Attributes Released.

Account Services on the Web

Page Help