debian/libapache2-mod-shib2.README.Debian

   1                         Shibboleth 2 SP for Debian
   2
   3 Introduction
   4
   5   This package provides the Shibboleth Apache module and accompanying
   6   daemon for a service provider.  In Shibboleth terminology, this is a web
   7   server serving some content that should be secured via Shibboleth.  In
   8   order for someone to access protected content from a Shibboleth SP, they
   9   will have to authenticate to a Shibboleth IdP (Identity Provider),
  10   either one that the Shibboleth SP points to directly or one that is part
  11   of a federation that is trusted by the Shibboleth SP.
  12
  13   This is the Shibboleth 2 version of the SP.  For the 1.x version of
  14   the Shibboleth SP (if it is still available), see libapache-mod-shib.
  15
  16 Installation and Configuration
  17
  18   After installing this package, the module is available but not enabled.
  19   It's not enabled automatically since some configuration is required
  20   before it will work (at least creating a certificate for the SP to use
  21   to authenticate to IdPs).
  22
  23   To generate a self-signed certificate for the Shibboleth SP, run
  24   shib-keygen.  See its manual page for more information.  This may or may
  25   not be what you want to do depending on which federation you plan on
  26   joining; some federations may want you to follow other procedures for
  27   generating a certificate.
  28
  29   The default error messages from Shibboleth are located in
  30   /etc/shibboleth/*.html.  The paths to those error messages are
  31   configured in /etc/shibboleth/shibboleth2.xml in the <Errors> tag.  If
  32   you customize them, you may want to copy them somewhere else and change
  33   /etc/shibboleth/shibboleth2.xml to point to the new locations.  Also in
  34   that <Errors> tag you can set the URLs to the logo and style sheet used
  35   by the default errors.  If you want to use the default URL (under
  36   /shibboleth-sp), add this to your Apache configuration:
  37
  38     <Location /shibboleth-sp>
  39         Allow from all
  40     </Location>
  41     Alias /shibboleth-sp/main.css /usr/share/shibboleth/main.css
  42     Alias /shibboleth-sp/logo.jpg /usr/share/shibboleth/logo.jpg
  43
  44   For Shibboleth to work properly, you will need to extensively customize
  45   /etc/shibboleth/shibboleth2.xml for your site.  In particular, the
  46   <ApplicationDefaults> section will have to be customized for the
  47   federations your SP will trust and the <CredentialResolver> section of
  48   <Applications> needs to list the credentials that your SP will use to
  49   authenticate when communicating with IdPs.  Your local site may provide
  50   a standard shibboleth2.xml for you to use.
  51
  52   Finally, you will want to protect some web content with Shibboleth.  The
  53   most basic configuration is:
  54
  55     <Location /secure>
  56         AuthType shibboleth
  57         ShibRequireSession On
  58         require valid-user
  59     </Location>
  60
  61   for some <Location>, <Directory>, or <Files> block.  You can also put
  62   similar code in an .htaccess file.  This will require authorization
  63   using the default federation defined in /etc/shibboleth/shibboleth2.xml.
  64
  65 Changes in Debian Package
  66
  67   The logging configuration for the native.log file has been changed to
  68   use syslog, since the upstream default tries to write to a file that
  69   Apache has no privileges to write to.  See /etc/shibboleth/native.logger
  70   for more details.  If you want the other parts of Shibboleth to also log
  71   to syslog, change the other /etc/shibboleth/*.logger files similarly.
  72
  73   The WS-Trust.xsd schema, which is needed if you use the ADFS support
  74   and turn on schema validation, was removed from the Debian package for
  75   license reasons.  To enable it again, do the following:
  76
  77     1. Download the original source from
  78        http://shibboleth.internet2.edu/downloads/shibboleth/cppsp/latest/
  79
  80     2. Extract schemas/WS-Trust.xsd to some convenient location, for
  81        example to /etc/shibboleth/WS-Trust.xsd.
  82
  83     3. Copy /usr/share/xml/shibboleth/catalog.xml into /etc/shibboleth.
  84
  85     4. Uncomment the WS-Trust line and set its uri attribute:
  86        <system systemId="http://schemas.xmlsoap.org/ws/2005/02/trust"
  87                uri="/etc/shibboleth/WS-Trust.xsd"/>
  88
  89     5. Edit /etc/default/shibd to contain
  90        DAEMON_OPTS="-x /etc/shibboleth/catalog.xml:/usr/share/xml/opensaml/saml20-catalog.xml:/usr/share/xml/xmltooling/catalog.xml"
  91
  92     6. Restart the Shibboleth daemon: /etc/init.d/shibd restart.
  93
  94 Testing with TestShib
  95
  96   If you don't have a local Shibboleth Federation you can easily join but
  97   want to test your Shibboleth installation, you can use the TestShib
  98   federation (which exists primarily for this purpose).  To do this, use
  99   the following instructions (but test them against the details on the
 100   testshib.org web pages in case anything has changed):
 101
 102   1. If you do not have an OpenIDP identity, go to <http://openidp.org/>
 103      and create one.
 104
 105   2. Go to <http://testshib.org/>, click on Join, and then Create and
 106      manage metadata entries.  Log in with your OpenIDP identity.
 107
 108   3. Click on New Service Provider (unless you've already created an entry
 109      for this host, in which case reuse it).  Enter your hostname, your
 110      public certificate, and your first and last name, and then click on
 111      Continue.  Verify the information and click on Submit.
 112
 113   4. Note the URL in quotes at the top of the page for which the
 114      credentials were "successfully stored."  This URL is your server's
 115      providerID; save it for later.
 116
 117   5. Now select Configure, scroll down to Service Provider Configuration,
 118      choose Other for the platform, and click on Create Me.  Save the
 119      resulting configuration file as /etc/shibboleth/shibboleth2.xml.
 120
 121   6. Create some part of your web site that's protected with Shibboleth as
 122      described above, restart Apache with apache2ctl restart, restart
 123      shibd with /etc/init.d/shibd restart, and then go to that URL.  You
 124      should be redirected to the testshib.org IdP, and then get a basic
 125      auth dialog box prompting for a username and password.  Enter
 126      "myself" and "myself".  You should now be redirected back to your
 127      protected page.  The best test page to use is a CGI script that
 128      prints out the environment; you can then confirm that you see the
 129      Shibboleth attributes as environment variables.  If this doesn't work
 130      immediately, wait a few minutes and try again; sometimes the
 131      testshib.org metadata takes a little bit to update.
 132
 133   These directions should work as of June 2008, but note that the
 134   testshib.org service may have changed since then.  TestShib is useful
 135   *only* for testing, not for any production use.  Those of us who have
 136   worked on the Debian package are not affiliated with testshib.org, just
 137   personally find it useful, and make no guarantees that it will work
 138   properly.  You should read over the shibboleth2.xml file that you
 139   download from testshib.org before using it to make sure that there's
 140   nothing strange in it.
 141
 142   If the above instructions don't work or there are changes in the
 143   TestShib service, please file a bug against the Debian
 144   libapache2-mod-shib2 package and let us know.
 145
 146 Further Information
 147
 148   For further installation information, see:
 149
 150     https://spaces.internet2.edu/display/SHIB2/Home
 151
 152   and in particular the "Configuration" link.
 153
 154  -- Russ Allbery <rra@debian.org>, Wed, 25 Jun 2008 19:46:06 -0700