Shibboleth Service Provider for Debian

Introduction

  This package provides the Shibboleth Apache module and accompanying
  daemon for a service provider.  In Shibboleth terminology, this is a web
  server serving some content that should be secured via Shibboleth.  In
  order for someone to access protected content from a Shibboleth SP, they
  will have to authenticate to a Shibboleth IdP (Identity Provider),
  either one that the Shibboleth SP points to directly or one that is part
  of a federation that is trusted by the Shibboleth SP.

Installation and Configuration

  The following instructions assume use of the Apache 2.4 access
  restriction syntax.  If you are still using the earlier Allow/Deny
  directives, you may need to use "Allow from all" instead of or in
  addition to "Require all granted".

  After installing this package, the module is enabled but not properly
  configured.  At least some manual configuration will be required before
  the module can be used, such as creating a certificate for the SP to use
  to authenticate to IdPs.

  To generate a self-signed certificate for the Shibboleth SP, run
  shib-keygen.  See its manual page for more information.  This may or may
  not be what you want to do depending on which federation you plan on
  joining; some federations may want you to follow other procedures for
  generating a certificate.

  A default Apache configuration for the module is installed in
  /etc/apache2/conf-available/shib.conf and contains the two Location
  blocks reproduced below.  You can modify it to suit your site's
  needs or disable it entirely with a2dismod.

  If you use a restrictive Apache configuration that denies access to all
  URLs by default, you will need to open access to the /Shibboleth.sso URL
  namespace.  For example (as enabled from /etc/apache2/conf-available.d):

    <Location "/Shibboleth.sso">
        AuthType None
        Require all granted
    </Location>

  The default error messages from Shibboleth are located in
  /etc/shibboleth/*.html.  The paths to those error messages are
  configured in /etc/shibboleth/shibboleth2.xml in the <Errors> tag.  If
  you customize them, you may want to copy them somewhere else and change
  /etc/shibboleth/shibboleth2.xml to point to the new locations.  Also in
  that <Errors> tag you can set the URLs to the logo and style sheet used
  by the default errors.  If you want to use the default URL (under
  /shibboleth-sp), add this to your Apache configuration:

    <Location /shibboleth-sp>
        AuthType None
        Require all granted
    </Location>
    Alias /shibboleth-sp/main.css /usr/share/shibboleth/main.css

  For Shibboleth to work properly, you will need to extensively customize
  /etc/shibboleth/shibboleth2.xml for your site.  In particular, the
  <ApplicationDefaults> section will have to be customized for the
  federations your SP will trust and the <CredentialResolver> section of
  <Applications> needs to list the credentials that your SP will use to
  authenticate when communicating with IdPs.  Your local site may provide
  a standard shibboleth2.xml for you to use.

  Finally, you will want to protect some web content with Shibboleth.  The
  most basic configuration is:

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

  for some <Location>, <Directory>, or <Files> block.  You can also put
  similar code in an .htaccess file.  This will require authorization
  using the default federation defined in /etc/shibboleth/shibboleth2.xml.

Changes in Debian Package

  The WS-Trust.xsd schema, which is needed if you use the ADFS support
  and turn on schema validation, was removed from the Debian package for
  license reasons.  To enable it again, do the following:

    1. Download the original source from
       https://shibboleth.net/downloads/service-provider/latest/

    2. Extract schemas/WS-Trust.xsd to some convenient location, for
       example to /etc/shibboleth/WS-Trust.xsd.

    3. Copy /usr/share/xml/shibboleth/catalog.xml into /etc/shibboleth.

    4. Uncomment the WS-Trust line and set its uri attribute:
       <system systemId="http://schemas.xmlsoap.org/ws/2005/02/trust"
               uri="/etc/shibboleth/WS-Trust.xsd"/>

    5. Edit /etc/default/shibd to contain
       DAEMON_OPTS="$DAEMON_OPTS -x /etc/shibboleth/catalog.xml:/usr/share/xml/opensaml/saml20-catalog.xml:/usr/share/xml/xmltooling/catalog.xml"

    6. Restart the Shibboleth daemon: service shibd restart.

  Extend the above for other missing schema files as necessary.

Testing with TestShib

  If you don't have a local Shibboleth Federation you can easily join but
  want to test your Shibboleth installation, you can use the TestShib
  federation (which exists primarily for this purpose).  To do this, use
  the following instructions (but test them against the details on the
  testshib.org web pages in case anything has changed):

  1. Run shib-keygen to generate a certificate for your new SAML entity.

  2. Set the entityID attribute in the ApplicationDefaults element of
     shibboleth2.xml to a value like https://your.service.tld/shibboleth;
     it needn't be resolvable, though that might come handy later, see
     https://wiki.shibboleth.net/confluence/display/CONCEPT/EntityNaming.

  3. Run a2enmod shib2 && apache2ctl restart && service shibd restart.

  4. Go to <http://testshib.org/>, click on Register, and follow the
     instructions to obtain your SP metadata and upload it under a unique
     name.

  5. Now select Configure, scroll down to Service Provider Configuration,
     choose Other for the platform, enter the hostname of your web server,
     and click on Create Me.  Save the resulting configuration file as
     /etc/shibboleth/shibboleth2.xml.

  6. Create some part of your web site that's protected with Shibboleth as
     described above, restart Apache with apache2ctl restart, restart
     shibd with service shibd restart, and then go to that URL.  You
     should be redirected to idp.testshib.org, and after logging in with
     one of the offered identities, redirected back to your
     protected page.  The best test page to use is a CGI script that
     prints out the environment; you can then confirm that you see the
     Shibboleth attributes as environment variables.  If this doesn't work
     immediately, wait a few minutes and try again; sometimes the
     testshib.org metadata takes a little bit to update.

  These directions should work as of Jan 2016, but note that the
  testshib.org service may have changed since then.  TestShib is useful
  *only* for testing, not for any production use.  Those of us who have
  worked on the Debian package are not affiliated with testshib.org, just
  personally find it useful, and make no guarantees that it will work
  properly.  You should read over the shibboleth2.xml file that you
  download from testshib.org before using it to make sure that there's
  nothing strange in it.

  If the above instructions don't work or there are changes in the
  TestShib service, please file a bug against the Debian
  libapache2-mod-shib2 package and let us know.

Further Information

  For further installation information, see:

    https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPConfiguration

 -- Etienne Dysli Metref <etienne.dysli-metref@switch.ch>, Mon, 27 Nov 2017 08:59:25 +0100