Shibboleth Developers

[(Nate Klingenstein)]

All,

I want to thank you for all the textual and other contributions you've made
to date.  Anything more that should be added or can be sent along, I'd
encourage you to do so and it will be quickly incorporated.


Shibboleth Deployment Guide

draft-internet2-mace-shibboleth-shib-deploy-01.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 means to request 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 degree
of 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 somehow 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 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 Java 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 a
fair deal of 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 tenet 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/.  The guide
also assumes that the Shibboleth tarball has already been cp'ed to the
proper directory and unpacked.

    All source files for both the HS and the AA should be located in
/usr/local/shib/src/.  This guide assumes that default folders are used for
simplicity, but the folders in your implementation, if different, should be
substituted.

        i.   Deploy HS and AA

1.  /usr/local/shib/src/ should contain build.xml.  Configuration options
here can determine how the build is performed, including the destination
folder for shibb.war, which defaults to /var/tomcat3/webapps/.
2.  Run /usr/local/ant/bin/ant in /usr/local/shib/src/.  This will utilize
the build.xml file in /usr/local/shib/src/ to build a 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/.
3.  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.
4.  Copy from /usr/local/shib/lib/ to /var/tomcat3/lib/apps/ the files
shibboleth.jar, xercesImpl.jar, and xmlParserAPIs.jar.
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 be and should be changed if possible for security purposes as part of
the database itself, and can be easily changed in Shibboleth's
configuration file.

    b. Target
        i.   Deploy SHIRE and SHAR
        ii.  Implement Resource Manager

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 help 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
        iii.  Establish default ARP's for community
        iv.   MyAA
        v.    WAYF
    b. Target
        i.   Design AAP's
             A. Algebratize Business Rules
             B. Understand who can administer AAP's
        ii.  Add SHAR plug-ins for attribute processing(C++ API)
        iii. 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--