Introduction

 This documentation has been tested on RHEL/CentOS 6 and 7, but should work on other RedHat-based systems as well.

Prerequisites

Firewall settings

• inbound traffic:
  • webserver: port 80 and/or 443 are used by any browser-user
• outbound:
  • Shibboleth daemon (shibd): has to be able to connect to every remote IdP in the federation on port 8443 for back-channel communication.

Time synchronization

Dependencies

Before starting to build and configure the Shibboleth Sevice Provider, be sure that the dependent packages (Apache, and the mod_ssl module for Apache) are installed:

yum install httpd mod_ssl

SELinux

Installation

Shibboleth SP is available for RedHat and derivative distributions via yum repositories maintained by the Shibboleth Project.  The repository configuration files are generated by the shibbolet.net download site based on the target Linux distribution.  You can either download the .repo  file directly by passing in the distribution name as per the examples below, or you can download it via a browser from https://shibboleth.net/downloads/service-provider/latest/RPMS/ and then copy it to the target system.

• Add the yum repository for your distribution (example for CentOS 7):

  wget -O /etc/yum.repos.d/shibboleth.repo https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7 

  
  The table below includes links for additional supported distributions (taken from the download form linked above)

  Platform (OS)	URL
  CentOS 8 and RHEL 8	https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_8
  CentOS 7 and RHEL 7	https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=CentOS_7
  Rocky Linux 8	https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=rockylinux8
  Amazon Linux 2	https://shibboleth.net/cgi-bin/sp_repo.cgi?platform=amazonlinux2

  RHEL 7 RPMs

  The Shibboleth Project provides binary packages for CentOS systems, but due to licensing restrictions, cannot build packages for RHEL 7 and above - full details are at https://wiki.shibboleth.net/confluence/display/SP3/RPMInstall.

  For RHEL 7 (and above) systems, please use the binary-compatible CentOS repository.

  And, for version 8, as CentOS 8 is not what it was expected to be, Rocky Linux 8 is a supported alternative...

• Install latest version via yum:

  yum install shibboleth

Federation Membership

Navigate to the Tuakiri federation management site https://registry.tuakiri.ac.nz/federationregistry (or, for Tuakiri-TEST federation, https://registry.test.tuakiri.ac.nz/federationregistry).

If you do not have an account with an IdP registered in the federation and you do not have an account with the Tuakiri VHO, start the SP registration (without logging in), by clicking the Create Service Provider link in the blue menu bar.

Otherwise, click Login and login using your IdP. Start the registration by clicking Subscribers > Service Providers > Create.

The registration form first displays a check-list of required information.  Please check that you have all the information the check-list asks for readily available, otherwise the registration form may time out while you gather missing information.

Please note that on the registration form, you'll be asked to select the organization you are registering the SP under.  If you have not registered your organization into Tuakiri (or Tuakiri-TEST) yet, please complete that process first, following our instructions for Creating an Organization in the Tuakiri Federation.

1. If you are filling this form without having logged in, you'll have to enter your details: Given Name, Surname and Email (otherwise, these are prefilled). (Do not use a shared mailbox, alias or mailing list when entering an email address because the confirmation email contains a single-use link and may cause some confusion should more than one person attempt to use it.)
   
   
2. Enter the information that describes the Service Provider being registered:
   • Select your Organization; if the organization you wish to host the Service Provider under does not exist, follow this procedure to create one. (Required)
   • Enter a Display Name and Description for your Service Provider. (Required)
   • Enter a Service URL for accessing your Service Provider in the form http://sp.example.org. The service URL is typically the base URL for accessing the Service Provider. (Required)
   • Optionally enter a URL in the Service Logo URL to a image or logo representing the service the Service Provider is authenticating. (Optional)
3. Enter the basic SAML configuration:
   • Choose the Shibboleth SP version that is installed on the Service Provider.
   • Enter the Service Provider's base URL for the Host, without a trailing slash, just as https://sp.example.org. The Federation Registry will automatically create all of the SAML2 endpoints from this base URL.  You can skip over the Advanced SAML2 Registration section.
   • Alternatively, if your deployment does not fit the basic SAML configurator (either your implementation is not among the pre-configured ones, or you use custom endpoint URLs),  please fill in the entityID and the endpoint URLs in the Advanced SAML2 Registration section.

4. Copy and paste in the back-channel certificate(s) generated when installing the Shibboleth SP software.

   For Shibboleth SP 2.x, the certificate is usually located in /etc/shibboleth/sp-cert.pem.

   Starting with Shibboleth 3.0, the two separate certificates are generated for encryption and signing.  These certificates are stored as /etc/shibboleth/sp-signing-cert.pem and /etc/shibboleth/sp-encrypt-cert.pem

   As of October 2018, Federation Registry supports including separate signing and encryption certificates on the registration form.  If you are registering an SP that has a single certificate used for both signing and encryption, copy the same certificate into both fields.  If your SP does not support encryption, leave the encryption certificate field blank (but a signing certificate is required).

   When pasting the certificate into the form, please take care that no line breaks, spaces or other characters are introduced during the cut-paste process.

   • Please note that it is highly recommended that the CN in the certificate matches the hostname the service provider is being registered under. If this is an alias and your system thinks of itself with a different hostname, we recommend you instead generate a new certificate with the correct hostname: run the following, substituting the externally visible hostname for sp.example.org:

     cd /etc/shibboleth
     # for a Shibboleth 2.x system:
     ./keygen.sh -f -u shibd -g shibd -y 20 -h sp.example.org -e https://sp.example.org/shibboleth
     # or for a Shibboleth 3.x system:
     ./keygen.sh -f -n sp-signing -u shibd -g shibd -y 20 -h sp.example.org -e https://sp.example.org/shibboleth
     ./keygen.sh -f -n sp-encrypt -u shibd -g shibd -y 20 -h sp.example.org -e https://sp.example.org/shibboleth 

5. Select the attributes Requested and mark which are Required. For each attribute requested give a good explanation for why the attribute is requested. This information will later be displayed to users as justification for why the information is being released.

   Persistent NameID

   Please note that with the IdPv3 upgrade, Tuakiri is moving from passing Persistent NameIDs in the eduPersonTargetedID attribute to passing them as a Persistent SAML2 NameID.  When registering a new SP requesting a persistent NameID, please request both the eduPersonTargetedID attribute (for interoperability with existing V2 IdPs), as well as NameID of Persistent format.  You will be able to add the SAML 2.0 Persistent NameIDFormat after your SP registration is approved - or please get in touch with the Tuakiri Support.

   schac attributes

   Please note that as of 2.6.0, Shibboleth SP includes attributes from the schac schema in the default configuration.  The names used for the attributes there are slightly different from what has been used in the attribute-map.xml file provided by Tuakiri for use with earlier versions of Shibboleth SP.  For compatibility with 2.6.0, we have adjusted the names in attribute-map.xml to match the names used by the 2.6.0 default configuration.

   homeOrganization is becoming schacHomeOrganization
   homeOrganizationType is becoming schacHomeOrganizationType

   eduPersonEntitlement attribute

   Please note: if intending to request the eduPersonEntitlement attribute, you cannot add the attribute to the list of requested attributes on the registration page; you'll have to add it separately later.

   Also, because of the nature of this attribute, you also have to include a specific requested value (or a regular expression matching a set of values), but an eduPersonEntitlement attribute request without specific values is not considered complete and will be ignored by the Federation Registry.

6. Click Submit and wait for a confirmation email.

ECP support

If your SP should support ECP (access via non-browser clients), then also register support for ECP:

• After your SP registration is complete, log into the Federation Registry again (in the same way as above)
• Open the entry for your SP (under Subscriprs -> Service Providers or directly from the Dashboard)
• Under EndPoints -> Assertion Consumer Service, add a new Endpoint:
  • Select Binding: urn:oasis:names:tc:SAML:2.0:bindings:PAOS
  • Enter Location: https://sp.example.org/Shibboleth.sso/SAML2/ECP (substituting sp.example.org with your SP hostname)
  • Enter Index: 4 (value 4 matches the value in the Shibboleth SP internal metadata in the default configuration)
• Remember to also configure support for ECP in your /etc/shibboleth/shibboleth2.xml file.

Configuration

• With earlier versions of Shibboleth SP (2.x), it was necessary to work around issues with rotation of logs generated by the mod_shib  module running inside Apache.  In Shibboleth SP 3.x, this module logs via syslog and this is no longer an issue.  If deploying a 2.x installation or explicitly logging to file, expand this section (otherwise archived for historical purposes only).

   Click here to expand...

  Workaround : move the log rotation from the module to logrotate.

  • Otherwise, SELinux rules would not permit the log rotation (by design Apache is allowed to only append to logs, but cannot remove them – incl. renaming).
  • And there is also a race condition in the log rotation.  This has been reported upstream as SSPCPP-757 - and we recommend to move log rotation out of mod_shib to logrotate.
    
    
  • Edit /etc/shibboleth/native.logger  and:
    • replace RollingFileAppender with FileAppender
    • comment out log rotation-specific options: maxFileSize and maxBackupIndex
    • or just replace the file with our copy with exactly these customizations: native.logger

  • Install a new file into /etc/logrotate.d/shibboleth-www to rotate these files via logrotate (and reload Apache post-rotate): shibboleth-www containing:

    
    

    /var/log/shibboleth-www/*.log {
        missingok
        daily
        rotate 10
        nodateext
        size 1000000
        sharedscripts
        postrotate
            /sbin/service httpd reload > /dev/null 2>/dev/null || true
        endscript
    }
    

  • These can be both installed with:

    wget -O /etc/shibboleth/native.logger https://github.com/REANNZ/Tuakiri-public/raw/master/shibboleth-sp/native.logger
    wget -O /etc/logrotate.d/shibboleth-www https://github.com/REANNZ/Tuakiri-public/raw/master/shibboleth-sp/logrotate-redhat/shibboleth-www

Special considerations

HTTP/HTTPS access

consistentAddress="false"

RedHat Enterprise Linux 6 and 7

Please note that RedHat Enterprise Linux 6 and 7 (and so also CentOS 6 and 7) come with CURL built against NSS, not OpenSSL. Using this version of the CURL libraries would break the SOAP calls Shibboleth SP is making to the IdP port 8443 (back-channel communication) for artifact resolution and attribute queries.  While initial approach taken by the Shibboleth SP project was to provide CURL version linked against OpenSSL that would "upgrade" (replace) the one that comes with the OS, this was later seen as having undesired consequences and the new approach is to instead provide "look-aside" version of the library that installs into /opt.

These libraries install automatically as dependencies of the main shibboleth package and no action is needed by the deployer.

Further information is available in the upstream documentation at https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxRH6

ECP

Logging

Protecting a resource

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

<Location />
  AuthType shibboleth
  ShibRequestSetting requireSession 0
  require shibboleth
</Location>

<Location /secure>
  AuthType shibboleth
  ShibCompatWith24 On
  ShibRequestSetting requireSession 1
  require shib-session
</Location>

<Location />
  AuthType shibboleth
  ShibCompatWith24 On
  ShibRequestSetting requireSession 0
  require shibboleth
</Location>

Finishing up

• Start up Apache and shibd:

   service httpd start
   service shibd start
   chkconfig httpd on
   chkconfig shibd on
  

  On RHEL7/CentOS7 using systemd, the commands should properly be:

  systemctl enable httpd shibd
  systemctl start httpd shibd

  (but the legacy syntax invoking service and chkconfig still works and is rerouted to systemctl)

Testing

1. Place a script inside the protected directory. PHP example script such as the following is good enough:

   <?php print_r($_SERVER) ?>

2. Access the protected directory/script (http://your.server/secure) from your browser, this should trigger a complete SSO cycle where you can authenticate on your IdP
3. Upon successful authentication, the page should display all received attributes. Make sure you have non empty Shib-Application-ID amongst other attributes (if your IdP release them).
4. Check your shibd.log to see if there are attributes received or errors encountered.