+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+ <head>
+ <meta name="generator" content=
+ "HTML Tidy for Mac OS X (vers 1st January 2002), see www.w3.org">
+
+ <title>Shibboleth Origin Deployment Guide</title>
+ <meta http-equiv="Content-Type" content=
+ "text/html; charset=utf-8">
+ <style type="text/css">
+
+html
+{
+background-color: #FFFFFF;
+color: #000000;
+margin: .5em;
+}
+a:visited
+{
+color: #999999;
+}
+a:link
+{
+color: #990000;
+}
+a:active
+{
+color: #440000;
+}
+dl
+{
+background-color: #DDDDDD;
+background-image: none;
+margin: 5px;
+padding: 0px;
+border-style: solid;
+border-bottom-width: 2px;
+border-top-width: 2px;
+border-left-width: 2px;
+border-right-width: 2px;
+}
+dt
+{
+background-color: #DDDDDD;
+background-image: none;
+margin: 1px;
+padding: 1px;
+}
+dd
+{
+background-color: #DDDDDD;
+background-image: none;
+margin: 0px;
+padding: 1px;
+}
+.attribute
+{
+font-size: 115%;
+font-color: #000000;
+text-align: left;
+background-color: #DDDDDD;
+border: 1px black inset;
+background-image: none;
+margin: 0px;
+padding: 2px;
+}
+.value
+{
+font-color: #000000;
+text-align: left;
+background-color: #EEEEEE;
+background-image: none;
+padding-top: 0em;
+padding-bottom: 0.5em;
+padding-right: 1em;
+padding-left: 5em;
+border-style: solid;
+border-bottom-width: none;
+border-top-width: none;
+border-left-width: 1px;
+border-right-width: 1px;
+}
+.attributeopt
+{
+font-size: 115%;
+font-color: #000000;
+text-align: left;
+background-color: #BCBCEE;
+border: 1px black inset;
+background-image: none;
+margin: 0px;
+padding: 2px;
+}
+.valueopt
+{
+font-color: #000000;
+text-align: left;
+background-color: #DDDDFF;
+background-image: none;
+padding-top: 0em;
+padding-bottom: 0.5em;
+padding-right: 1em;
+padding-left: 5em;
+border-style: solid;
+border-bottom-width: none;
+border-top-width: none;
+border-left-width: 1px;
+border-right-width: 1px;
+}
+.attributelong
+{
+font-size: 85%;
+font-color: #000000;
+text-align: left;
+background-color: #DDDDDD;
+border: 1px black inset;
+background-image: none;
+margin: 0px;
+padding: 2px;
+}
+.attributeoptlong
+{
+font-size: 85%;
+font-color: #000000;
+text-align: left;
+background-color: #BCBCEE;
+border: 1px black inset;
+background-image: none;
+margin: 0px;
+padding: 2px;
+}
+.demo
+{
+background-color: #EEEEEE;
+padding: 3px;
+}
+.fixedwidth
+{
+font-family: monospace;
+font-size: 90%;
+font-color: #121212;
+}
+
+ </style>
+ </head>
+
+ <body link="red" vlink="red" alink="black" bgcolor="white">
+ <center>
+ <h2>Shibboleth Origin Deployment Guide</h2>
+ </center>
+ Shibboleth Origin Deployment Guide<br>
+ draft-internet2-mace-shibboleth-shib-origin-deploy-30.html<br>
+ Nate Klingenstein<br>
+ 12 June, 2003<br>
+ Comments should be directed to <a href=
+ "mailto:ndk@internet2.edu">ndk@internet2.edu</a>.<br>
+
+ <h3>This version of the deploy guide is for Shibboleth v1.0. For
+ documentation related to prior versions of Shibboleth, please
+ consult the appropriate branch in the Shibboleth
+ CVS.</h3>
+
+ <h3>Federations have been abstracted out from the Shibboleth
+ documentation. For further information on using Shibboleth in a
+ federation, refer to the federation guide.</h3>
+
+ <p>Shibboleth v1.0 is stable and secure enough to deploy in
+ production scenarios. While attempts have been made to include all
+ functionality that would represent a break of interoperability with
+ previous versions in v1.0, be aware that future versions of
+ Shibboleth are likely to be developed and may include further
+ implementation of the architectural document, functional
+ enhancements, and user interface improvements.</p>
+
+ <p>Functionality which has been added since the previous
+ version (v0.8) includes:</p>
+
+ <ul>
+ <li>
+ <p>Various improvements to error handling. Origin sites are now
+ able to supply a URL to a federation for users to be referred to
+ when Shibboleth encounters a problem. Targets will be able to
+ utilize this URL in error templates.</p>
+ </li>
+
+ <li>
+ <p>The SHAR may now store its session and attribute cache in a
+ back-end database in addition to the previously available
+ in-memory option. The method by which <span
+ class="fixedwidth">sites.xml</span> is refreshed has been
+ modified to improve robustness.</p>
+ </li>
+
+ <li>
+ <p>Attribute acceptance policies have been greatly enhanced,
+ with filtering of attribute values by sites supported.</p>
+ </li>
+
+ <li>
+ <p>OpenSAML now populates <span
+ class="fixedwidth">AuthType</span> element in the SAML Subject
+ element using a value specified by origin sites using a
+ configuration directive. This value describes the type of
+ authentication mechanism used at the origin site(e.g. Kerberos,
+ PKI, etc.). This value is made available on the target side as
+ another variable that may be used in authorization
+ decisions.</p>
+ </li>
+
+ <li>
+ <p>Origin sites whose HS certificate is not signed by one of a
+ federation's trusted roots are able to provide that federation
+ with the certificate; this cert can now be stored in the sites
+ metadata, and targets will be able to use this certificate to
+ validate the HS' signature.</p>
+ </li>
+
+ <li>
+ <p>The AA implementation has been improved with a powerful
+ attribute resolver. This should greatly simplify the process of
+ configuring the AA to support additional general attributes,
+ while Java classes may still be written for more complex
+ evaluations.</p>
+ </li>
+
+ </ul>
+
+ <p>Before starting, please sign up for all applicable <a href=
+ "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
+ mailing lists</a>. Announcements pertinent to Shibboleth
+ deployments and developments and resources for deployment
+ assistance can be found here.</p>
+
+ <p>Please send any questions, concerns, or eventual confusion
+ to <a href=
+ "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
+ This should include, but not be limited to, questions about the
+ documentation, undocumented problems, installation or
+ operational issues, and anything else that arises. Please
+ ensure that you have the <a href=
+ "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
+ .tarball</a> for your operating system.</p>
+ <br>
+ <hr>
+ <br>
+ <br>
+
+
+ <h3><a name="TOC"></a>Shibboleth Origin -- Table of
+ Contents</h3>
+ <br>
+
+
+ <ol type="1">
+ <li>
+ <h4><a href="#1."><font color="black">Shibboleth
+ Overview</font></a></h4>
+
+ <ol type="a">
+ <li><a href="#1.a."><font color=
+ "black">Origin</font></a></li>
+
+ <li><a href="#1.b."><font color=
+ "black">Target</font></a></li>
+
+ <li><a href="#1.c."><font color=
+ "black">WAYF</font></a></li>
+
+ <li><a href="#1.d."><font color=
+ "black">Federations</font></a></li>
+ </ol>
+ </li>
+
+ <li>
+ <h4><a href="#2."><font color=
+ "black">Planning</font></a></h4>
+
+ <ol type="a">
+ <li><a href="#2.a."><font color=
+ "black">Requirements</font></a></li>
+
+ <li><a href="#2.b."><font color="black">Join a
+ Federation</font></a></li>
+
+ <li><a href="#2.c."><font color="black">Security
+ Considerations</font></a></li>
+
+ <li><a href="#2.d."><font color="black">Server
+ Certs</font></a></li>
+
+ <li><a href="#2.e."><font color="black">Attribute Release
+ Policies</font></a></li>
+
+ <li><a href="#2.f."><font color="black">Designate
+ Contacts</font></a></li>
+
+ <li><a href="#2.g."><font color="black">Browser
+ Requirements</font></a></li>
+
+ <li><a href="#2.h."><font color=
+ "black">Clocks</font></a></li>
+
+ <li><a href="#2.i."><font color="black">Other
+ Considerations</font></a></li>
+ </ol>
+ </li>
+
+ <li>
+ <h4><a href="#3."><font color=
+ "black">Installation</font></a></h4>
+
+ <ol type="a">
+ <li><a href="#3.a."><font color="black">Software
+ Requirements</font></a></li>
+
+ <li><a href="#3.b."><font color="black">Deploy HS and
+ AA</font></a></li>
+
+ </ol>
+ </li>
+
+ <li>
+ <h4><a href="#4."><font color="black">Getting
+ Running</font></a></h4>
+
+ <ol type="a">
+ <li><a href="#4.a."><font color="black">Basic
+ Configuration</font></a></li>
+
+ <li>
+ <a href="#4.b."><font color="black">Key Generation and
+ Certificate Installation</font></a>
+
+ </li>
+
+ <li><a href="#4.c."><font color="black">Linking the
+ Authentication System to the HS</font></a>
+
+ <ol type="i">
+ <li><a href="#4.c.i."><font color="black">Enabling client
+ certificate authentication</font> <font color="#5555EE">(optional)</font></a></li>
+ </ol>
+ </li>
+
+ <li><a href="#4.d."><font color="black">Establishing
+ default ARP's for the origin community</font></a></li>
+
+ <li><a href="#4.e."><font color="black">Modifying the
+ default Attribute Resolver configuration</font></a></li>
+
+ </ol>
+ </li>
+
+ <li>
+ <h4><a href="#5."><font color="black">Advanced
+ Configuration</font></a></h4>
+
+ <ol type="a">
+ <li>
+ <a href="#5.a."><font color="black">ARP
+ Overview</font></a>
+
+ <ol type="i">
+ <li><a href="#5.a.i."><font color="black">ARP
+ Processing</font></a></li>
+
+ <li><a href="#5.a.ii."><font color="black">ARP
+ Syntax</font></a></li>
+ </ol>
+ <li><a href="#5.b."><font color="black">Sharing
+ certificate/key pairs between Apache and Java
+ keystores</font> <font color="#5555EE">(optional)</font></a></li>
+ <li><a href="#5.c."><font color="black">The Attribute Resolver</font></a></li>
+ </ol>
+ </li>
+
+ <li>
+ <h4><a href="#6."><font color=
+ "black">Troubleshooting</font></a></h4>
+
+ <ol type="a">
+ <li><a href="#6.a."><font color="black">Basic
+ Testing</font></a></li>
+
+ <li><a href="#6.b."><font color=
+ "black">Logging</font></a></li>
+
+ <li><a href="#6.c."><font color="black">Common
+ Problems</font></a></li>
+ </ol>
+ </li>
+ </ol>
+ <br>
+ <hr>
+ <br>
+
+
+ <h3><a name="1."></a>1. Shibboleth Overview</h3>
+
+ <p>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 by the resource to help determine
+ whether to grant the user access to the resource. 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.</p>
+
+ <p>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 authentication system. 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.</p>
+
+ <p>There are several controls on privacy in Shibboleth, and
+ mechanisms are provided to allow users to determine exactly
+ which information about them is released. A user's actual
+ identity isn't necessary for many access control decisions, so
+ privacy often is needlessly compromised. Instead, the resource
+ often utilizes other attributes such as faculty member or member
+ of a certain class. While these are commonly determined using
+ the identity of the user, Shibboleth provides a way to mutually
+ refer to the same principal without revealing that principal's
+ identity. Because the user is initially known to the target site
+ only by a randomly generated temporary handle, if sufficient,
+ the target site might know no more about the user than that the
+ user is a member of the origin organization. This handle should
+ never be used to decide whether or not to grant access, and is
+ intended only as a temporary reference for requesting
+ attributes.</p>
+
+ <h4><a name="1.a."></a>1.a. Origin</h4>
+
+ <blockquote>
+ <p>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 Pubcookie can be obtained from
+ www.pubcookie.org; the directory is provided by the origin
+ site. Shibboleth is able to interface with a directory
+ exporting an LDAP interface 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.</p>
+
+ <p>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.</p>
+ </blockquote>
+
+ <h4><a name="1.b."></a>1.b. Target</h4>
+
+ <blockquote>
+ <p>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.</p>
+
+ <p>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.</p>
+ </blockquote>
+
+ <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
+
+ <blockquote>
+ <p>The WAYF service can be either outsourced and operated by
+ a federation 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.</p>
+ </blockquote>
+
+ <h4><a name="1.d."></a>1.d. Federations</h4>
+
+ <blockquote>
+ <p>A Shibboleth federation provides part of the underlying trust
+ required for function of the Shibboleth architecture. A federation
+ 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
+ federation 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.</p>
+
+ <p>A federation can be created in a variety of formats and trust
+ models, but must provide a certain set of services to federation
+ members. It needs to supply a registry to process
+ applications to the federation 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 federation 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 federation
+ members.</p>
+ </blockquote>
+ <br>
+ <br>
+ <br>
+ <hr>
+ <br>
+
+
+ <h3><a name="2."></a>2. Planning</h3>
+
+ <p>There are several essential elements that must be present in
+ the environment to ensure Shibboleth functions well, both
+ political and technical. Shibboleth is entirely written in
+ Java on the origin side. These are the recommendations and
+ requirements for a successful implementation of a Shibboleth
+ origin.</p>
+
+ <h4><a name="2.a."></a>2.a. Requirements</h4>
+
+ <ul>
+ <li>
+ <p>A common institutional directory service should be
+ operational; Shibboleth comes with LDAP capabilities
+ built in, and the Attribute Authority has a Java API which
+ will allow specification of interfaces with legacy
+ directories. This is discussed further in <a href=
+ "#4.d.">section 4.d</a>.</p>
+ </li>
+
+ <li>
+ <p>A method to authenticate browser users must be in place,
+ preferably in the form of an enterprise authentication
+ service. Some form of an SSO or a WebISO service is not
+ explicitly necessary for Shibboleth; however, it is highly
+ recommended. Implementation details of this are discussed in
+ <a href="#4.c.">section 4.c</a>.</p>
+ </li>
+
+ <li>
+ <p>Shibboleth is known to work on Linux and Solaris, but
+ should function on any platform that has a Tomcat
+ implementation.</p>
+ </li>
+
+ <li>
+ <p>It is recommended that a web server must be deployed that
+ can host Java servlets and Tomcat, although not explicitly
+ necessary, as Tomcat can still host an origin without it.</p>
+ </li>
+ </ul>
+
+ <h4><a name="2.b."></a>2.b. Join a Federation</h4>
+
+ <blockquote>
+ <p>While it is not necessary for a target or origin to join a
+ federation, doing so greatly facilitates the implementation of
+ multilateral trust relationships. Each federation will have a
+ different application process. When an origin is accepted into a
+ federation, its information is added to the sites file used by the
+ WAYF and target sites.</p>
+
+ <p><b>It may be necessary to join multiple federations
+ depending on the sites with whom you wish to exchange
+ attributes and the terms under which these interactions will
+ take place. An origin site exists within the context of a
+ single federation, while a single target may accept assertions
+ issued by multiple federations if they are all recognized by
+ the SHAR. If an organization wishes to be a member of
+ multiple federations, it must run a separate origin site for
+ each federation, including a separate AA and HS.</b></p>
+
+ <p>Attribute release and acceptance policies, the use and
+ caching of attributes, and definition of commonly traded
+ attributes are examples of specifications a federation may
+ make. For more information on federations, please refer to
+ the Deployer's Guide to Federations and the Shibboleth v1.0
+ architectural document.</p>
+ </blockquote>
+
+ <h4><a name="2.c."></a>2.c. Security Considerations</h4>
+
+ <blockquote>
+ <p>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.</p>
+
+ <ol type="i">
+ <li>
+ <p>SSL use is optional for origin sites. Federation 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 possible performance degradation
+ should be performed for all applications.</p>
+ </li>
+
+ <li>
+ <p>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.</p>
+ </li>
+
+ <li>
+ <p>Information regarding origin users is generally
+ provided by the authoritative enterprise directory, and
+ the acceptance of requests from target applications can
+ be carefully restricted to ensure that all requests the
+ SHAR performs are authorized and all information the
+ origin provides is accurate. Proper security measures
+ should also be in place on directory access and
+ population(see <a href=
+ "http://www.georgetown.edu/giia/internet2/ldap-recipe/#AccessControl">
+ Access Control</a> in the <a href=
+ "http://www.georgetown.edu/giia/internet2/ldap-recipe/">LDAP
+ recipe</a> for more information). Use of plaintext
+ passwords is strongly advised against.</p>
+ </li>
+
+ <li>
+ <p>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.</p>
+ </li>
+ </ol>
+ </blockquote>
+
+ <h4><a name="2.d."></a>2.d. Server Certs</h4>
+
+ <blockquote>
+ <p>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
+ Federation rules. Different federations may require the use of
+ different CA's.</p>
+ </blockquote>
+
+ <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
+
+ <blockquote>
+ <p>The Attribute Authority maintains a set of policies called
+ Attribute Release Policies (or ARP's) that govern the sharing
+ of user attributes with Shibboleth target sites. When a user
+ attempts to access a Shibboleth-protected resource, that
+ resource's SHAR queries the user's AA for all attributes to
+ which it is entitled. The SHAR provides its own name and the
+ URL of the resource on behalf of which it is making the
+ request. The AA finds the attributes associated with the
+ browser user, determines an "Effective ARP" for this user, and
+ then sends to the SHAR only the attributes/values allowed in
+ this policy.</p>
+
+ <p>An ARP may be thought of as a sort of filter for outbound
+ attributes; it cannot create attributes or data that aren't
+ originally present, but it can limit the attributes released
+ and the values those attributes may have when released. It
+ does not change the information in the data sources in any
+ way.</p>
+
+ <p>Each ARP is comprised of one or more rules that specify
+ which attributes and values may be released to a target or set
+ of targets. The assignment of rules to various targets is
+ quite flexible and includes mechanisms for specifying: that a
+ rule should affect all targets (default rule), exact SHAR
+ names for which a rule is applicable, regular expressions
+ against which SHAR names should be matched to determine if a
+ rule is applicable, URL trees for which a rule is
+ applicable.</p>
+
+ <p>For each request, an Effective ARP is determined by
+ locating all ARP's applicable to the designated user and
+ extracting each rule that matches the querying SHAR and
+ resource. Attributes and values that are specified for
+ release are included in the effective ARP, while those
+ specified for denial are blocked from release. See section <a
+ href="#5.a.i.">5.a.i</a> for details on how ARP's are
+ processed.</p>
+
+
+ <p>Various ARP's may be combined in forming the Effective ARP.
+ For instance, the Site ARP is administratively maintained and
+ applies to all users for which the AA is answerable. User
+ ARP's apply to a specific user only, and can be maintained
+ either administratively or by the users themselves. All ARP's
+ are specified using the same syntax and semantics.</p>
+ </blockquote>
+
+ <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
+
+ <blockquote>
+ <p>Since Shibboleth deals both with daily technical and
+ operational issues and also with contractual issues, a set of
+ contacts should be set up to support the user base and to
+ facilitate interactions with other Shibboleth sites and federation
+ members. It is recommended that at least technical and
+ administrative contacts be designated.</p>
+ </blockquote>
+
+ <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
+
+ <blockquote>
+ <p>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 cookies,
+ redirection and SSL. Browser users will have to perform an
+ additional click to submit the authentication assertion if
+ JavaScript is not functional.</p>
+ </blockquote>
+
+ <h4><a name="2.h."></a>2.h. Clocks</h4>
+
+ <blockquote>
+ <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
+ be run on all web servers. Shibboleth employs a short handle
+ issuance time to protect against replay attacks. Because of
+ this, any significant degree of clock skew can hinder the
+ ability of users to access sites successfully.</p>
+ </blockquote>
+
+ <h4><a name="2.i."></a>2.i. Other Considerations</h4>
+
+ <blockquote>
+ <p>Especially for 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 within the United States of America
+ are strongly advised to consult the <a href=
+ "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
+ Rights and Privacy Act of 1974(FERPA)</a>, and all other
+ relevant state and federal legislation before deploying
+ Shibboleth.</p>
+ </blockquote>
+ <br>
+ <br>
+ <hr>
+ <br>
+
+
+ <h3><a name="3."></a>3. Installation</h3>
+
+ <h4><a name="3.a."></a>3.a. Software Requirements</h4>
+
+ <p><b>The following requirements are primarily recommendations
+ based on the most common ways to run Shibboleth. However, the
+ origin should be able to run under any servlet container
+ supporting <span class="fixedwidth">Servlet API v2.3</span> and <span class="fixedwidth">JSP specification
+ 1.2</span>.</b></p>
+
+ <blockquote>
+ <ul type="circle">
+ <li><a href=
+ "http://http://www.apache.org/dist/httpd/">Apache
+ 1.3.26+ (<2.0)</a></li>
+
+ <li><a href="http://jakarta.apache.org/tomcat/">Tomcat
+ 4.1.18-24 LE Java server</a></li>
+
+ <li>
+ <a href="http://java.sun.com/j2se/">Sun J2SE v 1.4.1_01 SDK</a>
+
+ <blockquote>
+ <p>Other versions of the JRE are not supported and are
+ known to cause errors when working with
+ certificates.</p>
+ </blockquote>
+ </li>
+
+ <li>
+ mod_jk
+
+ <blockquote>
+ <p>You may need to build mod_jk against Apache, which
+ will generally require GCC or a platform-specific C
+ compiler.</p>
+ </blockquote>
+ </li>
+
+ <li>
+ An enterprise authentication mechanism
+
+ <blockquote>
+ <p>Ideally, this will be a WebISO or SSO system such as
+ <a href= "http://pubcookie.org/">Pubcookie</a>. The
+ minimal requirement is for the web server to be able to
+ authenticate browser users and supply their identity to
+ the Handle Server.</p>
+ </blockquote>
+ </li>
+
+ <li>
+ An enterprise directory service
+
+ <blockquote>
+ <p>Shibboleth currently supports retrieving user
+ attribute information from an <a href=
+ "http://www.openldap.org">LDAP</a> directory. For
+ testing purposes, Shibboleth also supports a minimal
+ echo responder which will always return two pre-defined
+ attributes.</p>
+ </blockquote>
+ </li>
+ </ul>
+ </blockquote>
+
+ <h4><a name="3.b."></a>3.b. Deploy HS and AA</h4>
+
+ <blockquote>
+ <ol type="1">
+ <li>
+ <p>Ensure you have already obtained the proper <a href=
+ "http://shibboleth.internet2.edu/release/shib-download.html">.tarball</a>.</p>
+ </li>
+
+ <li>
+ <p>The archive will expand into a <span class="fixedwidth">shibboleth-origin-1.0/</span>
+ directory(<span class="fixedwidth">/usr/local/</span> recommended).</p>
+ </li>
+
+ <li>
+ <p>Run the following command to move the Java files into
+ Tomcat's tree:</p>
+
+ <blockquote>
+ <span class="fixedwidth">cp /usr/local/shibboleth-origin-1.0/dist/shibboleth.war
+ /usr/local/tomcat/webapps/</span>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>Tomcat 4.1.x requires that several Java jarfiles used
+ by Shibboleth be located in a special "endorsed" folder to
+ override obsolete classes that Sun includes with their JVM.
+ To deal with this problem use the following command, adjusting
+ paths as needed:</p>
+ <blockquote>
+ <span class="fixedwidth">$ cp /usr/local/shibboleth-origin-1.0/endorsed/*.jar /usr/local/tomcat/common/endorsed</span>
+ </blockquote>
+ <p>Different versions of Tomcat or other Java servers may have
+ other locations in which to place these files or deal with this
+ problem. Refer to your application server's documentation to
+ find out how to properly endorse classes, if necessary.</p>
+ </li>
+
+ <li>
+ <p>Restart Tomcat, which will automatically detect that
+ there has been a new .war file added. This file will by
+ default be expanded into
+ <span class="fixedwidth">/usr/local/tomcat/webapps/shibboleth</span>.</p>
+ </li>
+
+ <li>
+ <p>Apache must be told to map the URL's for the
+ Shibboleth HS and AA to Tomcat. Two popular ways of doing
+ this are to include the following text directly in
+ <span class="fixedwidth">httpd.conf</span>, or to place <span class="fixedwidth">Include
+ conf/mod_jk.conf</span> in <span class="fixedwidth">httpd.conf</span>, and place
+ the following lines in
+ <span class="fixedwidth">/etc/httpd/conf/mod_jk.conf</span>:</p>
+
+ <blockquote>
+ <span class="fixedwidth">--------- begin ---------<br>
+ <IfModule !mod_jk.c><br>
+ LoadModule jk_module libexec/mod_jk.so<br>
+ </IfModule><br>
+ <br>
+ JkWorkersFile
+ "/usr/local/tomcat/conf/jk/workers.properties"<br>
+ JkLogFile "/usr/local/apache/logs/mod_jk.log"<br>
+ <br>
+ JkLogLevel emerg<br>
+ <br>
+ JkMount /shibboleth/* ajp13<br>
+ <br>
+ --------- end ---------</span>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>Tomcat's <span class="fixedwidth">/conf/server.xml</span>
+ ships by default with the Coyote/JK2 connector enabled, which
+ fails with Shibboleth due to the lack of support for <span
+ class="fixedwidth">REMOTE_USER</span>. This connector must be
+ commented out. Then, uncomment and modify the traditional AJP
+ 1.3 connector as follows:</p>
+
+ <ol type="A">
+ <li>
+ <p>Add <span class="fixedwidth">address="127.0.0.1"</span> inside the
+ <span class="fixedwidth"><Ajp13Connector></span> configuration
+ element to prevent off-host access.</p>
+ </li>
+
+ <li>
+ <p>Add <span class="fixedwidth">tomcatAuthentication="false"</span> to the
+ <span class="fixedwidth"><Ajp13Connector></span> configuration element
+ to ensure that the user's identity is passed from
+ Apache to the servlet environment.</p>
+ </li>
+ </ol>
+ </li>
+ </ol>
+ </blockquote>
+ <br>
+ <hr>
+ <br>
+
+
+ <h3><a name="4."></a>4. Getting Running</h3>
+
+ <h4><a name="4.a."></a>4.a. Basic Configuration</h4>
+
+ <blockquote>
+ <p>The main configuration file for Shibboleth's origin side is
+ located in
+ <span class="fixedwidth">/webapps/shibboleth/WEB-INF/classes/conf/origin.properties.</span>. This file contains configuration information
+ for the origin side in several sections. The configuration
+ must be consistent with values elsewhere in the deployment,
+ such as the <a href="#4.c.">HS' certificate</a> and with
+ directory access bindings, etc., or access errors may occur.</p>
+
+ <p>All pathnames are relative, and have an effective root
+ path of
+ <span class="fixedwidth">$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/</span>. To
+ specify files outside of the webapp, specify a full URI, such
+ as <span class="fixedwidth">file:///usr/local/shibboleth/</span>.</p>
+
+ <p>Fields that are purple are optional; grey fields are
+ mandatory.</p>
+
+
+ <p>These are the variables that may be specified for each
+ component of <span class="fixedwidth">origin.properties</span>:</p>
+
+ <br>
+ <p>General Configuration:</p>
+
+ <dl>
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer
+ = <domain name></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the DNS name the HS should use for
+ itself in issuing assertions.</p>
+ </dd>
+
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName
+ = <URI></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the the <span
+ class="fixedwidth">URI</span> to use as the name of
+ the origin site as a whole. This field is primarily
+ meant to be populated in the context of the federation
+ in which the origin site resides, is intended to be
+ globally unique, and will typically be assigned by the
+ federation.</p>
+ </dd>
+
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl
+ = <url></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the <span class="fixedwidth">URL</span>
+ at which the HS' corresponding AA may be
+ contacted.</p>
+ </dd>
+
+ <dd class="attributeoptlong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.username
+ = <var></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies the HTTP request header that should be used
+ to acquire the user's principal name from the
+ authentication service. Defaults to <span
+ class="fixedwidth">REMOTE_USER</span>.</p>
+ </dd>
+
+ <dd class="attributeoptlong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.authMethod
+ = <uri></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifes the URI used to populate <span
+ class="fixedwidth">AuthenticationMethod</span> in the SAML
+ attribute assertion. This corresponds to the method used
+ to authenticate users by the authentication service used
+ by the HS. Some common authentication methods and
+ corresponding URI's are listed below; for a complete list,
+ please consult section 7.1 of the SAML 1.1 core
+ specifications or your federation's guidelines.</p>
+ <table border=2 cellpadding=0 cellspacing=0>
+ <tr>
+ <td><span class="fixedwidth">urn:oasis:names:tc:SAML:1.0:am:password</span></td>
+ <td>The authentication was performed using a password.</td>
+ </tr>
+ <tr>
+ <td><span class="fixedwidth">urn:ietf:rfc:1510</span></td>
+ <td>The authentication was performed using Kerberos.</td>
+ </tr>
+ <tr>
+ <td><span class="fixedwidth">urn:oasis:names:tc:SAML:1.0:am:X509-PKI</span></td>
+ <td>The authentication was performed using a
+ certificate and key issued to the end user. More
+ specific forms of PKI authentication such as SPKI and
+ XKMS are also assigned URN's in the SAML specs.</td>
+ </tr>
+ </table>
+ </dd>
+ </dl>
+
+ <br>
+ <p>Assertion Signing:</p>
+
+ <dl>
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath
+ = <pathname></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the location of the Java keystore
+ containing the x.509 certificate and matching private
+ key to be used by the HS.</p>
+ </dd>
+
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword
+ = <password></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the password to the referenced
+ keystore.</p>
+ </dd>
+
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias
+ = <alias></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the alias used for accessing the private
+ key.</p>
+ </dd>
+
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
+ = <password></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the password used to retrieve the private key.</p>
+ </dd>
+
+ <dd class="attributeoptlong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias
+ = <alias></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies the alias for the certificate
+ corresponding to the private key used by the HS.
+ Defaults to the private key's alias.</p>
+ </dd>
+ </dl>
+ <br>
+
+ <p>General AA Configuration:</p>
+
+ <dl>
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName
+ = <domain name></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the name of the AA, which is typically
+ the domain name of the server running it.</p>
+ </dd>
+
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.AAServlet.passThruErrors
+ = <true/false></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies whether the AA should pass on internal errors
+ to the SHAR for debugging purposes. Defaults to <span
+ class="fixedwidth">false</span>.</p>
+ </dd>
+ </dl>
+
+ <p>AA Attribute Resolution:</p>
+
+ <dl>
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig
+ = <pathname></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the location of the configuration file
+ for the resolver the AA uses to build attributes.
+ Defaults to <span
+ class="fixedwidth">/conf/resolver.xml</span>. For
+ information on how to configure and use the attribute
+ resolver, consult section <a href="4.e.">4.e</a>.</p>
+ </dd>
+ </dl>
+
+ <p>ARP Configuration:</p>
+
+ <dl>
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.ArpRepository.implementation
+ = <string></span>
+ </dd>
+
+ <dd class="value">
+ <p>References the type of ARP repository implemented.
+ Shibboleth provides a built-in ARP repository
+ specified by
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.
+ provider.FileSystemArpRepository</span>.</p>
+
+ <p>Note that the set of principals that an ARP applies
+ to is not expressed by the ARP itself, but rather the
+ implementation of the ARP repository. For example, if
+ the ARP repository were implemented in LDAP, the ARP's
+ that apply to a user would be attributes of that
+ user's personal LDAP entry, and the site ARP would be
+ an attribute of an entry representing the site. While
+ not performed by the built-in ARP repository, a
+ repository implementation might also implement group
+ ARP's; for example, in an LDAP directory, the user
+ entry might have some group membership attributes that
+ refer to group entries, and those group entries would
+ have ARP attributes, and all those ARP's would be
+ applicable.</p>
+ </dd>
+
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path
+ = <pathname></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the relative or absolute path to the
+ folder containing the ARP files.</p>
+ </dd>
+
+ <dd class="attributeoptlong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.ArpTTL
+ = <seconds></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies the duration in <span
+ class="fixedwidth">seconds</span> that ARP's may be
+ cached by the AA. Defaults to <span
+ class="fixedwidth">0</span>, or no caching.</p>
+ </dd>
+ </dl>
+
+ <p>Handle Repository Configuration:</p>
+
+ <dl>
+ <dd class="attributeoptlong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.implementation
+ = <string></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies the method by which the HS and AA share
+ handles. These are by default passed by memory(which
+ can be specified explicitly using
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.
+ MemoryHandleRepository</span>), and may also be passed
+ using symmetric encryption with
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository</span>.</p>
+ </dd>
+ </dl>
+
+ <p>edu.internet2.middleware.shibboleth.hs.provider.
+ MemoryHandleRepository <font color="#5555EE">(specify
+ if
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.
+ implementation</span> is <span class="fixedwidth">MemoryHandleRepository</span>)</font></p>
+
+ <blockquote>
+ <dl>
+ <dd class="attributeoptlong">
+<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.BaseHandleRepository.handleTTL
+ = <seconds></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies the time in <span
+ class="fixedwidth">seconds</span> for which issued handles
+ are valid. Defaults to <span
+ class="fixedwidth">1800</span>, or 30 minutes. The time
+ should be long enough to allow for clock skew and short
+ enough to protect against various attacks. Consult your
+ federation guidelines for further advice.</p>
+ </dd>
+ </dl>
+ </blockquote>
+
+ <p>edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository <font color="#5555EE">(specify
+ if
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.HandleRepository.
+ implementation</span> is <span class="fixedwidth">CryptoHandleRepository</span>)</font></p>
+
+ <p>In order to use the crypto repository implementation, you must
+ have a <span class="fixedwidth">DESede</span> secret key in a
+ keystore of type <span class="fixedwidth">JCEKS</span>. The
+ origin distribution includes a program that will automatically
+ generate such a key. In order to invoke it, run <span
+ class="fixedwidth">./ant genSecret</span>, which will create a
+ keystore in <span
+ class="fixedwidth">$SHIB_HOME/src/conf/handle.jks</span> that
+ includes the key, with an alias of <span
+ class="fixedwidth">handleKey</span> and a password of <span
+ class="fixedwidth">shibhs</span>. If <span
+ class="fixedwidth">./ant dist</span> is run subsequently, this
+ keystore will be included in the webapp archive that is
+ created.</p>
+
+ <blockquote>
+ <dl>
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePath
+ = <pathname></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the path to the keystore containing the
+ key used to encrypt passed principal identifiers.</p>
+ </dd>
+
+ <dd class="attributelong">
+<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword
+ = <password></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the password for the keystore.</p>
+ </dd>
+
+ <dd class="attributelong">
+<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias
+ = <password></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies the alias for the appropriate encryption
+ key within the keystore.</p>
+ </dd>
+
+ <dd class="attributelong">
+<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword
+ = <password></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies the password used to retrieve the key.</p>
+ </dd>
+
+ <dd class="attributeoptlong">
+<span class="fixedwidth">edu.internet2.middleware.shibboleth.hs.CryptoHandleRepository.handleTTL
+ = <seconds></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies the time in <span
+ class="fixedwidth">seconds</span> for which issued handles
+ are valid. Defaults to <span
+ class="fixedwidth">1800</span>, or 30 minutes. The time
+ should be long enough to allow for clock skew and short
+ enough to protect against various attacks. Consult your
+ federation guidelines for further advice.</p>
+ </dd>
+
+ </dl>
+ </blockquote>
+
+ <p>Federation Configuration:</p>
+
+ <dl>
+ <dd class="attributelong">
+ <span class="fixedwidth">edu.internet2.middleware.shibboleth.audiences
+ = <URI's></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies a list of <span
+ class="fixedwidth">URI</span>'s that will be used for
+ the <span class="fixedwidth">Audience</span> field of
+ the SAML attribute assertion. All URI's listed will
+ be sent with any assertion issued by the AA. These
+ URI's are defined and provided by and correspond to
+ federations.</p>
+
+ <p>Note that the values of the URI's here <b>must</b>
+ match one of the policy URI's accepted by the
+ receiving target in the <span
+ class="fixedwidth">[policies]</span> section of <span
+ class="fixedwidth">shibboleth.ini</span> or
+ interoperation will fail by design.
+ </dd>
+ </dl>
+
+ </blockquote>
+ <br>
+
+
+ <h4><a name="4.b."></a>4.b. Key Generation and Certificate
+ Installation</h4>
+
+ <blockquote>
+ <p>The SAML messages generated by the HS must be digitally
+ signed. 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. Access parameters to the
+ keystore will need to be consistent with those specified in
+ <span class="fixedwidth">origin.properties</span>.</p>
+
+ <p>A sample keystore is included in the distribution and can
+ be found in
+ <span class="fixedwidth">/usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf/keystore
+ .jks</span> with a password of <span class="fixedwidth">shibhs</span>. It is intended
+ to serve as an example and not as a production keystore.</p>
+
+ <p>The following commands will generate a new RSA keypair and
+ store it in the <span class="fixedwidth">keystore.jks</span> file, with a keyentry
+ alias of <span class="fixedwidth">hs</span> and new passwords of your choosing:</p>
+
+ <blockquote>
+ <span class="fixedwidth">$ cd
+ /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf<br>
+ $ keytool -storepasswd -keystore keystore.jks -new
+ <newpassword><br>
+ $ keytool -genkey -keystore keystore.jks -alias hs -keyalg
+ rsa -keysize 2048<br>
+ </span>
+ </blockquote>
+
+ <p>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 <span class="fixedwidth">Common Name</span>(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 a specific federation of
+ sites may dictate what type of key algorithm, key size, or
+ validity period is appropriate.</p>
+
+ <p>Once you have a keypair generated, the self-signed certificate
+ must be replaced with a certificate signed by a CA acceptable to
+ the federation you will be joining. Shibboleth is generally able to
+ climb trust chains to reach an intermediate CA's root CA. Note
+ that the intermediate CA's signing certificate must still be
+ signed by a root CA recognized by the federation.</p>
+
+ <p>To generate a certificate signing request for a CA, use
+ the following command:</p>
+
+ <blockquote>
+ <span class="fixedwidth">$ keytool -certreq -keystore keystore.jks -alias hs
+ -file <csr-file><br>
+ </span>
+ </blockquote>
+
+ <p>The contents of <span class="fixedwidth"><csr-file></span> 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:</p>
+
+ <blockquote>
+ <span class="fixedwidth">$ keytool -import -keystore keystore.jks -alias hs
+ -file <cert-file></span>
+ </blockquote>
+
+ <p>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 the above.</p>
+
+ <p>For information on sharing certificate/key pairs between Apache
+ and Java keystores see section <a href="#5.b.">5.b.</a>.</p>
+ </blockquote>
+
+ <h4><a name="4.c."></a>4.c. Linking the Authentication System
+ to the HS</h4>
+
+ <blockquote>
+ <p>The interaction between the HS and the local authentication
+ system is implemented by supplying the HS with the identity of
+ the browser user. Most often, this will mean protecting the HS
+ servlet with some form of local authentication that populates
+ <span class="fixedwidth">REMOTE_USER</span>. Location blocks can be added to
+ <span class="fixedwidth">httpd.conf</span>, associating the appropriate
+ authentication mechanism with the URL of the HS servlet. The
+ following example demonstrates association of a very basic
+ authentication method with the HS:</p>
+
+ <blockquote>
+ <span class="fixedwidth"><Location /shibboleth/HS><br>
+ AuthType Basic<br>
+ AuthName "Internet2 Handle Service"<br>
+ AuthUserFile /usr/local/apache/conf/user.db<br>
+ require valid-user<br>
+ </Location><br>
+ </span>
+ </blockquote>
+
+ <p>Note that .htaccess files cannot be used for this purpose
+ because URL's are "virtualized" by Tomcat.</p>
+
+ <p>It is recommended that the origin be tested at the end of
+ this process using the process described in section <a href=
+ "#6.a.">6.a</a>.</p>
+ </blockquote>
+
+ <h4><a name="4.c.i."></a>4.c.i. Enabling client certificate
+ authentication <font color="#5555EE">(optional)</font></h4>
+
+ <blockquote>
+ <blockquote>
+
+ <p>Shibboleth supports client certificate authentication by
+ utilization of a filter that relies on the web server to do all
+ processing to ensure that the certificate is both valid and
+ appropriate for the application. An example deployment descriptor
+ is included with the Shibboleth distribution at <span
+ class="fixedwidth">$SHIB_HOME/webAppConfig/origin-client-cert.xml</span>.
+ To enable the filter, add the following to the deployment
+ descriptor (<span class="fixedwidth">web.xml</span>):</p>
+
+ <blockquote>
+ <span class="fixedwidth"> <filter><br>
+ <filter-name><br>
+ Client Cert AuthN Filter<br>
+ </filter-name><br>
+ <filter-class><br>
+ edu.internet2.middleware.shibboleth.utils.ClientCertTrustFilter<br>
+ </filter-class><br>
+ </filter><br>
+ <br>
+ <br>
+ <filter-mapping><br>
+ <filter-name><br>
+ Client Cert AuthN Filter<br>
+ </filter-name><br>
+ <url-pattern><br>
+ /HS<br>
+ </url-pattern><br>
+ </filter-mapping><br></span>
+ </blockquote>
+
+ <p>By default, the filter pulls the principal name out of the <span
+ class="fixedwidth">CN</span> of the cert's <span
+ class="fixedwidth">Subject</span> by using regular expression
+ grouping. This may be done using patterns such as:</p>
+
+ <blockquote>
+ <span class="fixedwidth">regex: '.*CN=([^,/]+).*' match group: 1</span>
+ </blockquote>
+
+ <p>The servlet filter will accept two initialization parameters,
+ <span class="fixedwidth">regex</span> and <span
+ class="fixedwidth">matchGroup</span> that can be used to extract
+ the principal name differently.</p>
+
+ </blockquote>
+ </blockquote>
+
+ <h4><a name="4.d."></a>4.d. Establishing default ARP's for the
+ origin community</h4>
+
+ <p><b>For a more basic introduction to ARP's, please refer to
+ section <a href="#2.e.">2.e</a>.</b></p>
+
+ <blockquote>
+ <p>An ARP determines which attributes are released to a SHAR
+ when a user tries to access a resource. It acts as a sort of
+ filter on user information contained in the authoritative
+ directory, deciding what can be released to whom, but not
+ modifying or creating information itself. ARP's are generally
+ administered by the site, but Shibboleth will provide for users to
+ broker control of their own information and privacy by
+ allowing them to create ARP's pertaining to themselves.</p>
+
+ <p>It is recommended that a set of policies be established
+ between an origin and frequently accessed targets to specify
+ default releases of expected attributes. Federation guidelines may
+ provide more information on population of ARP's.</p>
+
+ <p>Currently, there is no direct mechanism for users to create
+ their own ARP's besides direct XML writing. In future
+ versions, a GUI will be provided for simpler management of
+ ARP's. Care should be given to balancing giving sufficient
+ control over information to users and avoiding access
+ problems. For example, users may decide to restrict the
+ release of their personal information to such a degree that
+ access to a site for a class may become impossible because
+ Shibboleth cannot release enough information to grant
+ access.</p>
+
+ <p>The Shibboleth distribution contains an example site arp that
+ releases the eduPersonScopedAffiliation attribute to all targets. For
+ more precise information regarding how ARP's are processed or
+ syntactically formed, please refer to section <a href="#5.a.i.">5.a.i</a>.</p>
+ </blockquote>
+
+ <h4><a name="4.e."></a>4.e. Modifying the default Attribute Resolver configuration</h4>
+ <blockquote>
+ <p>The resolver.xml file controls the retrieval of attributes from enterprise repositories, and the process of mapping them to Shibboleth/SAML attributes. For more precise information regarding how attributes are processed or syntactically formed, please refer to section <a href="#5.c.">5.c.</a></p>
+
+ <p>In order to make the Shibboleth software operational, however, minor edits must be made to the example version of the resolver.xml file. The file can be found at <span class="fixedwidth">/webapps/shibboleth/WEB-INF/classes/conf/resolver.xml.</span> Two changes are necessary:</p>
+
+ <p> 1. The value of the smartScope attribute should be changed to the Domain Name value submitted to the Federation. It appears on two SimpleAttributeDefinition elements: eduPersonScopedAffiliation and eduPersonPrincipalName.</p>
+
+ <p>2. The comment indicators should be removed from around the definitions of those two elements ( <!-- and --> ).</p>
+ </blockquote>
+ <br>
+ <hr>
+ <br>
+
+ <h3><a name="5."></a>5. Advanced Configuration</h3>
+
+ <h4><a name="5.a."></a>5.a. ARP Overview</h4>
+
+ <blockquote>
+ <h5>This section applies primarily to the syntactic and
+ technical details of ARP's. For basic information on and
+ explanation of what an ARP is and how it should be managed,
+ please refer to sections <a href="#2.e.">2.e</a> and <a href=
+ "#4.d.">4.d</a>.</h5>
+
+ <p>Every ARP file contains one ARP. ARP's may be specified either
+ as the site ARP or user ARP's. The site ARP pertains to every
+ principal for whom the AA retrieves information; a user ARP
+ applies only to the individual user for whom it is defined. The
+ set of principals to whom the ARP applies is defined by the name
+ of the ARP file: the site ARP is stored in <span
+ class="fixedwidth">arp.site.xml</span> and user ARP's are stored as
+ <span class="fixedwidth">arp.user.$PRINCIPALNAME.xml</span>.
+ Up to two ARP's will apply to a principal: the site ARP, and the
+ user ARP for that principal.</p>
+
+ <p>Each ARP acts as a container that holds a set of ARP rules
+ that are applicable to the principals that ARP is effective
+ for. Each ARP rule specifies a single release policy within
+ the ARP container pertaining to a specific set of targets.
+ This set of targets may be specified as a specific SHAR, a
+ SHAR tree, or a regular expression, and becomes the ARP rule's
+ target definition. Each ARP rule may contain specifications
+ regarding the release of any number of attribute values to
+ requests matching that ARP rule for that user. ARP rules may
+ be flagged as default, implying that they are always applied
+ to any user matched by the ARP container. Note that ARP's may
+ also be used to restrict specific attribute/value pairs in
+ addition to restricting or releasing individual attributes.</p>
+
+ <p>When a query is received, the AA generates an effective
+ ARP, which is the fully evaluated set of ARP rules regarding
+ that SHAR based on all ARP containers applicable to the
+ principal. This effective ARP is then applied to attribute
+ values retrieved from the directory and the appropriate
+ assertion is constructed. Default rules are always
+ included in construction of the effective ARP.</p>
+
+ <!-- ##To be included in future releases of the deploy guide.
+
+ <dl>
+ <dd class="demo">
+ <img src="arp.gif">
+ </dd>
+ <dd class="demo">
+ <p>In this picture, meant to demonstrate the structure
+ of ARP's, if all ARP's are taken to mean "Release this
+ attribute," then attributes 1-4 will be released if that
+ principal tries to access site A. ARP #1 could not
+ restrict the release of attribute 4 to site A.</p>
+ </dd>
+ </dl>
+
+ -->
+
+ </blockquote>
+
+ <h4><a name="5.a.i."></a>5.a.i. ARP Processing</h4>
+
+ <blockquote>
+ <blockquote>
+ <p>When a request arrives from a particular SHAR, the
+ applicable set of ARP rules are parsed into an effective
+ ARP. This parsing is done as follows:</p>
+
+ <ol type=1>
+ <li>Identify all ARP's that should be applied to a particular
+ principal. This is done by isolating the files in the folder
+ specified by <span
+ class="fixedwidth">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path</span> that have the
+ name either arp.site.xml or arp.user.$PRINCIPALNAME.xml.</li>
+ <li>Find all ARP rules relevant to the query:
+ <ol type=i>
+ <li>Any ARP rules within the identified ARP's designated
+ as defaults are automatically included in the effective
+ ARP without performing any matching functions.</li>
+ <li>For each non-default rule in each identified ARP,
+ the matching functions specified in the rule's target
+ definition are performed. A separate matching function
+ is performed for the requesting SHAR and the resource on
+ behalf of which the SHAR is making the request.</li>
+ <li>Each matching function evaluates to <span class="fixedwidth">TRUE</span> if
+ the match is successful or <span class="fixedwidth">FALSE</span> if it is
+ unsuccessful. If both functions evaluate to
+ <span class="fixedwidth">TRUE</span>, the rule is included in the Effective
+ ARP.</li>
+ </ol></li>
+ <li>Construct the Attribute Filter:
+ <ol type=i>
+ <li>For each attribute, compile a temporary list of
+ associated rules that includes all values with a release
+ qualifier of <span class="fixedwidth">permit</span>.</li>
+ <li>Subtract from this list all attribute values with
+ rules specifying a release qualifier of <span class="fixedwidth">deny</span>.
+ The resulting list represents the allowable release
+ values for the attribute and is used as a mask for the
+ values which are returned from the Attribute
+ Resolver.</li>
+ <li>If a statement specifies that all values should be
+ permitted, then specific <span class="fixedwidth">deny</span> qualifiers for
+ specific values should still be enforced. If a
+ statement specifies that all values should be denied,
+ then <span class="fixedwidth">permit</span> qualifiers for specific values will
+ be ignored.</li>
+ </ol></li>
+ <li>Using the mask and attributes returned from the
+ Attribute Resolver, an assertion is constructed.</li>
+ </ol>
+ </blockquote>
+ </blockquote>
+
+
+ <h4><a name="5.a.ii."></a>5.a.ii. ARP Syntax</h4>
+
+ <blockquote>
+ <blockquote>
+
+ <p>Each ARP is described by an XML file based on a standard
+ <span class="fixedwidth">.xsd</span> schema. It consists of a standard
+ <span class="fixedwidth">AttributeReleasePolicy</span> element referencing the
+ appropriate <span class="fixedwidth">xsi:schemaLocation</span> and a self-explanatory
+ <span class="fixedwidth">Description</span> element followed by any number of
+ <span class="fixedwidth">Rule</span> elements. Each <span class="fixedwidth">Rule</span> element must
+ consist of a <span class="fixedwidth">Target</span> element and one or more
+ <span class="fixedwidth">Attribute</span> elements. The <span class="fixedwidth">Target</span> element
+ specifies the rules by which the target definition is formed.
+ The <span class="fixedwidth">Attribute</span> elements specifies the name and values
+ of the attributes that may be released.</p>
+
+ <p>The simplest possible ARP is as follows, which releases
+ <span class="fixedwidth">eduPersonScopedAffiliation</span> to any target for the
+ users the ARP applies to:</p>
+
+ <blockquote>
+ <span class="fixedwidth">
+ <?xml version="1.0"?><br>
+
+ <AttributeReleasePolicy
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="urn:mace:shibboleth:arp:1.0"
+ xsi:schemaLocation="urn:mace:shibboleth:arp:1.0
+ shibboleth-arp-1.0.xsd"><br>
+
+
+ <Description>Simplest possible
+ ARP.</Description><br>
+
+
+ <Rule><br>
+
+
+ <Target><br>
+
+
+
+ <AnyTarget/><br>
+
+
+ </Target><br>
+
+
+ <Attribute
+ name="urn:mace:eduPerson:1.0:eduPersonScopedAffiliation"><br>
+
+
+
+ <AnyValue release=
+ "permit"/><br>
+
+
+ </Attribute
+ ><br>
+
+ </Rule
+ ><br>
+
+ </AttributeReleasePolicy><br>
+
+ </span>
+ </blockquote>
+ </blockquote>
+
+ <p>All ARP's must take the same basic form. A detailed
+ description of how each element of the <span class="fixedwidth">Rule</span> element
+ may be sub-populated follows:</p>
+
+ <p>The <span class="fixedwidth">Target</span> element:</p>
+
+ <blockquote>
+
+ <p><span class="fixedwidth">Target</span> may contain either the
+ <span class="fixedwidth">AnyTarget</span> element, which will cause the
+ <span class="fixedwidth">Target</span> to always return <span class="fixedwidth">TRUE</span>, or both the
+ <span class="fixedwidth">Requester</span> element, which provides for matches to be
+ performed against the SHAR name and the <span class="fixedwidth">Resource</span>
+ element, which provides for matches to be performed against
+ the requested URL.</p>
+
+ <p>There are three matches that may be performed by the AA
+ in evaluating ARP's by using the <span class="fixedwidth">matchFunction</span>
+ component of the <span class="fixedwidth">Requester</span> and <span class="fixedwidth">Resource</span>
+ elements. The following match patterns may be
+ specified directly following the <span class="fixedwidth">Requester</span> or
+ <span class="fixedwidth">Resource</span> elements, such as <span class="fixedwidth"><Requester
+ matchFunction="urn:mace:shibboleth:arp:matchFunction:regexMatch"></span>:</p>
+
+ <ul type=disc>
+ <li>
+ <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:exactShar
+ </span></p>
+ <blockquote>
+ <p>May be used with the <span class="fixedwidth">Requester</span>
+ element.</p>
+
+ <p>Evaluates to <span class="fixedwidth">TRUE</span> when the string content
+ of the <span class="fixedwidth">Requester</span> element matches exactly the
+ name of the requesting SHAR. Otherwise evaluates to
+ <span class="fixedwidth">FALSE</span>. Serves as the default value
+ associated with <span class="fixedwidth">Requester</span> if none is
+ specified.</p>
+ </blockquote>
+ </li>
+ <li>
+ <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:resourceTree
+ </span></p>
+ <blockquote>
+ <p>May be used with the <span class="fixedwidth">Resource</span> element.</p>
+
+ <p>Evaluates to <span class="fixedwidth">TRUE</span> when the location of
+ the resource either matches exactly or begins with
+ the string content of the <span class="fixedwidth">Resource</span> element.
+ Otherwise evaluates to <span class="fixedwidth">FALSE</span>.</p>
+ </blockquote>
+ </li>
+ <li>
+ <p><span class="fixedwidth">urn:mace:shibboleth:arp:matchFunction:regexMatch
+ </span></p>
+ <blockquote>
+ <p>May be used with both the <span class="fixedwidth">Requester</span>
+ and <span class="fixedwidth">Resource</span> elements.</p>
+
+ <p>Evaluates to <span class="fixedwidth">TRUE</span> when the name of the
+ requesting SHAR or the requested URL tree is a valid
+ match of the regular expression represented as the
+ content of the containing element. Otherwise evaluates
+ to <span class="fixedwidth">FALSE</span>. Regular expressions are evaluated in
+ accordance with the the <a
+ href="http://java.sun.com/j2se/1.4/docs/api/java/util/
+ regex/Pattern.html#sum">Java 1.4 Pattern API</a>.</p>
+ </blockquote>
+ </li>
+ </ul>
+
+ </blockquote>
+
+ <p>The <span class="fixedwidth">Attribute</span> element:</p>
+
+ <blockquote>
+
+ <p>The <span class="fixedwidth">Attribute</span> element must always specify the
+ URN of the attribute whose release parameters it specifies.
+ Additionally, it must contain either the <span class="fixedwidth">AnyValue</span>
+ element or one or more <span class="fixedwidth">Value</span> elements. These
+ elements, in turn, must specify either <span class="fixedwidth">release</span> =
+ <span class="fixedwidth">permit</span> or <span class="fixedwidth">deny</span>. The <span class="fixedwidth">Value</span>
+ element must then contain one value for which the rule
+ applies. Examples:</p>
+
+ <blockquote>
+ <span class="fixedwidth">
+ <Attribute name="urn:mace:eduPerson:1.0:eduPersonPrincipalName"><br>
+ <AnyValue release="Permit"><br>
+ </Attribute><br>
+ </span><br>
+ <p>Permits the release of <span class="fixedwidth">eduPersonPrincipalName</span>
+ with any value.</p>
+ </blockquote>
+
+ <blockquote>
+ <span class="fixedwidth">
+ <Attribute name="urn:mace:eduPerson:1.0:eduPersonScopedAffiliation"><br>
+ <Value release="deny">member@example.edu</Value><br>
+ </Attribute><br>
+ </span><br>
+ <p>Denies the release of
+ <span class="fixedwidth">eduPersonScopedAffiliation</span> value
+ <span class="fixedwidth">member@example.edu</span>. Other values of the
+ attribute may still be released if so specified by a
+ <span class="fixedwidth">permit</span> ARP.</p>
+ </blockquote>
+ </blockquote>
+
+ <!-- ##To be included in future releases. Not yet implemented.
+
+ <p>There is also a special <span class="fixedwidth">AttributeIdentifier</span>
+ element that allows internal references to the an attribute
+ within an ARP. This is useful for quickly applying multiple
+ rules to the same target. It is used as follows:</p>
+
+ <blockquote>
+ <span class="fixedwidth">
+ <Rule><br>
+
+ <Target><br>
+
+ <AnyTarget/><br>
+
+ </Target><br>
+
+ <Attribute
+ name="urn:mace:eduPerson:1.0:
+ eduPersonScopedAffiliation"><br>
+
+ <Value
+ release="permit">member@example.edu</Value
+ ><br>
+
+ </Attribute><br>
+
+ </Rule><br>
+
+ <AttributeReference identifier="http://www.example.edu/attributes/attribute1"><br>
+
+ <Attribute name="urn:mace:eduPerson:1.0:eduPersonAffiliation" identifier="http://www.example.edu/attributes/attribute1"><br>
+
+ <Value release="permit">student@example.edu<Value><br>
+
+ </Attribute><br>
+ </span>
+ -->
+
+ </blockquote>
+ <h4><a name="5.b."></a>5.b. Sharing certificate/key pairs
+ between Apache and Java keystores <font color="#5555EE">(optional)</font></h4>
+
+ <blockquote>
+ <blockquote>
+ <p>The JDK includes the command line program
+ <span class="fixedwidth">keytool</span> for managing Java keystores. This utility
+ cannot import or export private key information, making it
+ difficult to use the same private key and certificate for
+ Apache and Java-based applications. The Shibboleth
+ distribution includes <span class="fixedwidth">extkeytool</span>, a program that
+ can be used in conjunction with <span class="fixedwidth">keytool</span> to perform
+ these tasks. Select the appropriate step-by-step procedure
+ for your situation from the following guides.</p>
+
+ <p>Before running <span class="fixedwidth">extkeytool</span>, the variable
+ SHIB_HOME must be set to the path to the directory where the
+ Shibboleth tarball was exploded(typically
+ /usr/local/shibboleth-origin-1.0/).</p>
+
+ <p><b>If you have a pre-exiting RSA key/certificate
+ combination in a keystore and you would like to use it with
+ Apache:</b></p>
+
+ <ol type="1">
+ <li>
+ <p>Determine the alias of the keystore keyEntry
+ containing the key you would like to use in your Apache
+ setup. Assuming that your keystore is named
+ <span class="fixedwidth">yourstore</span>, the following command should
+ present a list of the entries in the keystore.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ keytool -list -v -keystore
+ yourstore</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>Assuming that you identified the appropriate alias
+ as <span class="fixedwidth">youralias</span> and the password for the keystore
+ is <span class="fixedwidth">yourpass</span>, enter the following command to
+ export the key in Base64-encoded pkcs8 format.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ extkeytool -exportkey -keystore yourstore
+ -alias youralias -storepass yourpass -rfc -file
+ yourkey.pkcs8</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>In order to use this key with Apache, you must
+ convert it to PEM-encoded RSA native format. You have
+ the option of storing the key unencrypted or
+ encrypted:</p>
+
+ <ol type="A">
+ <li>
+ <p>To use the unencrypted format, enter the
+ following command for the conversion:</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
+ -nocrypt|openssl rsa -out yourkey.key</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>To use the encrypted format, enter the following
+ command for the conversion:</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.pkcs8
+ -nocrypt|openssl rsa -des3 -out
+ yourkey.enckey</span></p>
+ </blockquote>
+ </li>
+ </ol>
+ </li>
+
+ <li>
+ <p>The following command will export the corresponding
+ certificate.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ keytool -export -keystore yourstore -alias
+ youralias -rfc -file yourcert</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>Set the <span class="fixedwidth">mod_ssl</span>
+ <span class="fixedwidth">SSLCertificateKeyFile</span> and
+ <span class="fixedwidth">SSLCertificateFile</span> directives to point to the
+ two files you have just created. Take care to remove
+ any temporary files you created (i.e.
+ <span class="fixedwidth">yourkey.pkcs8</span>) and set appropriate file
+ permissions, especially if you chose to store the key
+ in an unencrypted format.</p>
+ </li>
+ </ol>
+
+ <p><b>If you have a pre-existing RSA key/certificate
+ combination that you use with Apache and would like to
+ import it into a java keystore:</b></p>
+
+ <ol type="1">
+ <li>
+ <p>Convert the private key to unencrypted DER-encoded
+ pkcs8 format. Assuming your PEM-encoded key is stored
+ in a file named <span class="fixedwidth">yourkey.enckey</span>, enter the
+ following command.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ openssl pkcs8 -in yourkey.enckey -topk8
+ -nocrypt -outform DER -out yourkey.der.pkcs8</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>Create a certificate bundle file. This file should
+ include a series of PEM-encoded X509 certificates
+ representing a complete trust chain, from the root CA
+ certificate to the certificate that matches your
+ private key. If your certificate is stored in a file
+ named <span class="fixedwidth">mycert</span> and the CA signer certificate is
+ stored in a file named <span class="fixedwidth">ca.cert</span>, you might
+ enter the following command to create the bundle.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ cat mycert ca.cert > cert.bundle</span></p>
+ </blockquote>
+
+ <b>Note: <span class="fixedwidth">mod_ssl</span>-enabled Apache
+ installations include a number of commonly recognized
+ CA certificates in the <span class="fixedwidth">ca-bundle.crt</span> file
+ under the <span class="fixedwidth">$ServerRoot/conf/ssl.crt/</span>
+ directory.</b>
+ </li>
+
+ <li>
+ <p>Import the key and certificate into the keystore.
+ Assuming you have already created a keystore named
+ <span class="fixedwidth">yourstore</span> with a password of of
+ <span class="fixedwidth">yourpass</span>, enter the following command to store
+ the data under the alias <span class="fixedwidth">youralias</span>.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ ./extkeytool -importkey -keystore yourstore
+ -alias youralias -storepass yourpass -keyfile
+ yourkey.der.pkcs8 -certfile cert.bundle -provider
+ org.bouncycastle.jce.provider.BouncyCastleProvider</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>You can verify that the import was successful by
+ listing entry. Use the command below.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ keytool -list -v -keystore yourstore -alias
+ youralias</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>Remember to delete <span class="fixedwidth">yourkey.der.pkcs8</span>, as it
+ contains your unencrypted private key.</p>
+ </li>
+ </ol>
+
+ <p><b>If you are starting from scratch and do not yet have
+ a certificate/key pair:</b></p>
+
+ <ol type="1">
+ <li>
+ <p>Generate an RSA private key. Use the command below,
+ substituting <span class="fixedwidth">yourkey</span> with an appropriate name
+ to use to refer to the key.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ openssl genrsa -des3 -out yourkey.enckey
+ 1024</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>The following command generates a Certificate
+ Signing Request, which should be communicated to a
+ Certificate Authority.</p>
+
+ <blockquote>
+ <p><span class="fixedwidth">$ openssl req -new -key
+ yourkey.enckey</span></p>
+ </blockquote>
+ </li>
+
+ <li>
+ <p>The Certificate Authority should respond with a
+ PEM-encoded X509 certificate. Set the <span class="fixedwidth">mod_ssl</span>
+ <span class="fixedwidth">SSLCertificateKeyFile</span> directive to point to
+ the key file you just created and the
+ <span class="fixedwidth">SSLCertificateFile</span> directive to point to file
+ containing the certificate issued by the Certificate
+ Authority. Previous sections explaion how to share the
+ key/certificate pair with a Java keystore.</p>
+ </li>
+ </ol>
+ </blockquote>
+ </blockquote>
+
+ <br>
+ <h4><a name="5.c."></a>5.c. The Attribute Resolver</h4>
+
+ <blockquote>
+ <p>Shibboleth provides a powerful attribute resolver that allows
+ origins to quickly configure the retrieval of simple attributes
+ from standard types of attribute stores. The resolver is configured
+ using an xml file wich should be pointed to with the <span
+ class="fixedwidth">edu.internet2.middleware.shibboleth.aa.
+ attrresolv.AttributeResolver.ResolverConfig</span> propety in <span
+ class="fixedwidth">origin.properties</span> as described in
+ section <a href="#4.a.">4.a</a>. For more complex attributes or
+ those that require processing before release, customized Java
+ classes will need to be written. For more information,
+ consult the programmer's guide.</p>
+
+ <p>The resolver is essentially a directed graph from attribute
+ definitions to data connectors. The data connectors pull data, in
+ the form of attributes, from external data sources. The attribute
+ definitions then process this data into a from suitable for use
+ by Shibboleth. This procedure can be as simple as taking an
+ unmodified string value from a data connector and tagging it with
+ a name or can include arbitrarily complex business rules.</p>
+
+ <p>The <span class="fixedwidth">resolver.xml</span> file that is
+ pointed to by <span class="fixedwidth">origin.properties</span>
+ consists of zero or more attribute definitions followed by zero or
+ more data connectors. Each attribute definition consists of an
+ identifier corresponding to the URN of the attribute, and optional
+ references to data connectors on which it depends. Each data connector
+ consists of a string identifier which is used by attribute
+ definitions that refer to it, and one or more elements specific to
+ the configuration of that data connector.</p>
+
+ <p>Shibboleth comes with two attribute definitions provided in
+ version 1.0: the <span
+ class="fixedwidth">SimpleAttributeDefinition</span>, which acts as
+ a basic proxy for attributes supplied by data connectors with some
+ name conversion and attribute scoping added, and a <span
+ class="fixedwidth">CustomAttributeDefinition</span>, which can be
+ used to configure user-created attribute definition plugins.
+ Similarly, Shibboleth 1.0 comes with two data connectors: the
+ <span class="fixedwidth">JNDIDirectoryDataConnector</span>, which
+ pulls data from any source for which there is a JNDI Directory
+ Context implementation, including LDAP, NDS, etc., and the <span
+ class="fixedwidth">CustomDataConnector</span>, which is used to
+ configure user-created data connector plugins.</p>
+
+ <p>A detailed explanation of each configuration option for the
+ provided connectors follows:</p>
+
+ <p><span class="fixedwidth">JNDIDirectoryDataConnector</span>:</p>
+
+ <dl>
+ <dd class="attribute">
+ <span class="fixedwidth">id = <string></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies a unique, textual name for the connector used by
+ attribute definitions to refer to and use it to build
+ attributes. Contained within the <span
+ class="fixedwidth">JNDIDirectoryDataConnector</span>
+ element.</p>
+ </dd>
+
+ <dd class="attribute">
+ <span class="fixedwidth"><Property name="<name>" value="<value>"/></span>
+ </dd>
+
+ <dd class="value">
+ <p>An element of the element <span
+ class="fixedwidth">JNDIDirectoryDataConnector</span>.
+ Specifies a set of name/value pairs that are used to configure
+ the JNDI Directory Context. This list of name/value pairs is
+ defined by the context itself, but is specified within <span
+ class="fixedwidth">resolver.xml</span>. Refer to the <a
+ href="http://http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi
+ /shibboleth/java/src/conf/resolver.ldap.xml">Shibboleth
+ CVS</a> for an example of names and values used to connect to
+ an LDAP directory.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth"><Search></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>An element of the element <span
+ class="fixedwidth">JNDIDirectoryDataConnector</span>. This
+ element defines the DN filter used to perform the LDAP search.
+ The search string must return no more than one result.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth"><Controls></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>An element of the element <span
+ class="fixedwidth">Search</span>. This
+ element grants some fine-grained control over the LDAP API
+ calls.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth"><cacheTime "<seconds>"/></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>An element of the element <span
+ class="fixedwidth">JNDIDirectoryDataConnector</span>.
+ Specifies an optional duration in <span
+ class="fixedwidth">seconds</span> for which the attribute
+ resolver may cache information retrieved from this
+ connector.</p>
+ </dd>
+ </dl>
+
+ <p>A representation of a properly constructed <span
+ class="fixedwidth">JNDIDirectoryDataConnector</span> element would
+ look like:</p>
+
+ <blockquote><span class="fixedwidth">
+ <JNDIDirectoryDataConnector id="directory"><br>
+ <Search filter="cn=%PRINCIPAL%"><br>
+ <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" /><br>
+ </Search><br>
+ <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" /><br>
+ <cacheTime="2400"/><br>
+ </JNDIDirectoryDataConnector>
+ </span></blockquote>
+
+ <p><span class="fixedwidth">SimpleAttributeDefinition</span>:</p>
+
+ <dl>
+ <dd class="attribute">
+ <span class="fixedwidth">id = <string></span>
+ </dd>
+
+ <dd class="value">
+ <p>Specifies a unique, textual name for the attribute which is
+ used as the attribute's name when it is sent over the wire by
+ Shibboleth. Contained within the <span
+ class="fixedwidth">SimpleAttributeDefinition</span>
+ element.</p>
+
+ <p>Attributes are named in the format <span
+ class="fixedwidth"><URI>#<attributename></span>;
+ for example, <span
+ class="fixedwidth">urn:mace:dir:eduperson#
+ eduPersonScopedAffiliation</span>.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth"><AttributeDependency / DataConnectorDependency requires="<id>"/></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>An element of the element <span
+ class="fixedwidth">SimpleAttributeDefinition</span>, which may
+ contain 0 or more of either <span
+ class="fixedwidth">AttributeDependency</span> or <span
+ class="fixedwidth">DataConnectorDependency</span>. These
+ specify attributes and data connectors that can be utilized by
+ this attribute definition. Each of these elements must
+ contain a <span class="fixedwidth">requires</span> statement
+ which this attribute definition can then use to build its
+ value.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth">smartScope = "<domain>"</span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifes a domain scope to be attached to the attribute. If
+ the value of the attribute as retrieved from the data
+ connector includes a pre-existing scope (<span
+ class="fixedwidth">bob@foo.edu</span>), that scope is used
+ instead. Contained within the <span
+ class="fixedwidth">SimpleAttributeDefinition</span>
+ element.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth">sourceName = "<string>"</span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>Specifies a different source attribute name to be used in
+ calls to the data connector, while the name on the wire will
+ be the specified <span class="fixedwidth">id</span>. This
+ would be useful to send a local UniversityID attribute as
+ eduPersonPrincipalName. If not supplied, the connector
+ tokenizes the <span class="fixedwidth">id</span> field and
+ uses the section following the <span
+ class="fixedwidth">#</span> to query data connectors.
+ Contained within the <span
+ class="fixedwidth">SimpleAttributeDefinition</span>
+ element.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth"><cacheTime "<seconds>"/></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>An element of the element <span
+ class="fixedwidth">SimpleAttributeDefinition</span>.
+ Specifies an optional duration in <span
+ class="fixedwidth">seconds</span> for which the attribute
+ resolver may cache this attribute for use in additional
+ assertions.</p>
+ </dd>
+
+ <dd class="attributeopt">
+ <span class="fixedwidth"><lifeTime "<seconds>"/></span>
+ </dd>
+
+ <dd class="valueopt">
+ <p>An element of the element <span
+ class="fixedwidth">SimpleAttributeDefinition</span>.
+ Specifies in the attribute assertion how long the attribute
+ should be cached and retained by the target upon receipt.
+ Federations and trust agreements may have some bearing on the
+ population and use of this field.</p>
+ </dd>
+ </dl>
+
+ <p>A representation of a properly constructed <span
+ class="fixedwidth">SimpleAttributeDefinition</span> element would
+ look like:</p>
+
+ <blockquote><span class="fixedwidth">
+ <SimpleAttributeDefinition id="urn:mace:dir:eduperson#eduPersonPrincipalName" smartScope="shibdev.edu" sourceName="universityPerson"><br>
+ <DataConnectorDependency requires="dataConnector"/><br>
+ <AttributeDependency requires="urn:mace:dir:eduperson#eduPersonAffiliation"/><br>
+ <cacheTime="600"/><br><br>
+ <lifeTime="3600"/><br><br>
+ </SimpleAttributeDefinition>
+ </span></blockquote>
+
+ <p>A properly formed <span class="fixedwidth">resolver.xml</span>
+ file to automatically generate a simple response for EPPN may take
+ the form:</p>
+
+ <blockquote><span class="fixedwidth">
+ <AttributeResolver xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:mace:shibboleth:resolver:1.0" xsi:schemaLocation="urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd"><br>
+ <br>
+ <SimpleAttributeDefinition id="urn:mace:dir:eduperson#eduPersonPrincipalName" smartScope="shibdev.edu"><br>
+ <DataConnectorDependency requires="echo"/><br>
+ </SimpleAttributeDefinition><br>
+ <br>
+ <CustomDataConnector id="echo"
+ class="edu.internet2.middleware.shibboleth.aa.attrresolv.provider.SampleConnector" /><br>
+ </AttributeResolver>
+ </span></blockquote>
+
+ <p>There are additional examples of <span class="fixedwidth">resolver.xml</span> files provided in the <a href="http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi/shibboleth/java/src/conf/">Shibboleth CVS</a>.</p>
+
+ </blockquote>
+
+ <br>
+ <br>
+ <hr>
+ <br>
+
+
+ <h3><a name="6."></a>6. Troubleshooting</h3>
+
+ <p>This section provides basic information about testing,
+ logging, and error handling for Shibboleth origins. This
+ information is not intended to be comprehensive, but instead
+ rudimentary guidelines for basic configuration tests and
+ problems. For more detailed information or answers to specific
+ problems not addressed in this section, please mail <a href=
+ "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
+ with a thorough description of errors and configurations
+ used.</p>
+
+ <h4><a name="6.a."></a>6.a. Basic Testing</h4>
+
+ <blockquote>
+ <p>Internet2 provides a basic target that can be used to test
+ origin setup functionality. After your origin is recognized
+ by InCommon, simply use any browser to access <a href=
+ "https://wayf.internet2.edu/shibboleth/sample.jsp">https://wayf.internet2.edu/shibboleth/sample.jsp</a>.
+ Select your origin's name and follow the login process as a
+ user would. Note that SSL must be used, and both the HS and
+ AA must be fully configured.</p>
+
+ <p>The test target will then display a simple page which
+ includes the basic information sent to it by your origin and
+ the authentication rules it is using.</p>
+
+ <p><b>For information regarding specific error messages that
+ may be generated if the origin does not work successfully,
+ please refer to section <a href="#6.c.">6.c</a>.</b></p>
+ </blockquote>
+
+ <h4><a name="6.b."></a>6.b. Logging</h4>
+
+ <blockquote>
+ <p>Shibboleth's origin components log various operations
+ which may prove useful for auditing, testing, and security
+ purposes. This data is sent through <span class="fixedwidth">log4j</span>'s standard
+ mechanism. The location of
+ the log file, the level at which the log is output, the
+ formatting of the logs, and many more options may be
+ configured by editing
+ <span class="fixedwidth">/WEB-INF/classes/conf/log4j.properties</span>. By default, it is
+ setup to log to the console of the servlet container, with a
+ level of <span class="fixedwidth">WARN</span>, but there is also a commented out
+ example in the file to give a possible alternate
+ configuration.</p>
+ </blockquote>
+
+ <h4><a name="6.c."></a>6.c. Common Problems</h4>
+
+ <blockquote>
+ <p>A knowledge base is being developed in the <a
+ href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.html">
+ Shibboleth Deployer's FAQ</a>. Please mail <a href=
+ "mailto:mace-shib-users@internet2.edu">mace-shib-users@
+ internet2.edu</a> with any additional questions or problems
+ encountered that are not answered by this basic guide.</p>
+ </blockquote>
+ </body>
+</html>
+