Shibboleth can be built on most versions of 32- and 64-bit Linux, but is officially supported only on the following distributions at this time, using the RPM packages available from the project’s official mirrors:

• Red Hat Enterprise and CentOS 6, 7 (packages only provided for 7.4+)
• SUSE Linux Enterprise Server 11-SP3, 11SP4, 12SP3, 12SP4

Packages may be available for other distributions but they are frequently out of date or have other issues. If you must use an unsupported distribution, see Shibboleth SP Provider on Unsupported Linux Distributions for potential solutions.

Download instructions can be found on the Shibboleth wiki’s installation page.  Be sure to read the System Requirements before beginning. The installation builds and installs an apache module (e.g., mod_shib_xx.so) and the shibd daemon.

The RPM installation process will place various components of Shibboleth in appropriate default directories based on your operating system’s file system layout. Typically:

/etc/shibboleth

• • Shibboleth configuration directory. Thme main configuration file is shibboleth2.xml.

/var/log/shibboleth

• • Log file directory. The most important log file for troubleshooting is shibd.log.

/run/shibboleth

• • Runtime directory where process ID and socket files are stored.

/var/cache/shibboleth

• • Cache directory where metadata backup and CRL files are stored.

/etc/httpd/conf.d/shib.conf

• • Relevant Apache configuration file.

/usr/sbin

• • shibd resides here and may be managed using service and chkconfig (on System V platforms) or with systemctl (on systemd platforms, some additional information available).

/usr/lib/shibboleth/ on a 32-bit OS and /usr/lib64/shibboleth on a 64-bit OS

• • The version of mod_shib_xx.so appropriate to the OS-supplied Apache and other pluggable modules are installed here.

1. In the command line, execute the following command to see whether the Shibboleth Service Provider can load the default configuration:

   sudo shibd -t

   The last line of the output should read:

   overall configuration is loadable, check console for non-fatal problems

   If there are any ERROR log entries, we strongly recommended you resolve these.

   Messages with log level WARN are generally not problematic but you should understand the causes of these warning messages and run the configuration check again when you are finished with your setup.

2. Also test the Apache configuration with the command:

   sudo apachectl configtest

   The output of this command should be:

   Syntax OK

3. (Re-) Start the web server and then access the URL: https://yourhost.example.org/Shibboleth.sso/Session
   The web server (or rather the Shibboleth daemon respectively) should return a page that says:
   A valid session was not found.
   This message shows that the Shibboleth module is loaded by the webserver and is communicating with the shibd process.

Configure your SP to work with the University’s Identity Provider (IdP). It is often easiest to start with a simple setup and expand to more complex configurations later. In file shibboleth2.xml, element ApplicationDefaults

1. Change the entityID attribute to a good value for your SP. The best thing to do here is edit the default value of https://sp.example.org/shibboleth to something based on your host’s DNS name, e.g. https://myserver.mydept.washington.edu/shibboleth.
2. Change the SSO element to point directly at the UW’s IdP.

   <SSO id="UW" isDefault="true" entityID="urn:mace:incommon:washington.edu"> SAML2 SAML1 </SSO>

3. Confirm that the Sessions element has a checkAddress attribute of

   checkAddress="false"

4. Element MetadataProvider
   • Depending on the needs and capabilities of your Service Provider, you have multiple IdP metadata configuration options. UW IdP Metadata describes the options and makes recommendations based on use case. It provides links to the following instructions:
     • Configure a Shibboleth SP to Use the InCommon Per-Entity Metadata Distribution Service
     • Configure a Shibboleth SP to Consume Metadata from a Local IdP Endpoint
     • Configure a Shibboleth SP to Use the InCommon Metadata Aggregate File
5. Restart your apache and shibd services.

In order to ease the configuration chore there are many defaults that are usually correct. You may need to change some of these defaults. In particular, even in a simple installation, you may want to change pathnames of log files or similar. This is a quick guide to some of those simple things you might want to change.

The prefix that the SP was built with is often used when relative pathnames are configured. The prefix might be /opt/shibboleth-sp, /usr/local, /etc/shibboleth, or something else.

1. Logging: If you need to change the locations of shib’s log files, or control the amount of log output, edit the appropriate configuration file:
   • shibd logging is configured in shibd.logger
   • the apache modules’s logging is configured in native.logger.
2. Sockets: Shib uses local sockets, usually in prefix/var/run/shibboleth/, which is created during installation. To change these locations:
   • The UnixListener defaults shibd.sock in the var directory. To change that edit the UnixListener element of shibboleth2.xml, e.g.

     <UnixListener address="/var/run/shibd.sock"/>

   • The DiscoveryFeed Handler defaults to the same var directory. To change that edit the “DiscoveryFeed” Handler element of shibboleth2.xml, e.g.

     <Handler type="DiscoveryFeed" Location="/DiscoFeed" dir="/var/run/shibboleth"/>

3. Metadata backing files: Metadata automatically downloaded from a source caches files in the var directory as well. An absolute pathname often seems the better choice.
   • Edit shibboleth2.xml and change the backingFilePath attribute of the MetadataProvider element.
4. SP signing certificate and key: The key/cert pair sp-key.pem and sp-cert.pem, in the conf directory, were generated by the installation process and are referred to in shibboleth2.xml‘s CredentialResolver. There is no need to change these files. 
   If, though, you are the sort that likes to look for trouble, you can generate these files with the provided keygen.sh script.

    cd <config directory>
   ./keygen.sh -b

   If you have some doubts about the contents of these files you can examine them to see if they refer to the correct hostname. For example, you might use

   openssl x509 -in sp-cert.pem -noout -subject

   The expiration status of the cert does not matter. An expired cert is fine.

1. Locally (for UW only)
   • If your service provider will only rely on the UW’s IdP register it at the Service Provider Registry. See Register a Service Provider with the UW for more information.
2. With InCommon (for federated use)
   • If you service provider will rely on multiple identity providers in the InCommon federation, see Request Service Provider Registration with InCommon.

1. Protect some resource with Shibboleth authorization, via .htaccess file:
   • shibd logging is configured in shibd.logger


     AuthType shibboleth
     ShibRequestSetting requireSession 1
     require valid-user

2. Direct your browser at this resource, specifying https.
   • Ensure that the directories containing .htaccess files are configured with ‘AllowOverride AuthConfig’ in the Apache static configuration. The AllowOverride directive works only in <Directory> sections.
   • To require login to an application via apache configuration directives:

     <Location /protected-area>
     AuthType shibboleth ShibRequestSetting requireSession 1
     require shib-session </Location>