Shibboleth Developers

[(Nate Klingenstein)]

Shibboleth Deployment Guide

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

    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.  Some sections of the deploy guide have not yet been populated
with text.  This document describes additional functionality which will
be present in the beta, but which is not implemented in the alpha,
including but not limited to:

    a. Security features, including certificates and SSL
    b. Support for, bundling, and utilization of SSO or WebISO systems
    c. The support for multiple WAYF's; the alpha WAYF will be included
       as a standard part of the SHIRE package.
    d. Any support for origin side ARP's.  The AA will ALWAYS send:
         i.   
member@domain(specified
 in web.xml, section 4.a.i)
         ii.  EPPN, in the form of 
login_name@domain
    e. Any support for target side AAP's.  Valid assertions will be
       accepted.
    f. The AA cannot currently use an external directory.(section 2.a.1)
    g. There is, as yet, no Club Shib and no support for clubs in the
       implementation.  Registration with the eventual Club Shib will be
       important come the end of the alpha.

Please send any questions, concerns, or eventual confusion to
.
  This should include, but not be limited to,
questions about the documentation, undocumented problems, and anything
else that arises.  Thank you for your help in testing Shibboleth.

Table of Contents

1.  Shibboleth Overview

    a.   Origin
    b.   Target
    c.   WAYF
    d.   Clubs

2.  First Steps

    a.   Origin
    b.   Target
    c.   Join a Club
    d.   Security Considerations
    e.   Server Certs
    f.   Designate an administrative contact
    g.   Browser Requirements
    h.   Clocks
    i.   Other Considerations

3.  Installation

    a.   Origin

        i.   Deploy HS and AA
        ii.  Implement a MySQL directory
        iii. Initial Configuration

    b.   Target

        i.   The following software must be present:
        ii.  Install the Shibboleth files:
        iii. Configure Tomcat
        iv.  Configure Apache

4.  Getting Running

    a.   Origin

        i.   Basic Configuration
        ii.  Linking the Authentication System to the HS
        iii. Deploying AA plug-ins for attributes(Java API)
        iv.  Establishing default ARP's for community
        v.   MyAA
        vi.  WAYF

    b.   Target

        i.   Protecting Webpages
        ii.  Designing AAP's
             A. Boolean Business Rules
        iii. Using Attributes in Applications
        iv.  Add SHAR plug-ins for attribute processing(Java API)
        v.   Club Shib Registry Files

5.      Advanced Configuration

6.      More Information

        Before proceeding with any installation of, implementation of, or
any other use of Shibboleth or its code, read and agree to the usage
terms put forth in the LICENSE file included in the tarballs.  There is
a potential patent claim by RSA Security Inc. on OASIS' SAML protocols,
which are utilized by Shibboleth; the details of this litigation may be
found at
http://www.oasis-open.org/committees/security/rsa-ipr-statement.shtml.
Shibboleth expresses no opinion on this pending litigation to date, but
implementing parties are advised to assess the use of the standard
accordingly.  Further developments should occur by the beta.

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 a
web-browsing individual 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 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 reference to the user, known as a
handle, for the individual and send this to the target site.  The target
site can then use the handle to ask for attributes about this
individual.  Based on these attributes, the target can decide whether or
not to grant access to the resource.  The user may then be allowed to
access the requested materials.
    There are several controls on privacy in Shibboleth, and mechanisms
are provided 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 reference 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 able to
interface with a directory exporting an LDAP interface or a SQL database
containing user attributes, and is designed such that programming
interfaces to other repositories should be readily implemented.
Shibboleth relies on standard web server mechanisms to trigger local
authentication.  A .htaccess file can be easily used to trigger either
the local WebISO system or the web server's own Basic Auth mechanism,
which will likely utilize an enterprise authentication system, such as
Kerberos.
    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 an 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 provides 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 and
abide by a common set of policies and practices.  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 Java, though C++ is used
for some portions of the SHIRE and SHAR.  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 Java API which
             will allow specification of interfaces with legacy
             directories.  This is discussed further in Chapter 5.

        ii.  Some form of a single sign-on service should be available
             to users to provide authentication services.  While not
             explicitly necessary for Shibboleth, without some form of
             an SSO or a WebISO service, users will have to repeatedly
             authenticate to the home organization for each new target
             application domain they wish to visit.  Implementational
             details of this are discussed in section 4.

        iii. A web server must be deployed that can host Java servlets,
             a MySQL database(which may or may not be on the same server
             as the Shibboleth components), and Tomcat.

    b. Target

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

    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 use is optional for both target and origin sites.  Club
             guidelines should be considered when determining whether to
             implement SSL, and, in general, SSL should be used for
             interactions with client machines to provide the necessary
             authentication and encryption to ensure protection from
             man-in-the-middle attacks.  It is strongly suggested that
             all password traffic or similarly sensitive data should be
             SSL-protected.  Assessment of the risk tradeoff against the
             performance degradation should be performed for all
             applications.

        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
             strongly advised against.

        iv.  Server platforms should be properly secured, commensurate
             with the level that would be expected for a campus' other
             security services, 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 significant
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, some form of authentication
triggered by the webserver, 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/ext/.
    This guide also assumes that default folders(/usr/local/shib/,
/usr/local/tomcat/, 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. 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/

3. Reboot Tomcat, which will automatically detect that there has been a
new .war file added.  This file will by default be expanded into
/usr/local/tomcat/webapps/shibb.

4. A section must be added to /etc/httpd/conf/mod_jk.conf for
Shibboleth mapping URL's to the HS and AA:

        --------- 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 /shibb ajp13
        JkMount /shibb/* ajp13
        --------- end ---------

5. Modify Tomcat's /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

        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
/usr/local/tomcat/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; this can be on
the same machine as the AA or HS, or on a different box.  Edit the line
in this file:

GRANT INSERT, SELECT on HandleService to 
shib@localhost
 IDENTIFIED by
'shib';

such that 
shib@localhost
 is replaced by 
user@FQDN,
 which should be the
domain name of the server on which the directory will be run and the
desired username for directory access by Shibboleth.  'shib' should be
changed to the desired password for access.  The username and password
should be altered if possible for security purposes in both the database
itself and Shibboleth's configuration file, but for testing alone, only
"localhost" must be modified.  The DBdomain, DBpass, and DBusername
attributes later configured into the AA and HS must be consistent with
these values.  Localhost is not a valid value.

2.  At shib.dump.sql, as root, run "mysql < shibdump.sql".

        iii. Initial Configuration

    /usr/local/tomcat/webapps/shibb/web-inf/web.xml must be configured
in order to begin properly using Shibboleth.  The variables that must be
completed and suggested values are listed in section 4.a.i.  It is
recommended that the rest of 4.a be reviewed as well.

    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 with
EAPI support, which can be obtained by adding mod_ssl to the Apache
build tree. It should also include SSL support (preferably using
mod_ssl). Shibboleth is also 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 /usr/local/tomcat/webapps/shibb/web-inf/.  The first
half of the file configures the HS; the second half configures the AA.
Both should be completed.  In the case of the database-access
attributes, they must be changed consistently in each section.  The
variables that may be altered for each component follow:

HS:

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 HS 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 location of the MySQL server.  "Localhost" cannot be
    used as a value due to processing by the Tomcat server; even if the
    database is hosted locally, the FQDN must be used.

AA:

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 location of the MySQL server.  "Localhost" cannot be
    used as a value due to processing by the Tomcat server; even if the
    database is hosted locally, the FQDN must be used.

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.  Linking the Authentication System to the HS

        The interaction between the HS and the local authentication system
is basically implemented by protecting the HS servlet with some form of
local authentication that populates REMOTE_USER.  Location blocks can be
added to httpd.conf to specify the location of servlets based on the
URL, which specify the location of specific authentication servlets.
The following example demonstrates one way to specify authentication for
access to the HS:

<Location /shibb/servlet/HandleServlet>
AuthType Basic
AuthName "Internet2 Handle Service"
AuthUserFile /etc/httpd/conf/user.db
require valid-user
</Location>

Note that .htaccess files cannot be used for this purpose because URL's
are "virtualized" by Tomcat.

        iii. Deploying AA plug-ins for attributes(Java API)
        iv.  Establishing default ARP's for community
        v.   MyAA
        vi.  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.  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

        affiliation
             A space-delimited list of scoped affiliation
             values (eg. 
"
 
")

        ii.  Designing AAP's

        Shibboleth allows a user to release a null set of attributes to a
destination site.  As a result, applications should make no assumption
about the presence of specific attributes for their use unless they have
intimate knowledge of the attribute release policies in place.

             A. Boolean Business Rules
        iii. Using Attributes in Applications

        If eduPersonPrincipalName is released by the origin site,
REMOTE_USER will contain its value. If eduPersonAffiliation is released,
values will be contained in HTTP_SHIB_EP_AFFILIATION.  This variable is
comma-delimited if more than one value is received.

        iv.  Add SHAR plug-ins for attribute processing(Java API)
        v.   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



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

    http://archives.internet2.edu/

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