Shibboleth Developers

[Nate Klingenstein <>]

My huge thanks to all the coders for getting me the information needed 
to release this in a timely fashion.  I hope I've represented it all 
accurately in this document in an easy way to follow.  As always, send 
all corrections and changes to me and I'll continue to revise it as 
quickly as necessary.

Let's get deploying.
Nate.

Shibboleth Deployment Guide

draft-internet2-mace-shibboleth-shib-deploy-08.txt
Nate Klingenstein
2 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. Support for, bundling, and utilization 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 origin Site's domain name.
    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, 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 (optional)

    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.  Key Generation and Certificate Installation
        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

    b.   Target

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

    c.   WAYF
        i.   Basic Configuration
        ii.  Club Shib Registry Files

    d. Testing Components

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

    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 
:

     Domain Name of the origin site(e.g., Ohio State's is "osu.edu")
     Complete URL to access the HS
     The CN(common name) of the HS's certificate's subject
     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.

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, Thawte Server CA, Thawte
Premium Server CA, CREN CA, SURFnet CA, EuroPKI CA, and for testing
purposes, a rudimentary CA operated by the University of Wisconsin at
http://bossie.doit.wisc.edu/cert/i2server.

    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, 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 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/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.   The following software must be present:

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.  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/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,
        # you will need to set this in each virtual host in order to 
ensure
        # that whatever cookie is set by the servlet will be passed back 
in.
        SHIRELocation https://<server-name>/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.
        WAYFLocation http://shib1.internet2.edu:88/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/shibb/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.  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/shibb/servlet/AAServlet";.

KSpath = <pathname>
    Defines the pathname to the JKS keystore that is used by the HS.
    Defaults to /WEB-INF/conf/keystore.jks.

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

KSkeyalias = <alias>
    This is the alias used to access the appropriate key within the
    keystore.

KSkeypass = <password>
    This is the password used to access the referenced key 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.

AA:

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

ctxFactoryClass = <parameter>
    This value defines where the AA will look for attributes to populate
    attribute assertions.  Many different methods will be supported, but
    the default, if not populated, is LDAP.  An "echo" setting is
    provided with the parameter
    "edu.internet2.middleware.shibboleth.aaLocal.EchoCtxFactory" for
    testing, which will automatically return eduPersonAffiliation with
    the fixed values of "member" and eduPersonPrincipalName populated
    with the UID used to login the user in question.

LDAP(optional):

These values must be provided if ctxFactoryClass = LDAP.

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.


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 /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.

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

    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

        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

    c. WAYF

        i.   Basic Configuration
        ii.  Club Shib Registry Files

    d. Testing Components

5.  Advanced Configuration

    a. Origin
        i.   ARP Syntax

        ARP's are defined using a text-based tool.  More information on
the internal mechanics of the AA and precise details on how ARP's are
evaluated can be found at http://icap.andrew.cmu.edu/aa/AA.htm.

    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--