Shibboleth Developers

[Nate Klingenstein <>]

All,

I'd like to make this the "frozen" guide for Alpha 2.  I've waited 
awhile for comments and I think I've got all the (major) bugs out of the 
guide.  All sent comments have been incorporated.  If the developers 
want to keep sending me text for 2.5 on the fly, please feel free to do 
so.

Thanks,
Nate.

Shibboleth Deployment Guide

draft-internet2-mace-shibboleth-shib-deploy-12.txt
Nate Klingenstein
10 July, 2002
Comments should be directed to 
.

     The second alpha version of Shibboleth has some 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. Some security features, including authentication of SHARs, and
        support for non-trivial certificate validation processes beyond
        simple CA validation.
     b. Bundling of SSO or WebISO systems
     c. Any support for origin side ARP's.  The AA will ALWAYS send EPPN,
        eduPersonAffiliation, and eduPersonEntitlement, provided LDAP is
        used as an attribute source, or EPPN and member affiliation if it
        isn't.
     d. Any support for customized target side AAP's, except by writing
        an Apache module to implement the desired policy.  As shipped,
        EPPN and eduPersonAffiliation are only accepted from the AA if
        the scope value is equal to the value of "domain" in the origin
        site HS's web.xml file, which will be the same as the name
        provided in registration with Club Shib.
     e. Club Shib is only a rudimentary concept at this time, and no
        support for multiple clubs or club policies is provided.
        Registration with the Shibboleth project management team is
        required to interoperate with other test sites, unless peer to
        peer sharing of certificate information is undertaken.  For more
        information about acquiring certificates accepted by Club Shib,
        please refer to section 2.e.

Please send any questions, concerns, or eventual confusion to
.
  This should include, but not be limited to,
questions about the documentation, undocumented problems, installation
or operational issues, and anything else that arises.  The .tarball can
be found at http://shib1.internet2.edu:8000/shib/.  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 (optional)

     b.   Target

         i.   Software Requirements
         ii.  Deploy SHIRE and SHAR
         iii. Configure Tomcat
         iv.  Configure Apache

4.  Getting Running

     a.   Origin

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

     b.   Target

         i.   Basic Configuration
         ii.  Key Generation and Certificate Installation
         iii. Protecting Webpages
         iv.  Designing AAP's
              A. Boolean Business Rules
         v.   Using Attributes in Applications
         vi.  Add SHAR plug-ins for attribute processing (Apache modules)

     c. Testing Components

5.  Advanced Configuration

     a. Origin
         i.   ARP Syntax

     b. Target
         i.   Caching
         ii.  Application Domains
         iii. AAP Syntax

     c. WAYF Deployment
         i.   Basic Deployment & Configuration
              A. Caching
              B. Display
              C. Searching

     d. Use of Shibboleth for other apps
     e. Shibboleth's use of cookies
     f. Non-standard attributes
     g. Client Certs

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 patent claim by RSA Security Inc. on use of OASIS' SAML protocols
which are utilized by Shibboleth; details of this claim may be found at
http://www.oasis-open.org/committees/security/rsa-ipr-statement.shtml.
At this point, RSA has not made available any process for obtaining
a license from them.  Once RSA makes a process available, implementing
parties are advised to assess the validity of the claim, and proceed
accordingly.  Shibboleth is being made available on a temporary basis
until further developments occur.

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 browser user.  The user may have the ability
to decide whether to release specific attributes to certain sites by
specifying personal attribute release policies (ARP's), effectively
preserving privacy while still granting access based on trusted
information.
     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 authentication 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.  The SHAR
performs some basic validation and analysis based on attribute acceptance
policies (AAP's).  These attributes are then handed off to the RM, which
is responsible for using these attributes to decide whether to grant
access.

     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 on the origin side
and in C++ on the target side, though Java is currently used for a
portion of the SHIRE.  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.  Implementation
              details of this are discussed in

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

     b. Target

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

     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 for the alpha2 test period, please submit a basic
application containing the following information to

 with the subject "Shib Origin Site
Application":

    i.   Domain Name of the origin site(e.g., Ohio State's is "osu.edu")
    ii.  Complete URL to access the HS
    iii. The CN(common name) of the HS's certificate's subject
    iv.  Any shorthand aliases the WAYF should support for the origin 
site
         (e.g., Ohio State, OSU, Buckeyes)

To interoperate with other sites in Club Shib, the HS will need to
have a private key and associated certificate generated.  When
generating the key, a distinguished name must be assigned to the key
that will contain a CN attribute.  Often, this will be the hostname of
your Handle Service, particularly if the same key-pair and certificate
will be used for SSL as well.  While any name may be assigned that is
acceptible to the signer of your certificate, using the hostname is
strongly encouraged.

If, for some reason, the HS's URL is not yet known, but its hostname and
CN have been determined, the URL (item ii) may be supplied later.  In
the meantime, the WAYF will be unable to direct users to that HS, but
any assertions from the site will still be accepted by club SHIRE's.

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 various client and/or 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.  For
the Shibboleth Alpha 2 testing, the following CA's will be recognized by
Club Shib:

Verisign/RSA Secure Server CA (http://www.verisign.com/)
Thawte Server CA (http://www.thawte.com)
Thawte Premium Server CA (http://www.thawte.com)
Thawte Test CA (http://www.thawte.com)
Microsoft Test CA (http://sectest.rte.microsoft.com/)
CREN CA (http://www.cren.net/crenca/institutionalcerts/index.html)
CREN Web Server CA(http://www.cren.net/crenca/webservercerts/index.html)
EuroPKI CA (http://www.europki.org/ca/root/)

The following CA's are only test CA's and have certificates which will
expire relatively soon, causing the expiration of their issued
certificates transitively:

SURFnet CA

Additionally, http://bossie.doit.wisc.edu/cert/i2server, a rudimentary CA
intended for testing purposes operated by the University of Wisconsin, is
provided.

     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 authentication
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 are 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 web server, Ant, Tomcat 3.3.1, 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.
     The origin can be built using a MySQL database to store handles or
an in-memory method to store handles.  Additionally, it's possible to
define alternate storage methods using the API.

         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/java/shibboleth.war 
/usr/local/tomcat/webapps/

3. Restart 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/shibboleth.

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

5. Modify Tomcat's /conf/server.xml as follows:

      Add address="127.0.0.1" inside the <Ajp12Connector> and
      <Ajp13Connector> configuration elements to prevent off-host access.

      Add tomcatAuthentication="false" to the <Ajp13Connector>
      configuration element to ensure that the user's identity is passed
      from Apache to the servlet environment.

         ii.  Implement a MySQL directory (optional)

1. A MySQL database needs to be implemented along with a JDBC driver for
use by the HS.  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/etc/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 for security purposes in both the database
itself and Shibboleth's configuration file.

     b. Target

         i.   Software Requirements

1. OpenSSL 0.9.6+(available from http://www.openssl.org/source/)

2. Apache 1.3.26+(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), and EAPI support (which
mod_ssl requires and provides).  Shibboleth can coexist with mod_auth,
which may be compiled or loaded into the server for use elsewhere, but
Shibboleth does not need or use it.

3. Java JDK 1.3.1 (The JRE by itself should work in many cases, but the
WAYF uses JSP pages, which require a JDK be present.)

4. Tomcat 3.3.1 Java server(http://jakarta.apache.org/tomcat/).  You may
need to build mod_jk against Apache, which will generally require GCC,
or a platform-specific C compiler.

         ii.  Deploy SHIRE and SHAR

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/java/shibboleth.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 to prevent off-host access.

      Add tomcatAuthentication="false" to the <Ajp13Connector>
      configuration element to ensure that the user's identity is passed
      from Apache to the servlet environment if the user releases
      identity to this target.

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

2. Add the Shibboleth and eduPerson attribute modules and global
configuration to httpd.conf:

         --------- begin ---------
         # Load modules
         LoadModule eduPerson_module /usr/local/shib/lib/mod_eduPerson.so
         LoadModule shib_module /usr/local/shib/lib/mod_shib.so

         # Configure mod_shib with various runtime information
         ShibSchemaPath /usr/local/shib/etc/

         # Set this to the session cookie name you choose.
         # Whatever you choose must be the same here and in web.xml
         ShibCookieName cookie-name

         # Set this to a directory where small session files will be 
created
         # by the SHIRE servlet to pass information into the module.
         # You may purge this directory based on your session expiration 
time.
         SHIRESessionPath /tmp/shiresessions

         # To equip the SHAR with a keypair and client certificate, use
         # these directives to identify a pair of PEM encoded files, 
and a
         # password, if necessary. Note that the module needs access to 
these
         # files from within the Apache child processes, which generally 
runs
         # as something other than root, and may not have access to the
         # key-pair used by mod_ssl without permission changes. The 
issues
         # surrounding how to securely obtain a key while running as 
"nobody"
         # will be addressed in a later release.
         ShibSSLCertFile /usr/local//apache/conf/ssl.crt/server.crt
         ShibSSLKeyFile /usr/local//apache/ssl.key/server.key
         ShibSSLKeyPass <password>

         # If you want to validate the signer of any SSL certificates 
the SHAR
         # encounters while talking to AAs, place any acceptable CA 
roots in a
         # single file of PEM-encoded certificates, as with mod_ssl.
         ShibSSLCAList /usr/local/apache/conf/ssl.crt/ca-bundle.crt

         # Set this to the location of your SHIRE servlet. Most of the 
time,
         # this should be a path only, so that the schema, host, and 
port will
         # determined dynamically in each virtual host.
         # If for some reason the dynamically derived URL is not 
appropriate, a
         # complete URL can be used, and may be set per-vhost explicitly:
         # SHIRELocation https://<server-name>/shibboleth/SHIRE
         SHIRELocation /shibboleth/SHIRE

         # Set this to the location of a WAYF service, remote or local.
         # If your server will be serving a single origin site of users,
         # you may choose to point this at an actual handle service.
         # This can be set per-vhost, to allow each vhost to service a
         # specific community of users.  HTTPS can be used as well.
         # WAYFLocation 
https://shib1.internet2.edu:8443/shibboleth-target/WAYF
         WAYFLocation http://shib1.internet2.edu:8000/shibboleth-
target/WAYF

         # Register attributes you wish to recognize and map them to an
         # authorization "alias" for use with require directives.
         # REMOTE_USER is a special case, suggested for use with EPPN,
         # and is automatically checked by a "require user" rule.
         # The parameter syntax is <attribute-uri> <HTTP-header> 
[<alias>]
         ShibMapAttribute urn:mace:eduPerson:1.0:eduPersonPrincipalName \
                 REMOTE_USER
         ShibMapAttribute urn:mace:eduPerson:1.0:eduPersonAffiliation \
                 Shib-EP-Affiliation affiliation
         ShibMapAttribute 
urn:mace:eduPerson:1.0:eduPersonPrimaryAffiliation \
                 Shib-EP-PrimaryAffiliation primary-affiliation
         ShibMapAttribute urn:mace:eduPerson:1.0:eduPersonEntitlement \
                 Shib-EP-Entitlement entitlement
         --------- 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.ii.

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/shibboleth/WEB-INF/.
This file contains configuration information for the origin side in
several sections.  The first is a set of options that must be defined
outside the servlet configuration, followed by configuration
information for the HS and the AA.  Some values specified must be
consistent with values in the HS's certificate, and other values must be
consistent with those configured into the directory for proper access.
These are the variables that may be specified for each component:


repository = <type>
     This option must be specified outside the servlet description, and
     specifies the method used to store handles.  The two currently
     valid values are "SQL" and "MEMORY".

MySQL(optional):

These values must be populated outside the servlet description if
repository = SQL.

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.

HS:

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

HSname = <domain name>
     Specifies the machine on which the HS is 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/shibboleth/AA";.

KSpath = <pathname>
     Defines the pathname to the JKS keystore that is used by the HS.
     The effective root of this path is
     /usr/local/tomcat/webapps/shibboleth and the keystore should
     usually be placed in the WEB-INF/conf directory (Defaults to
     /WEB-INF/conf/keystore.jks)

KSpass = <password>
     Specifies the password used to access the JKS keystore.

KSkeyalias = <alias>
     Specifies the alias used to access the HS's private key entry
     within the keystore.

KSkeypass = <password>
     Specifies the password used to access the HS's private key entry
     within the keystore.

certalias = <alias>
     This is the alias used to access the certificate associated with the
     key used by the HS within the keystore.  Should be identical to
     KSkeyalias.

AA:

domain = <domain name>
     Specifies the domain in which the AA is located, e.g.
     internet2.edu.  This is the default scope for attributes.

arpFactoryMethod = <method>
     This will eventually allow for the selection of how ARP's are
     stored, supporting SQL databases and LDAP repositories
     eventually.  Currently, "file" is the only method supported.

ctxFactoryClass = <parameter>
     This optional parameter allows sites to override how AA will 
populate
     attribute assertions.  This is only needed if LDAP is not used.
      An echo setting is provided with the parameter
     "edu.internet2.middleware.shibboleth.aaLocal.EchoCtxFactory" for
     example and testing, which will automatically return
     eduPersonAffiliation with the fixed value of "member" and
     eduPersonPrincipalName populated with the UID used to login the user
     in question.

LDAP(optional):

These values must be provided if LDAP is used
(e.g. ctxFactoryClass not stated).

dirUrl = <LDAP URL>
     This is the URL of the LDAP directory used to store attributes,
     containing the LDAP hostname and search base.  An example query URL
     would be "ldap://shib2.internet2.edu/ou=People,dc=internet2,dc=edu";

ldapUserDnPhrase = <DC>
     This is the prefix for the last part of the DN; e.g., "uid=".  The
     user's ID is dynamically appended to this value to create the user's
     complete DN.

        ii.  Key Generation and Certificate Installation

        The SAML messages generated by the HS must be digitally signed,
so each HS must be issued a private and public keypair, which is stored
in a Java keystore.  The current implementation of Shibboleth requires
the use of an ordinary file-based keystore.  The keytool program is
included with the Java development and runtime kits.  These values will
need to be consistent with those given in web.xml.

A sample keystore that can be used is included in the distribution and
can be found in
/usr/local/tomcat/webapps/shibboleth/WEB-INF/conf/keystore.jks with a
password of "shibhs".

The following commands will generate a new RSA keypair and store it in
the keystore.jks file, with a keyentry alias of "hs" and new passwords
of your choosing:

$ cd /usr/local/tomcat/webapps/shibboleth/WEB-INF/conf
$ keytool –storepasswd –keystore keystore.jks –new <newpassword>
$ keytool –genkey –keystore keystore.jks –alias hs –keyalg rsa –keysize
2048

You will be prompted for passwords during key generation as needed, to
access the keystore and assign the key itself its own password.  You will
also be prompted for the distinguished name components to associate with
the key.  This DN will be placed in a self-signed certificate and will be
the name that is associated with your HS by Shibboleth.  In particular,
the first component you enter for Name will be the Common Name (when
keytool asks for first and last name, common name is intended), which in
most cases should be the hostname of the HS system.  Note that the
specific club of sites may dictate what type of key algorithm, key size,
or validity period is appropriate.

Once you have a keypair generated, the self-signed certificate must be
replaced with a certificate signed by a CA known to be acceptable to the
club of sites that you are joining. Currently, the certificate must be
signed directly by a CA trusted by the target sites your users will
access. An intermediate CA with a certificate chain will only work if a
target site has installed the intermediate CA as a trusted root. This
restriction may be relaxed in subsequent releases.

To generate a certificate signing request for a CA, use the following
command:

$ keytool –certreq –keystore keystore.jks –alias hs –file <csr-file>

The contents of <csr-file> can then be sent to a CA for signing. You
will receive a signed certificate in return in a file. To install the
new certificate into your keystore, use the following command:

$ keytool –import –keystore keystore.jks –alias hs –file <cert-file>

Note that if the signing CA's certificate is not already installed in
your keystore as a trusted signer, you may need to download the CA's
root certificate and import it into the keystore file under a different
alias, using a command similar to this.

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.

         iii. 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 /shibboleth/HS>
AuthType Basic
AuthName "Internet2 Handle Service"
AuthUserFile /usr/local/apache/conf/user.db
require valid-user
</Location>

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

         iv.  Deploying AA plug-ins for attributes(Java API)
         v.   Establishing default ARP's for community
         vi.  MyAA

     b. Target

        i.   Basic Configuration

        The target configuration data is divided among the Java SHIRE
servlet and the Apache module(s). The servlet's configuration is in
/usr/local/tomcat/webapps/shibboleth/WEB-INF/web.xml, and the Apache
modules are configured in /usr/local/apache/conf/httpd.conf.

The web.xml parameters are as follows:

cookie-name = <cookie-name>
    Specifies the name of the session cookie created by the servlet.
    Must match the ShibCookieName Apache module command.

session-dir = <pathname>
    Specifies the directory in which to create session files for use by 
the
    Apache module.  Must match the ShibSessionPath Apache module command.
    Defaults to /tmp/shiresessions.

ssl-only = <true/false>
    Specifies whether to permit access to the servlet via HTTP without 
SSL.
    Use of SSL is strongly recommended.

check-address = <true/false>
    Specifies whether to require that the client's IP address match the
    client address contained in the handle submission provided by the
    user's HS. Strongly suggested, unless users must use proxies or other
    address-distorting equipment.

verbose = <true/false>
    Specifies how much information to display with errors.

registry-uri = <uri>
    Specifies where to obtain the registry of origin site data to 
validate
    incoming sign-on requests by users.  The URI can be a network 
location
    or a local file (using file:/// absolute path syntax).  The file will
    be read in at initialization time.  Tomcat must be restarted (or the
    shibboleth webapp must be caused to reinitialize) to refresh the list
    of sites.  For alpha 2 purposes, should be
    "http://shib1.internet2.edu:8000/shibboleth-target/sites.xml";.

keystore-path = <pathname>
    Specifies the Java keystore file containing the CA roots to permit
    while validating submitted handles. Only users from origin sites 
whose
    HS certificate is signed by one of these root CAs will be able to
    sign on to this target. The effective root of this path is
    /usr/local/tomcat/webapps/shibboleth and the keystore should
    usually be placed in the WEB-INF/conf directory
    (eg. /WEB-INF/conf/roots.jks)

keystore-alias = <alias>
    The registry file specified earlier is a signed XML document.  The
    SHIRE can be configured to optionally verify the signature on this
    document to ensure that it has not been tampered with.  This 
parameter
    specifies a trusted certificate entry in the root keystore specified
    above that is used to verify the signature on the file.  Should be
    "internet2" for alpha 2 purposes.

keystore-password = <password>
    Specifies the password to the root keystore specified above.  Should
    be "shibboleth" for alpha 2 purposes.

The global and per-server Apache module configuration commands are
outlined in section 3.b.iv.2. As discussed earlier, some of the web.xml
settings must match some of the Apache commands. These form the points
of integration between the Java and C++ portions of the target
implementation.

Also note that the eduPerson module must be loaded *before* the shib
module, and both LoadModule commands must appear before any of the
subsequent module commands in the conf file. Any other custom attribute
modules must also be loaded prior to the shib module.

        ii.  Key Generation and Certificate Installation

        The only target component that must have a private key and
certificate is the SHAR, which is implemented within the Apache module.
While the target server itself should support SSL in most cases, it is
mandatory for the SHAR to authenticate when contacting an AA, and it
must therefore be given a key and an SSL client certificate.  It is
permissible for the SHAR to use the same keypair and certificate used by
the target server itself, provided the certificate is signed by a CA
accepted by the community of sites.  In this case, it doubles as both an
SSL server and an SSL client certificate.

The SHAR is assigned a key and a certificate using the Apache module
commands ShibSSLKeyFile, ShibSSLCertFile and ShibSSLKeyPass, described
earlier.  These files must currently be in PEM format. OpenSSL commands
to generate a new keypair and a certificate request are shown here,
assuming RSA keys are to be used:

$ openssl genrsa -des3 -out ssl.key 2048
$ openssl req -new -key ssl.key -out ssl.csr

The signed certificate file returned by the CA should be usable
directly, or can be converted to PEM format using the openssl x509
command.

The key and certificate files can be placed anywhere, though in or
beneath /usr/local/apache/conf directory is a good choice.  The Apache
child processes, often running as "nobody", must be able to read them
while the server is running, which may require permission changes.

This particularly applies when sharing the key and certificate used by
mod_ssl, which are only readable by root by default. The password, if
any, must be placed in the conf file, since the module cannot prompt for
it as the initial startup of mod_ssl can.  The issues surrounding how to
securely obtain a key while running as "nobody" will be addressed in a
later release.  Since the password will be stored in clear text in a
frequently examined file, it is suggested to not reuse a password used
elsewhere, or to place the ShibSSLKeyPass directive in a separate file
that is "Included" in the main configuration file, so that its
permissions can be further restricted.

Finally, the ShibSSLCAList command provides the SHAR with a set of CA
roots to trust when validating AA server certificates.  In all cases,
the SHAR verifies that the certificate's CN equals the AA's hostname,
but the CA root bundle restricts the acceptable signers to those
permitted by the SHAR.  The parameter can be omitted to skip such
signer validation.

        iii. 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: 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.

Part of this process also includes "mapping" attributes provided by an
AA to a localized vocabulary for authorization rules. Each attribute can
be mapped, with the ShibMapAttribute command, to an HTTP header name
(where it can subsequently be accessed by applications), and optionally
to an "alias" that can be used in a Require command to search for a
matching value. This mapping command must be in the global server
configuration, while the rest of the commands described here appear in
content-specific configuration or .htaccess files.

A complete list of the options is below:


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

ShibSSLOnly <On/Off>
    Controls whether Shibboleth will reject non-SSL requests from
    clients.  Defaults to off.

ShibBasicHijack <On/Off>
    Controls whether Shibboleth should or should not ignore requests for
    which AuthType is set to Basic.  Defaults to off.

ShibCheckAddress <On/Off>
    Controls whether to check client addresses for impersonation
    protection.  Defaults to off.

ShibExportAssertion <On/Off>
    Controls whether the SAML attribute assertion provided by the AA
    is exported in a base64-encoded HTTP header, Shib-Attributes.
    Defaults to off.

ShibAuthLifetime <seconds>
    Sets the maximum lifetime in seconds that a user session can
    survive.  Omission or zero results in arbitrary session lifetime.

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 Shibboleth user from a trusted origin site is accepted

        user
            A space-delimited list of EPPN values, provided that the
            urn:mace:eduPerson:1.0:eduPersonPrincipalName attribute has
            been mapped to the REMOTE_USER header (as per the earlier
            example configuration commands).

        group
            A space-delimited list of group names defined with
            AuthGroupFile files, again provided that the mapping to
            REMOTE_USER exists.

        <alias>
            An arbitrary rule tag that matches an alias defined in a
            ShibMapAttribute server command. The rule value is a space-
            delimited list of attribute values, whose format depends on
            the attribute in question (e.g. an affiliation rule might
            look like
            "Require affiliation 

 
").


        iv.  Designing AAP's

        Shibboleth allows a user to release a varying set of attributes
to a destination site, and does not impose restrictions on the kinds of
attribute information provided by an AA.  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. Target implementations must also be prepared to
examine the attributes they receive and filter them based on policies
about what information to permit an origin site to assert about its
users.

Future versions may support more complex policy-based attribute
acceptance, but the current implementation imposes a simple AAP that
requires any "scoped" attribute, such as EPPN or affiliation, to be
scoped only to the origin site's domain. In other words, the "osu.edu"
origin site is only permitted to assert an EPPN value of the form
<name>@osu.edu. Subdomains and disjoint domains are not supported by the
supplied attribute plugin, which is implemented by the eduPerson module.

For now, customizing this policy requires that a new module be plugged
in to implement a different set of rules, just as if an entirely new
attribute were to be supported.

             A. Boolean Business Rules

        v.   Using Attributes in Applications

        Apart from the simple RM functionality provided, attribute
information may be made available directly to applications via the
standard practice of creating custom HTTP request headers before passing
control to the application.

The ShibMapAttribute server command controls this interface, and maps a
Shibboleth attribute (identified by an unambiguous URI) to a header
name, such as Shib-EP-Affiliation. Using that example, any values of the
mapped attribute will be placed in that header, delimited by spaces. An
application that uses a CGI-like syntax to access the header will find
the values in the HTTP_SHIB_EP_AFFILIATION variable. Using the command,
any attribute can be placed in any header, to drive legacy applications
that expect information in a particular header.

The REMOTE_USER variable is a special case that is generally populated
automatically by the web server based on an internal piece of data that
represents the user's "username". Unlike many authentication modules,
Shibboleth does not guarantee that REMOTE_USER will have any value. If
it does, it is set solely based on a ShibMapAttribute command. For most
purposes, the urn:mace:eduPerson:1.0:eduPersonPrincipalName attribute
should be mapped to REMOTE_USER. Even so, EPPN may not be provided by
the AA, and REMOTE_USER might still be empty.

Finally, the ShibExportAssertion flag instructs the module to place the
entire XML message containing the SAML attribute information from the AA
into a base64-encoded header called Shib-Attributes. This is a raw
interface that provides an application with the entire AA response, and
is not a filtered view based on any attribute acceptance rules or even
based on what attributes are recognized by the target. What was sent is
what you see.

        vi.  Add SHAR plug-ins (Apache modules) for attribute processing

        In order for an attribute to be used by the built-in RM, it must
be recognized as valid by the SHAR and implemented with any specific
rules for how to understand and express its value based on the XML from
the AA. The eduPerson module is an example of a plugin that provides
this support for an initial set of eduPerson-based attributes.

Once the Shibboleth source code is made available, the eduPerson module
will provide a simple example of how to build such a plugin for other
attributes. It is a largely empty Apache module that implements the
child_init and child_exit module hooks with calls into the Shibboleth
C++ API to register the attributes it supports.

     c. Testing Components

5.  Advanced Configuration

     a. Origin
         i.   ARP Syntax
     b. Target
         i.   Caching
         ii.  Application Domains
         iii. AAP Syntax

     c. WAYF Deployment

         i.   Basic Deployment & Configuration

         For Alpha 2, Internet2 will host a centralized WAYF service for
Club Shib.  Sites that need to run customized WAYF services should
construct a registry file reflecting the origin sites appropriate to
their needs.  This registry file must conform to the schema that is
distributed with the WAYF service
("/WEB-INF/classes/schemas/shibboleth.xsd" in the expanded web
application).

The WAYF service is configured using two XML files.  One must contain a
registry of origin site data, and other defines runtime configuration
options.  The location of these files can be passed to the WAYF program
via init parameters in the web applications web.xml file.  The
"SiteConfigFileLocation" parameter specifies the location relative to
the web application root at which the origin registry file resides.  The
"WAYFConfigFileLocation" parameter specifies the location of the runtime
configuration file relative to the web application root.  These
parameters are both optional, and, if not passed, will default to
"/WEB-INF/conf/sites.xml" and "/WEB-INF/conf/wayfconfig.xml",
respectively.

The WAYF runtime configuration file specifies cache configuration,
display customization, and search preferences.  Most configuration
options have reasonable defaults if not specified.

              A. Caching

The WAYF has the ability to cache selections that users make concerning
which origin site they would like to be associated with.  This allows
subsequent requests to the WAYF to be redirected to the user's Handle
Service without user interaction.  Three caching modes are available:
COOKIES, SESSION, and NONE.  Specifying the "COOKIES" option causes the
WAYF to create a new cookie in which the user's selection is stored.
The "SESSION" option causes the user selection to be tied to servlet
session.  If "NONE" is used, the user will be prompted to select an
origin site upon each request to the WAYF.

<WayfConfig cacheType="COOKIES" cacheExpiration="7500" 
cacheDomain="test.edu" />

              B. Display

Several parameters effect the display of the origin selection page.  It
is possible to configure the displayed text, the displayed image, and
the support contact.  Example:

<WayfConfig 
supportContact="mailto:"
~         logoLocation="images/internet2.gif">
~         <HelpText>Where are you from?</HelpText>
~         <SearchResultEmptyText>Not found, try
again.</SearchResultEmptyText>
</WayfConfig>

              C. Searching

Currently the only customization related searching is the ability to
specify terms that will be excluded from a keyword search of the site
registry.  This is useful for words such as "state" that are common to
many origin site names.  Example:

<WayfConfig>
~   <SearchIgnore>
~      <IgnoreText>State</IgnoreText>
~   </SearchIgnore>
</WayfConfig>

     d. Use of Shibboleth for other apps
     e. Shibboleth's use of cookies
     f. Non-standard attributes
     g. 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--