Shibboleth Developers

[(Nate Klingenstein)]

Including deployment information for the target side, slight revisions to
the origin side text, and other minor edits.  Huge thanks to Scott for
getting the text to me.

Shibboleth Deployment Guide

draft-internet2-mace-shibboleth-shib-deploy-02.txt
Nate Klingenstein
22 April, 2002
Comments should be directed to 
.


1.  Shibboleth Overview

    Shibboleth is a system designed to exchange attributes across realms for 
the
primary purpose of authorization.  It provides a secure framework for one
organization to transmit attributes about an indexically referenced principal
across security domains to another institution.  In the primary usage case, 
when
a user attempts to access a resource at a remote domain, the user's own home
security domain can send certain information about that user to the target 
site
in a trusted exchange.  These attributes can then be used as a means of 
deciding
access control to the resource by the same indexically referenced principal.
    When a user first tries to access a resource protected by Shibboleth, they
are redirected to the a service which asks the user to specify the 
organization
from which they want to authenticate.  If the user has not yet locally
authenticated to a WebISO service, the user will then be redirected to their
home institution's login page.  After the user authenticates, the Shibboleth
components at the local institution will generate a temporary indexical
reference, known as a handle, for the individual and send this to the target
site.  The target site then use the handle will ask for attributes about this
individual, then, based on these attributes, decide whether or not to grant
access.  The user may then be redirected to the requested materials.
    There are several controls on privacy in Shibboleth, and mechanisms are
specified to allow users to determine exactly which information about them is
released.  In many access control decisions, the actual identity isn't so
important as other attributes that are then associated with the principle, 
such
as faculty member or member of a certain class.  Because the user is known to
the target site only by a randomly generated handle, if sufficient, the target
site might know no more about the user than that the user is a member of the
origin organization.  The handle should never be used to decide whether or not
to grant access, and is intended only as a temporary assertion for requesting
attributes.

    a. Origin

    There are four primary components to the origin side in Shibboleth: the
Attribute Authority (AA), the Handle Service (HS), the directory service, and
the local sign-on system (SSO).  The AA and HS are provided with Shibboleth, 
and
an open-source WebISO solution produced by the University of Washington known 
as
Pubcookie is also supplied; the directory is provided by the origin site.
Shibboleth is designed to easily interface with legacy directory and sign-on
systems, but this may require some minimal coding to implement.
    From the origin site's point of view, the first contact will be the
redirection of a user to the handle service, which will then consult the SSO
system to determine whether the user has already been authenticated.  If not,
then the browser user will be asked to authenticate, and then sent back to the
target URL with a handle bundled in a SAML attribute assertion.  Next, a 
request
from the Shibboleth Attribute Requester (SHAR) will arrive at the AA which 
will
include the previously mentioned handle.  The AA then consults the ARP's for 
the
directory entry corresponding to the handle, queries the directory for these
attributes, and releases to the SHAR all attributes the SHAR is entitled to 
know
about that user.

    b. Target

    There are three primary components to the target side in Shibboleth: the
Shibboleth Indexical Reference Establisher (SHIRE), the Shibboleth Attribute
Requester (SHAR), and the resource manager (RM).  An implementation of each of
these is included in the standard Shibboleth distribution.  These components 
are
intended to run on the same web server.
    From the target's point of view, a browser will hit the RM with a request
for a Shibboleth-protected resource.  The RM then allows the SHIRE to step in,
which will use the WAYF to acquire the name of a handle service to ask about 
the
user.  The handle service (HS) will then reply with a SAML attribute assertion
containing a handle, which the SHIRE then hands off to the SHAR.  The SHAR 
uses
the handle and the supplied address of the corresponding attribute authority
(AA) to request all attributes it is allowed to know about the handle.  These
attributes are then handed off to the RM, which is responsible for using these
attributes to decide whether to grant access based on attribute acceptance
policies (AAP's).

    c. Where are you from? (WAYF)

    The WAYF service can be either outsourced and operated by a club or 
deployed
as part of the SHIRE.  It is responsible for allowing a user to associate
themself with an institution of their specification, then redirecting the user
to the known address for the handle service of that institution.

    d. Clubs

    A Shibboleth club is a crucial part of the underlying trust required for
function of the Shibboleth architecture.  A club is a group of
organizations(universities, corporations, content providers, etc.) who agree 
to
exchange attributes using the SAML/Shibboleth protocols.  In so doing, they 
must
implicitly or explicitly agree to a common set of guidelines.  Joining a club 
is
not explicitly necessary for operation of Shibboleth, but it dramatically
expands the number of targets and origins that can interact without defining
bilateral agreements between all these parties.
    A club can be created in a variety of formats and trust models, but must
provide a certain set of services to club members.  It needs to supply a
registry to process applications to the club and distribute membership
information to the origin and target sites.  This must include distribution of
the PKI components necessary for trust between origins and targets.  There 
also
needs to be a set of agreements and best practices defined by the club 
governing
the exchange, use, and population of attributes before and after transit, and
there should be a way to find information on local authentication and
authorization practices for club members.


2.  First Steps

    There are several essential elements that must be present in the 
environment
to ensure Shibboleth functions well, both political and technical.  Shibboleth
is primarily written in C++, though Java is used for some portions of the
attribute authority.  These are the recommendations and requirements for a
successful Shibboleth implementation.

    a. Origin

        i.   A common institutional directory service should be operational;
Shibboleth comes with LDAP and MySQL abilities built in, and the attribute
authority has a C++ API which will allow specification of interfaces with 
legacy
directories.  This is discussed further in Chapter 5.

        ii.  A WebISO service should be available to provide authentication
services.  While this is not explicitly necessary for Shibboleth, without a
single-sign on solution of some form, users will have to repeatedly 
authenticate
to the home organization for each new target application domain they wish to
visit.

        iii. A web server must be deployed that can host a Java servlet and 
JSP
apps.

    b. Target

        i.   Currently, Shibboleth is only available as an apache module.  The
target's web servers must be running Apache
v1.3.x.

    c. Join a Club

    While it is not necessary for a target or origin to join a club, doing so
greatly facilitates the implementation of multilateral trust relationships.
Each club will have a different application process.  To join Club Shib, 
please
fill out the application at http://middleware.internet2.edu/foo/ and submit 
this
application to Renee Frost at 
.
  For more information on
Clubs, refer to 1.d or the Shibboleth v1.0 architectural document.

    d. Security Considerations

    Shibboleth's protocols and software have been extensively engineered to
provide protection against many attacks.  However, the most secure protocol 
can
be compromised if it is placed in an insecure environment.  To ensure 
Shibboleth
is as secure as possible, there are several recommended security precautions
which should be in place at local sites.

        i.   SSL should be used for all interactions with client machines to
provide the necessary authentication and encryption to ensure protection from
man-in-the-middle attacks.

        ii.  Many other attacks can be made on the several redirection steps
that Shibboleth takes to complete attribute transfer.  The best protection
against this is safeguarding the WAYF service and ensuring that rogue targets
and origins are not used, generally by development of the trust model 
underneath
Shibboleth.  Shibboleth also leverages DNS for security, which is not 
uncommon,
but attacks concerning bad domain information should be considered.

        iii. The identification and authentication of both origin users and
target applications should be carefully performed to ensure that all requests
the SHAR performs and all information the origin provides is accurate.  Proper
security measures should also be in place on directory access and 
population(see
Access Control in the LDAP recipe for more information).  Use of plaintext
passwords is advised against.

        iv.  Server platforms should be properly secured, and cookie stores on
client machines should be well protected.

    e. Server Certs

    In the Shibboleth architecture, the SHIRE, SHAR, HS, and AA must all have
server certificates for use in signing assertions and creating SSL channels.
These should be issued by a commonly accepted CA, which may be stipulated by
some Club rules.

    f.   Designate an administrative contact

    The contact will give other sites a business entry point to discuss 
matters
related to interoperation.  This contact address should be given to any Clubs 
of
which the organization is a member.

    g.   Browser Requirements

    A primary Shibboleth design consideration was to require very little or no
modification to client machines.  The only requirement is that a browser is 
used
which supports redirection and SSL.  Browser users will have to perform an
additional click to submit the attribute assertion if Javascript is not
functional.

    h.   Clocks

    NTP should be run on all web servers, as with Shibboleth's short handle
issuance time to protect against replay attacks, any degree of clock skew can
hinder the ability of users to access sites successfully.

    i.   Other Considerations

    Especially in higher education, there is a handful of laws enacted which 
may
have important ramifications on the disclosure of personal information and
attributes.  Since Shibboleth does not necessarily need to transmit identity, 
it
is an ideal solution for many higher education situations.  Nevertheless, all
parties are strongly advised to consult the Family Educational Rights and
Privacy Act of 1974(FERPA), and all other relevant state and federal 
legislation
before deploying Shibboleth.

3.  Installation

    a. Origin

    There are two primary components to be deployed at the origin site.  This
guide will assume that Apache, a WebISO server, Ant, Tomcat 3.x, and an
enterprise directory are already functional.  Tomcat, along with build
instructions, is located at http://jakarta.apache.org/tomcat/, and the
University of Washington's open-source WebISO project Pubcookie is available 
at
http://www.washington.edu/computing/pubcookie/.

    This guide also assumes that default folders(/usr/local/shib/,
/usr/local/tomcat/, /var/tomcat3/, and /usr/local/apache/) are used for
simplicity, but the folders in your implementation, if different, should be
substituted.

        i.   Deploy HS and AA

1. The archive will expand into a shib/ directory(/usr/local/ recommended).
2. Configure /usr/local/shib/src/build.xml to determine how the build is
performed, including the destination folder for shibb.war, which defaults to
/var/tomcat3/webapps/.
3. Run /usr/local/ant/bin/ant in /usr/local/shib/src/.  This will build the
shibb.war file which is placed in the destination directory set in build.xml 
and
compile the Java class files into /usr/local/shib/src/build/.
4. Reboot Tomcat, which will automatically detect that there has been a new 
.war
file added.  This file will by default be expanded into
/var/tomcat3/webapps/shibb.
5. Run the following command to move the Java files into Tomcat's tree:

        cp /usr/local/shib/lib/*.jar /var/tomcat3/lib/apps/

5.  A section must be added to /etc/httpd/conf/mod_jk.conf for Shibboleth.

        ii.  Implement a MySQL directory

1. A MySQL database needs to be implemented along with a JDBC driver for use 
by
the AA.  One available driver is MM.MySQL(http://mmmysql.sourceforge.net/).
The driver selected should be unpacked and the .jar file should be moved to
/var/tomcat3/lib/apps/.
2. Using /usr/local/shib/src/shibdump.sql, a MySQL(http://www.mysql.com)
database must be created.  Copy this file where desired, and as admin, run
"mysql < shibdump.sql"; this may be done locally or on another machine.
3. The default access for Shibboleth to the database is shib/shib.  This can 
and
should be changed if possible for security purposes in both the database
itself and Shibboleth's configuration file.

    b. Target

        i.  The following software must be present:

1. OpenSSL 0.9.6+(available from http://www.openssl.org/source/)
2. Apache 1.3.x(available from http://www.apache.org/dist/httpd/).  Apache 
must
be compiled with mod_so for DSO module support, and must include SSL
support(preferably using mod_ssl).  Shibboleth is compatible with mod_auth,
which may be compiled into the server for use elsewhere, but Shibboleth does 
not
need it.
3. Java 1.3.1(JDK recommended, but JRE-only should work)
4. Tomcat 3.3.1 Java server(http://jakarta.apache.org/tomcat/).  Build mod_jk
against Apache, which will generally require GCC.

        ii. Install the Shibboleth files:

1. The archive will expand into a shib/ directory(/usr/local/ recommended).
2. Run the following commands to move the Java files into Tomcat's tree:

        cp /usr/local/shib/lib/*.jar /usr/local/tomcat/lib/apps/
        cp /usr/local/shib/lib/*.war /usr/local/tomcat/webapps/

        iii. Configure Tomcat

1. Modify /conf/server.xml as follows:

     Add address="127.0.0.1" inside the <Ajp12Connector> and <Ajp13Connector>
configuration elements
     Add tomcatAuthentication="false" to the <Ajp13Connector> configuration
element

        iv.  Configure Apache

1. A bare-bones mod_jk configuration will activate the needed servlet:

        --------- begin ---------
        <IfModule !mod_jk.c>
          LoadModule jk_module libexec/mod_jk.so
        </IfModule>

        JkWorkersFile "/usr/local/tomcat/conf/jk/workers.properties"
        JkLogFile "/usr/local/apache/logs/mod_jk.log"

        JkLogLevel emerg

        JkMount /shibdest ajp13
        JkMount /shibdest/* ajp13
        --------- end ---------

2. Add the Shibboleth module and global configuration to httpd.conf:

        --------- begin ---------
        LoadModule shibb_module /usr/local/shib/lib/mod_shibb.so
        ShibSchemaPath /usr/local/shib/conf/
        ShibCookieName ShireSessionId
        SHIRELocation https://<server_name>/shibdest/servlet/ShireServlet
        SHIRESessionPath /tmp/shiresessions
        WAYFFormPath /usr/local/shib/conf/wayf.html
        WAYFMapPath /usr/local/shib/conf/wayf.map

        <Location /wayf.form>
        AuthType shibauth
        require valid-user
        </Location>
        --------- end ---------

3. Tell Apache where libraries are by adding to its startup script:

       LD_LIBRARY_PATH=/usr/local/shib/lib; export LD_LIBRARY_PATH

Apache content will then need to be modified for Shibboleth authentication.
This is discussed in 4.b.i.

4.  Getting Running

    a. Origin

        i.   Basic Configuration

   The main configuration file for Shibboleth's origin side, web.xml, will be
located in /var/tomcat3/webapps/shibb/web-inf/.  This file allows for
configuration of the AA and HS.  The following options may be configured:

domain = <domain name>
    Specifies the domain in which the AA and HS are located, e.g. 
internet2.edu

issuer = <domain name>
    Specifies the machine on which the AA and HS are located, e.g.
    shib.internet2.edu

ticket = <milliseconds>
    Specifies the duration for which an issued attribute assertion should be
    valid; defaults to "1400000".  Refer to your club guidelines for advice in
    populating this field.

AAurl = <url>
    Defines the URL where the AA runs, such as
    "https://shib.internet2.edu/shibb/servlet/AAServlet";.

DBdriver = <driver name>
    This is the name of the driver that the AA should use in queries to the
    MySQL database.  For MM.MySQL, this should be "org.gjt.mm.mysql.Driver".

DBuser = <login>
    This is the username used to login to the MySQL database, and must be
    consistent with one defined in the database.

DBpass = <password>
    This is the password used to login to the MySQL database, and must be
    consistent with one defined in the database.

DBdomain = <domain>
    Specifies the domain of the MySQL server.  If the MySQL server is located 
on
    the same server as the AA and HS, this should be "localhost".

Included with the Shibboleth distribution is a simple application that can be
used to test the function of any AA.  The URL of
the AA must be supplied and must be consistent with the specified AAurl.

        ii.   Deploy AA plug-ins for attributes(C++ API)
        iii.  Establish default ARP's for community
        iv.   MyAA
        v.    WAYF

    b. Target

                i.   Protecting Webpages

        Any of the typical ways of identifying content may be used(.htaccess,
Directory, Location, Files, etc.).  There are two ways to trigger Shibboleth
authentication: by specifying an AuthType of shibboleth to use Shibboleth
directly, or specifying ShibBasicHijack on to process existing .htaccess files
using Shibboleth instead.  Alpha support for authorization consists of
mod_auth-style require directives, as well as support for mod_auth group 
files.
A complete list of the options is below:


AuthType <string>
    Use shibauth for direct invocation, or Basic plus the Hijack option
    described below.

ShibSSLOnly <yes/no>
    Controls whether Shibboleth will reject non-SSL requests from clients.

ShibBasicHijack <yes/no>
    Controls whether Shibboleth should or should not ignore requests for which
    AuthType is set to Basic.

ShibCheckAddress <yes/no>
    Controls whether to check client addresses for impersonation protection.

AuthGroupFile <pathname>
    Same as mod_auth; collects EPPN's into a named group for access control

Require
    Enforce authorization using one of the following variants:

        valid-user
            Any EPPN value is acceptable

        user
            A space-delimited list of EPPN values

        group
            A space-delimited list of group names defined with AuthGroupFile
files


        ii.  Design AAP's
             A. Algebratize Business Rules
             B. Understand who can administer AAP's
        iii. Add SHAR plug-ins for attribute processing(Java API)
        iv. Club Shib Registry Files

5.  Advanced Configuration

    a. Origin
        i.   ARP Syntax
    b. Target
        i.   Caching
        ii.  Application Domains
        iii. AAP Syntax
    c. Use of Shibboleth for other apps
    d. Shibboleth's use of cookies
    e. Non-standard attributes
    f. Client Certs

6.  More Information

    The alpha version of Shibboleth has many limitations and lacks certain
security provisions which will be present in the full beta.  It is strongly
advised that the alpha not be used to protect any sensitive data.


------------------------------------------------------mace-shib-design-+
For list utilities, archives, subscribe, unsubscribe, etc. please visit the
ListProc web interface at 

    http://archives.internet2.edu/

------------------------------------------------------mace-shib-design--