doc/DEPLOY-GUIDE-ORIGIN.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2
   3 <html>
   4   <head>
   5     <meta name="generator" content=
   6     "HTML Tidy for Mac OS X (vers 1st January 2002), see www.w3.org">
   7
   8     <title>Shibboleth Origin Deployment Guide</title>
   9     <meta http-equiv="Content-Type" content=
  10     "text/html; charset=utf-8">
  11     <style type="text/css">
  12
  13 html
  14 {
  15 background-color: #FFFFFF;
  16 color: #000000;
  17 margin: .5em;
  18 }
  19 a:visited
  20 {
  21 color: #999999;
  22 }
  23 a:link
  24 {
  25 color: #990000;
  26 }
  27 a:active
  28 {
  29 color: #440000;
  30 }
  31 dl
  32 {
  33 background-color: #DDDDDD;
  34 background-image: none;
  35 margin: 5px;
  36 padding: 0px;
  37 border-style: solid;
  38 border-bottom-width: 2px;
  39 border-top-width: 2px;
  40 border-left-width: 2px;
  41 border-right-width: 2px;
  42 }
  43 dt
  44 {
  45 background-color: #DDDDDD;
  46 background-image: none;
  47 margin: 1px;
  48 padding: 1px;
  49 }
  50 dd
  51 {
  52 background-color: #DDDDDD;
  53 background-image: none;
  54 margin: 0px;
  55 padding: 1px;
  56 }
  57 .attribute
  58 {
  59 font-size: 115%;
  60 font-color: #000000;
  61 text-align: left;
  62 background-color: #DDDDDD;
  63 border: 1px black inset;
  64 background-image: none;
  65 margin: 0px;
  66 padding: 2px;
  67 }
  68 .value
  69 {
  70 font-color: #000000;
  71 text-align: left;
  72 background-color: #EEEEEE;
  73 background-image: none;
  74 padding-top: 0em;
  75 padding-bottom: 0.5em;
  76 padding-right: 1em;
  77 padding-left: 5em;
  78 border-style: solid;
  79 border-bottom-width: none;
  80 border-top-width: none;
  81 border-left-width: 1px;
  82 border-right-width: 1px;
  83 }
  84 .attributeopt
  85 {
  86 font-size: 115%;
  87 font-color: #000000;
  88 text-align: left;
  89 background-color: #BCBCEE;
  90 border: 1px black inset;
  91 background-image: none;
  92 margin: 0px;
  93 padding: 2px;
  94 }
  95 .valueopt
  96 {
  97 font-color: #000000;
  98 text-align: left;
  99 background-color: #DDDDFF;
 100 background-image: none;
 101 padding-top: 0em;
 102 padding-bottom: 0.5em;
 103 padding-right: 1em;
 104 padding-left: 5em;
 105 border-style: solid;
 106 border-bottom-width: none;
 107 border-top-width: none;
 108 border-left-width: 1px;
 109 border-right-width: 1px;
 110 }
 111 .attributelong
 112 {
 113 font-size: 85%;
 114 font-color: #000000;
 115 text-align: left;
 116 background-color: #DDDDDD;
 117 border: 1px black inset;
 118 background-image: none;
 119 margin: 0px;
 120 padding: 2px;
 121 }
 122 .attributeoptlong
 123 {
 124 font-size: 85%;
 125 font-color: #000000;
 126 text-align: left;
 127 background-color: #BCBCEE;
 128 border: 1px black inset;
 129 background-image: none;
 130 margin: 0px;
 131 padding: 2px;
 132 }
 133 .demo
 134 {
 135 background-color: #EEEEEE;
 136 padding: 3px;
 137 }
 138 .fixed
 139 {
 140 font-family: monospace;
 141 font-size: 90%;
 142 font-color: #121212;
 143 }
 144 .feature
 145 {
 146 color: #00FF00
 147 }
 148
 149   </style>
 150   </head>
 151
 152   <body link="red" vlink="red" alink="black" bgcolor="white">
 153     <center>
 154       <h2>Shibboleth Origin Deployment Guide</h2>
 155     </center>
 156         Shibboleth Origin Deployment Guide<br>
 157         Shibboleth Version 1.0.1<br />
 158         July 25, 2003<br />
 159
 160         <h3>This version of the deploy guide is for Shibboleth v1.0.1. For documentation
 161         related to prior versions of Shibboleth, please consult the appropriate branch
 162         in the Shibboleth CVS.</h3>
 163
 164     <h3>Federations have been abstracted out from the Shibboleth
 165     documentation.  For further information on using Shibboleth in a
 166     federation, refer to the federation guide.</h3>
 167
 168         <p>Shibboleth v1.0.1 is stable and secure enough to deploy in production
 169         scenarios. It is backward compatible with 1.0 in all respects, including
 170         configuration, but some older commands have been deprecated or replaced.</p>
 171
 172         <p>Features and changes specific to 1.0.1 are marked with <span class="feature">
 173         [1.0.1]</span></p>
 174
 175         <h4>Major New Features in 1.0 and 1.0.1</h4>
 176         This new release contains many improvements and enhancements, including:
 177
 178         <h5>Federation Support</h5>
 179         <ol>
 180             <li>Federation and trust support has been substantially extended. Federation
 181             structures are now defined. The set of metadata collected and managed by
 182             each Federation is more fully defined. The configuration values assigned by
 183             a Federation are now identified. </li>
 184             <li>There is some support for targets to be members of multiple federations;
 185             this support will continue to evolve. When a browser user arrives, a target
 186             will determine which federation their origin belongs to, and then use the
 187             trust fabric associated with that Federation.</li>
 188             <li>Better support for flexible and bilateral trust agreements. A key
 189             specific to an origin site can be used to vallidate its signature.</li>
 190             <li>This version contains a significantly more mature security
 191             implementation, and should meet the security requirements of typical sites.</li>
 192         </ol>
 193         <h5>Origin</h5>
 194         <ol>
 195             <li>The Attribute Authority has a powerful new attribute resolver. Simple
 196             scenarios (using a string attribute stored in ldap) can be accomplished by
 197             merely editing a configuration file. Java classes may still be written for
 198             more complex evaluations (eg retrieving information from multiple disparate
 199             repositories, and computing the SAML attribute using business rules). This
 200             should greatly simplify the process of configuring the AA to support
 201             additional general attributes.</li>
 202             <li>Support for a runtime-derived per-requester persistent identifier
 203             attribute to support anonymous personalization by targets has been added via
 204             an attribute plugin. <span class="feature">[1.0.1]</span></li>
 205             <li>Specialized deployments without privacy needs can configure identity-based
 206             handles interoperable with other SAML deployments. <span class="feature">
 207             [1.0.1]</span></li>
 208         </ol>
 209         <h5>Target</h5>
 210         <ol>
 211             <li>Significantly more flexibility in configuring targets to ensure
 212             robustness. Failover and redundant configurations are now supported.</li>
 213             <li>The SHAR may now optionally store its session and attribute cache in a
 214             back-end database in addition to the previously available in-memory option.
 215             This would allow a site to run an apache server farm, with multiple SHARs,
 216             supporting the same set of sessions.</li>
 217             <li>Federation supplied files (sites.xml and trust.xml) are now refreshed in
 218             a much more robust manner.</li>
 219             <li>The SHAR can be configured to request specific attributes from the
 220             Origin.</li>
 221             <li>The SHAR can use TCP sockets when responding to the Apache module, for
 222             specialized deployment behind firewalls. <span class="feature">[1.0.1]</span>
 223             </li>
 224             <li>Attribute acceptance policies have been greatly enhanced, and are now
 225             used to configure all aspects of attribute handling by the target, except
 226             for requesting specific attributes by sitename. Adding attributes now takes
 227             place in one configuration step. <span class="feature">[1.0.1]</span> </li>
 228             <li>Support for Apache 1.3 on Windows NT/2000/XP/2003 has been added.
 229             <span class="feature">[1.0.1]</span></li>
 230             <li>Microsoft IIS web server support has been added via an ISAPI filter and
 231             extension. <span class="feature">[1.0.1]</span></li>
 232         </ol>
 233         <h5>Miscellaneous</h5>
 234         <ol>
 235             <li>Origin sites can configure a value to describe the type of
 236             authentication mechanism used at the origin site(e.g. password, Kerberos,
 237             PKI, etc.). This value is made available on the target side as Shib-Authentication-Method.</li>
 238             <li>Various improvements to error handling. Origin sites are now able to
 239             supply an error URL and contact information to a federation. When a target
 240             encounters an error, it can include this information in the error page.</li>
 241             <li>Local time string values are now used in log files.</li>
 242             <li>Internationalization support has been extended.</li>
 243         </ol>
 244
 245     <p>Before starting, please sign up for all applicable <a href=
 246     "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
 247     mailing lists</a>. Announcements pertinent to Shibboleth
 248     deployments and developments and resources for deployment
 249     assistance can be found here.</p>
 250
 251     <p>Please send any questions, concerns, or eventual confusion
 252     to <a href="mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
 253     This should include, but not be limited to, questions about the
 254     documentation, undocumented problems, installation or
 255     operational issues, and anything else that arises. Please
 256     ensure that you have the <a href=
 257     "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
 258     .tarball</a> for your operating system.</p>
 259     <br>
 260     <hr>
 261     <br>
 262     <br>
 263
 264
 265     <h3><a name="TOC"></a>Shibboleth Origin -- Table of Contents</h3>
 266     <br>
 267
 268
 269     <ol type="1">
 270       <li>
 271         <h4><a href="#1."><font color="black">Shibboleth
 272         Overview</font></a></h4>
 273
 274         <ol type="a">
 275           <li><a href="#1.a."><font color=
 276           "black">Origin</font></a></li>
 277
 278           <li><a href="#1.b."><font color=
 279           "black">Target</font></a></li>
 280
 281           <li><a href="#1.c."><font color=
 282           "black">WAYF</font></a></li>
 283
 284           <li><a href="#1.d."><font color=
 285           "black">Federations</font></a></li>
 286         </ol>
 287       </li>
 288
 289       <li>
 290         <h4><a href="#2."><font color=
 291         "black">Planning</font></a></h4>
 292
 293         <ol type="a">
 294           <li><a href="#2.a."><font color=
 295           "black">Requirements</font></a></li>
 296
 297           <li><a href="#2.b."><font color="black">Join a
 298           Federation</font></a></li>
 299
 300           <li><a href="#2.c."><font color="black">Security
 301           Considerations</font></a></li>
 302
 303           <li><a href="#2.d."><font color="black">Server
 304           Certs</font></a></li>
 305
 306           <li><a href="#2.e."><font color="black">Attribute Release
 307           Policies</font></a></li>
 308
 309           <li><a href="#2.f."><font color="black">Designate
 310           Contacts</font></a></li>
 311
 312           <li><a href="#2.g."><font color="black">Browser
 313           Requirements</font></a></li>
 314
 315           <li><a href="#2.h."><font color=
 316           "black">Clocks</font></a></li>
 317
 318           <li><a href="#2.i."><font color="black">Other
 319           Considerations</font></a></li>
 320         </ol>
 321       </li>
 322
 323       <li>
 324         <h4><a href="#3."><font color=
 325         "black">Installation</font></a></h4>
 326
 327         <ol type="a">
 328           <li><a href="#3.a."><font color="black">Software
 329           Requirements</font></a></li>
 330
 331           <li><a href="#3.b."><font color="black">Deploy HS and
 332           AA</font></a></li>
 333
 334         </ol>
 335       </li>
 336
 337       <li>
 338         <h4><a href="#4."><font color="black">Getting
 339         Running</font></a></h4>
 340
 341         <ol type="a">
 342           <li><a href="#4.a."><font color="black">Basic
 343           Configuration</font></a></li>
 344
 345           <li>
 346             <a href="#4.b."><font color="black">Key Generation and
 347             Certificate Installation</font></a>
 348
 349           </li>
 350
 351           <li><a href="#4.c."><font color="black">Linking the
 352           Authentication System to the HS</font></a>
 353
 354             <ol type="i">
 355               <li><a href="#4.c.i."><font color="black">Enabling client
 356               certificate authentication</font> <font color="#5555EE">(optional)</font></a></li>
 357             </ol>
 358           </li>
 359
 360           <li><a href="#4.d."><font color="black">Establishing
 361           default ARP's for the origin community</font></a></li>
 362
 363                   <li><a href="#4.e."><font color="black">Modifying the
 364                   default Attribute Resolver configuration</font></a></li>
 365
 366         </ol>
 367       </li>
 368
 369       <li>
 370         <h4><a href="#5."><font color="black">Advanced
 371         Configuration</font></a></h4>
 372
 373         <ol type="a">
 374           <li>
 375             <a href="#5.a."><font color="black">ARP
 376             Overview</font></a>
 377
 378             <ol type="i">
 379               <li><a href="#5.a.i."><font color="black">ARP
 380               Processing</font></a></li>
 381
 382               <li><a href="#5.a.ii."><font color="black">ARP
 383               Syntax</font></a></li>
 384             </ol>
 385               <li><a href="#5.b."><font color="black">Sharing
 386               certificate/key pairs between Apache and Java
 387               keystores</font> <font color="#5555EE">(optional)</font></a></li>
 388           <li><a href="#5.c."><font color="black">The Attribute Resolver</font></a></li>
 389           <li><a href="#5.d."><font color="black">Local Error Page</font></a></li>
 390         </ol>
 391       </li>
 392
 393       <li>
 394         <h4><a href="#6."><font color=
 395         "black">Troubleshooting</font></a></h4>
 396
 397         <ol type="a">
 398           <li><a href="#6.a."><font color="black">Basic
 399           Testing</font></a></li>
 400
 401           <li><a href="#6.b."><font color=
 402           "black">Logging</font></a></li>
 403
 404           <li><a href="#6.c."><font color="black">Common
 405           Problems</font></a></li>
 406         </ol>
 407       </li>
 408     </ol>
 409     <br>
 410     <hr>
 411     <br>
 412
 413
 414     <h3><a name="1."></a>1. Shibboleth Overview</h3>
 415
 416     <p>Shibboleth is a system designed to exchange attributes
 417     across realms for the primary purpose of authorization. It
 418     provides a secure framework for one organization to transmit
 419     attributes about a web-browsing individual across security
 420     domains to another institution. In the primary usage case, when
 421     a user attempts to access a resource at a remote domain, the
 422     user's own home security domain can send certain information
 423     about that user to the target site in a trusted exchange. These
 424     attributes can then be used by the resource to help determine
 425     whether to grant the user access to the resource. The user may
 426     have the ability to decide whether to release specific
 427     attributes to certain sites by specifying personal Attribute
 428     Release Policies (ARP's), effectively preserving privacy while
 429     still granting access based on trusted information.</p>
 430
 431     <p>When a user first tries to access a resource protected by
 432     Shibboleth, they are redirected to a service which asks the
 433     user to specify the organization from which they want to
 434     authenticate. If the user has not yet locally authenticated to
 435     a WebISO service, the user will then be redirected to their
 436     home institution's authentication system. After the user
 437     authenticates, the Shibboleth components at the local
 438     institution will generate a temporary reference to the user,
 439     known as a handle, for the individual and send this to the
 440     target site. The target site can then use the handle to ask for
 441     attributes about this individual. Based on these attributes,
 442     the target can decide whether or not to grant access to the
 443     resource. The user may then be allowed to access the requested
 444     materials.</p>
 445
 446     <p>There are several controls on privacy in Shibboleth, and
 447     mechanisms are provided to allow users to determine exactly
 448     which information about them is released. A user's actual
 449     identity isn't necessary for many access control decisions, so
 450     privacy often is needlessly compromised. Instead, the resource
 451     often utilizes other attributes such as faculty member or member
 452     of a certain class. While these are commonly determined using
 453     the identity of the user, Shibboleth provides a way to mutually
 454     refer to the same principal without revealing that principal's
 455     identity. Because the user is initially known to the target site
 456     only by a randomly generated temporary handle, if sufficient,
 457     the target site might know no more about the user than that the
 458     user is a member of the origin organization. This handle should
 459     never be used to decide whether or not to grant access, and is
 460     intended only as a temporary reference for requesting
 461     attributes.</p>
 462
 463     <h4><a name="1.a."></a>1.a. Origin</h4>
 464
 465     <blockquote>
 466       <p>There are four primary components to the origin side in
 467       Shibboleth: the Attribute Authority (AA), the Handle Service
 468       (HS), the directory service, and the local sign-on system
 469       (SSO). The AA and HS are provided with Shibboleth, and an
 470       open-source WebISO solution, Pubcookie, can be obtained from
 471       www.pubcookie.org; the directory is provided by the origin
 472       site. Shibboleth is able to interface with a directory
 473       exporting an LDAP interface containing user attributes, and is
 474       designed such that programming interfaces to other
 475       repositories should be readily implemented. Shibboleth relies
 476       on standard web server mechanisms to trigger local
 477       authentication. A .htaccess file can be easily used to trigger
 478       either the local WebISO system or the web server's own Basic
 479       Auth mechanism, which will likely utilize an enterprise
 480       authentication system, such as Kerberos.</p>
 481
 482       <p>From the origin site's point of view, the first contact
 483       will be the redirection of a user to the handle service,
 484       which will then consult the SSO system to determine whether
 485       the user has already been authenticated. If not, then the
 486       browser user will be asked to authenticate, and then sent
 487       back to the target URL with a handle bundled in an attribute
 488       assertion. Next, a request from the Shibboleth Attribute
 489       Requester (SHAR) will arrive at the AA which will include the
 490       previously mentioned handle. The AA then consults the ARP's
 491       for the directory entry corresponding to the handle, queries
 492       the directory for these attributes, and releases to the SHAR
 493       all attributes the SHAR is entitled to know about that
 494       user.</p>
 495     </blockquote>
 496
 497     <h4><a name="1.b."></a>1.b. Target</h4>
 498
 499     <blockquote>
 500       <p>There are three primary components to the target side in
 501       Shibboleth: the Shibboleth Indexical Reference Establisher
 502       (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
 503       resource manager (RM). An implementation of each of these is
 504       included in the standard Shibboleth distribution. These
 505       components are intended to run on the same web server.</p>
 506
 507       <p>From the target's point of view, a browser will hit the RM
 508       with a request for a Shibboleth-protected resource. The RM
 509       then allows the SHIRE to step in, which will use the WAYF to
 510       acquire the name of a handle service to ask about the user.
 511       The handle service (HS) will then reply with a SAML
 512       authentication assertion containing a handle, which the SHIRE
 513       then hands off to the SHAR. The SHAR uses the handle and the
 514       supplied address of the corresponding attribute authority
 515       (AA) to request all attributes it is allowed to know about
 516       the handle. The SHAR performs some basic validation and
 517       analysis based on attribute acceptance policies (AAP's).
 518       These attributes are then handed off to the RM, which is
 519       responsible for using these attributes to decide whether to
 520       grant access.</p>
 521     </blockquote>
 522
 523     <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
 524
 525     <blockquote>
 526       <p>The WAYF service can be either outsourced and operated by
 527       a federation or deployed as part of the SHIRE. It is responsible
 528       for allowing a user to associate themself with an institution
 529       of their specification, then redirecting the user to the
 530       known address for the handle service of that institution.</p>
 531     </blockquote>
 532
 533     <h4><a name="1.d."></a>1.d. Federations</h4>
 534
 535     <blockquote>
 536       <p>A Shibboleth federation provides part of the underlying trust
 537       required for function of the Shibboleth architecture. A federation
 538       is a group of organizations(universities, corporations,
 539       content providers, etc.) who agree to exchange attributes
 540       using the SAML/Shibboleth protocols and abide by a common set
 541       of policies and practices. In so doing, they must implicitly
 542       or explicitly agree to a common set of guidelines. Joining a
 543       federation is not explicitly necessary for operation of Shibboleth,
 544       but it dramatically expands the number of targets and origins
 545       that can interact without defining bilateral agreements
 546       between all these parties.</p>
 547
 548       <p>A federation can be created in a variety of formats and trust
 549       models, but must provide a certain set of services to federation
 550       members. It needs to supply a registry to process
 551       applications to the federation and distribute membership
 552       information to the origin and target sites. This must include
 553       distribution of the PKI components necessary for trust
 554       between origins and targets. There also needs to be a set of
 555       agreements and best practices defined by the federation governing
 556       the exchange, use, and population of attributes before and
 557       after transit, and there should be a way to find information
 558       on local authentication and authorization practices for federation
 559       members.</p>
 560     </blockquote>
 561     <br>
 562     <br>
 563     <br>
 564     <hr>
 565     <br>
 566
 567
 568     <h3><a name="2."></a>2. Planning</h3>
 569
 570     <p>There are several essential elements that must be present in
 571     the environment to ensure Shibboleth functions well, both
 572     political and technical. Shibboleth is entirely written in
 573     Java on the origin side. These are the recommendations and
 574     requirements for a successful implementation of a Shibboleth
 575     origin.</p>
 576
 577     <h4><a name="2.a."></a>2.a. Requirements</h4>
 578
 579     <ul>
 580       <li>
 581         <p>A common institutional directory service should be
 582         operational; Shibboleth comes with LDAP capabilities
 583         built in, and the Attribute Authority has a Java API which
 584         will allow specification of interfaces with legacy
 585         directories. This is discussed further in <a href=
 586         "#4.d.">section 4.d</a>.</p>
 587       </li>
 588
 589       <li>
 590         <p>A method to authenticate browser users must be in place,
 591         preferably in the form of an enterprise authentication
 592         service. Some form of an SSO or a WebISO service is not
 593         explicitly necessary for Shibboleth; however, it is highly
 594         recommended. Implementation details of this are discussed in
 595         <a href="#4.c.">section 4.c</a>.</p>
 596       </li>
 597
 598       <li>
 599         <p>Shibboleth is known to work on Linux and Solaris, but
 600         should function on any platform that has a Tomcat
 601         implementation.</p>
 602       </li>
 603
 604       <li>
 605         <p>It is recommended that a web server must be deployed that
 606         can host Java servlets and Tomcat, although not explicitly
 607         necessary, as Tomcat can still host an origin without it.</p>
 608       </li>
 609     </ul>
 610
 611     <h4><a name="2.b."></a>2.b. Join a Federation</h4>
 612
 613     <blockquote>
 614       <p>While it is not necessary for a target or origin to join a
 615       federation, doing so greatly facilitates the implementation of
 616       multilateral trust relationships. Each federation will have a
 617       different application process. When an origin is accepted into a
 618       federation, its information is added to the sites file used by the
 619       WAYF and target sites.</p>
 620
 621       <p><b>It may be necessary to join multiple federations
 622       depending on the sites with whom you wish to exchange
 623       attributes and the terms under which these interactions will
 624       take place.  An origin site exists within the context of a
 625       single federation, while a single target may accept assertions
 626       issued by multiple federations if they are all recognized by
 627       the SHAR.  If an organization wishes to be a member of
 628       multiple federations, it must run a separate origin site for
 629       each federation, including a separate AA and HS.</b></p>
 630
 631       <p>Attribute release and acceptance policies, the use and
 632       caching of attributes, and definition of commonly traded
 633       attributes are examples of specifications a federation may
 634       make.  For more information on federations, please refer to
 635       the Deployer's Guide to Federations and the Shibboleth v1.0
 636       architectural document.</p>
 637     </blockquote>
 638
 639     <h4><a name="2.c."></a>2.c. Security Considerations</h4>
 640
 641     <blockquote>
 642       <p>Shibboleth's protocols and software have been extensively
 643       engineered to provide protection against many attacks.
 644       However, the most secure protocol can be compromised if it is
 645       placed in an insecure environment. To ensure Shibboleth is as
 646       secure as possible, there are several recommended security
 647       precautions which should be in place at local sites.</p>
 648
 649       <ol type="i">
 650         <li>
 651           <p>SSL use is optional for origin sites. Federation guidelines
 652           should be considered when determining whether to
 653           implement SSL, and, in general, SSL should be used for
 654           interactions with client machines to provide the
 655           necessary authentication and encryption to ensure
 656           protection from man-in-the-middle attacks. It is strongly
 657           suggested that all password traffic or similarly
 658           sensitive data should be SSL-protected. Assessment of the
 659           risk tradeoff against possible performance degradation
 660           should be performed for all applications.</p>
 661         </li>
 662
 663         <li>
 664           <p>Many other attacks can be made on the several
 665           redirection steps that Shibboleth takes to complete
 666           attribute transfer. The best protection against this is
 667           safeguarding the WAYF service and ensuring that rogue
 668           targets and origins are not used, generally by
 669           development of the trust model underneath Shibboleth.
 670           Shibboleth also leverages DNS for security, which is not
 671           uncommon, but attacks concerning bad domain information
 672           should be considered.</p>
 673         </li>
 674
 675         <li>
 676           <p>Information regarding origin users is generally
 677           provided by the authoritative enterprise directory, and
 678           the acceptance of requests from target applications can
 679           be carefully restricted to ensure that all requests the
 680           SHAR performs are authorized and all information the
 681           origin provides is accurate. Proper security measures
 682           should also be in place on directory access and
 683           population(see <a href=
 684           "http://www.georgetown.edu/giia/internet2/ldap-recipe/#AccessControl">
 685           Access Control</a> in the <a href=
 686           "http://www.georgetown.edu/giia/internet2/ldap-recipe/">LDAP
 687           recipe</a> for more information). Use of plaintext
 688           passwords is strongly advised against.</p>
 689         </li>
 690
 691         <li>
 692           <p>Server platforms should be properly secured,
 693           commensurate with the level that would be expected for a
 694           campus' other security services, and cookie stores on
 695           client machines should be well protected.</p>
 696         </li>
 697       </ol>
 698     </blockquote>
 699
 700     <h4><a name="2.d."></a>2.d. Server Certs</h4>
 701
 702     <blockquote>
 703       <p>In the Shibboleth architecture, the SHIRE, SHAR, HS, and AA
 704       must all have various client and/or server certificates for use in
 705       signing assertions and creating SSL channels. These should be
 706       issued by a commonly accepted CA, which may be stipulated by some
 707       Federation rules. Different federations may require the use of
 708       different CA's.</p>
 709     </blockquote>
 710
 711     <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
 712
 713     <blockquote>
 714       <p>The Attribute Authority maintains a set of policies called
 715       Attribute Release Policies (or ARP's) that govern the sharing
 716       of user attributes with Shibboleth target sites. When a user
 717       attempts to access a Shibboleth-protected resource, that
 718       resource's SHAR queries the user's AA for all attributes to
 719       which it is entitled. The SHAR provides its own name and the
 720       URL of the resource on behalf of which it is making the
 721       request.  The AA finds the attributes associated with the
 722       browser user, determines an "Effective ARP" for this user, and
 723       then sends to the SHAR only the attributes/values allowed in
 724       this policy.</p>
 725
 726       <p>An ARP may be thought of as a sort of filter for outbound
 727       attributes; it cannot create attributes or data that aren't
 728       originally present, but it can limit the attributes released
 729       and the values those attributes may have when released. It
 730       does not change the information in the data sources in any
 731       way.</p>
 732
 733       <p>Each ARP is comprised of one or more rules that specify
 734       which attributes and values may be released to a target or set
 735       of targets.  The assignment of rules to various targets is
 736       quite flexible and includes mechanisms for specifying: that a
 737       rule should affect all targets (default rule), exact SHAR
 738       names for which a rule is applicable, regular expressions
 739       against which SHAR names should be matched to determine if a
 740       rule is applicable, URL trees for which a rule is
 741       applicable.</p>
 742
 743       <p>For each request, an Effective ARP is determined by
 744       locating all ARP's applicable to the designated user and
 745       extracting each rule that matches the querying SHAR and
 746       resource.  Attributes and values that are specified for
 747       release are included in the effective ARP, while those
 748       specified for denial are blocked from release.  See section <a
 749       href="#5.a.i.">5.a.i</a> for details on how ARP's are
 750       processed.</p>
 751
 752
 753       <p>Various ARP's may be combined in forming the Effective ARP.
 754       For instance, the Site ARP is administratively maintained and
 755       applies to all users for which the AA is answerable. User
 756       ARP's apply to a specific user only, and can be maintained
 757       either administratively or by the users themselves.  All ARP's
 758       are specified using the same syntax and semantics.</p>
 759     </blockquote>
 760
 761     <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
 762
 763     <blockquote>
 764       <p>Since Shibboleth deals both with daily technical and
 765       operational issues and also with contractual issues, a set of
 766       contacts should be set up to support the user base and to
 767       facilitate interactions with other Shibboleth sites and federation
 768       members. It is recommended that at least technical and
 769       administrative contacts be designated.</p>
 770     </blockquote>
 771
 772     <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
 773
 774     <blockquote>
 775       <p>A primary Shibboleth design consideration was to require
 776       very little or no modification to client machines. The only
 777       requirement is that a browser is used which supports cookies,
 778       redirection and SSL. Browser users will have to perform an
 779       additional click to submit the authentication assertion if
 780       JavaScript is not functional.</p>
 781     </blockquote>
 782
 783     <h4><a name="2.h."></a>2.h. Clocks</h4>
 784
 785     <blockquote>
 786       <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
 787       be run on all web servers. Shibboleth employs a short handle
 788       issuance time to protect against replay attacks. Because of
 789       this, any significant degree of clock skew can hinder the
 790       ability of users to access sites successfully.</p>
 791     </blockquote>
 792
 793     <h4><a name="2.i."></a>2.i. Other Considerations</h4>
 794
 795     <blockquote>
 796       <p>Especially for higher education, there are a handful of
 797       laws enacted which may have important ramifications on the
 798       disclosure of personal information and attributes. Since
 799       Shibboleth does not necessarily need to transmit identity, it
 800       is an ideal solution for many higher education situations.
 801       Nevertheless, all parties within the United States of America
 802       are strongly advised to consult the <a href=
 803       "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
 804       Rights and Privacy Act of 1974(FERPA)</a>, and all other
 805       relevant state and federal legislation before deploying
 806       Shibboleth.</p>
 807     </blockquote>
 808     <br>
 809     <br>
 810     <hr>
 811     <br>
 812
 813
 814     <h3><a name="3."></a>3. Installation</h3>
 815
 816     <h4><a name="3.a."></a>3.a. Software Requirements</h4>
 817
 818     <p><b>The following requirements are primarily recommendations
 819     based on the most common ways to run Shibboleth.  However, the
 820     origin should be able to run under any servlet container
 821     supporting <span class="fixed">Servlet API v2.3</span> and <span class="fixed">JSP specification
 822     1.2</span>.</b></p>
 823
 824     <blockquote>
 825       <ul type="circle">
 826         <li><a href=
 827         "http://http://www.apache.org/dist/httpd/">Apache
 828         1.3.26+ (&lt;2.0)</a></li>
 829
 830         <li><a href="http://jakarta.apache.org/tomcat/">Tomcat
 831         4.1.18-24 LE Java server</a></li>
 832
 833         <li>
 834           <a href="http://java.sun.com/j2se/">Sun J2SE JDK v1.4.1_01 and above</a>
 835         </li>
 836
 837         <li>
 838           mod_jk
 839
 840           <blockquote>
 841             <p>You may need to build mod_jk against Apache, which
 842             will generally require GCC or a platform-specific C
 843             compiler.</p>
 844           </blockquote>
 845         </li>
 846
 847         <li>
 848           An enterprise authentication mechanism
 849
 850           <blockquote>
 851             <p>Ideally, this will be a WebISO or SSO system such as
 852             <a href= "http://pubcookie.org/">Pubcookie</a>. The
 853             minimal requirement is for the web server to be able to
 854             authenticate browser users and supply their identity to
 855             the Handle Server.</p>
 856           </blockquote>
 857         </li>
 858
 859         <li>
 860           An enterprise directory service
 861
 862           <blockquote>
 863             <p>Shibboleth currently supports retrieving user
 864             attribute information from an <a href=
 865             "http://www.openldap.org">LDAP</a> directory. For
 866             testing purposes, Shibboleth also supports a minimal
 867             echo responder which will always returns predefined
 868             attributes.</p>
 869           </blockquote>
 870         </li>
 871       </ul>
 872     </blockquote>
 873
 874     <h4><a name="3.b."></a>3.b. Deploy HS and AA</h4>
 875
 876     <blockquote>
 877       <ol type="1">
 878         <li>
 879           <p>Ensure you have already obtained the proper <a href=
 880           "http://shibboleth.internet2.edu/release/shib-download.html">tarball</a>.</p>
 881         </li>
 882
 883         <li>
 884           <p>The archive will expand into a <span class="fixed">shibboleth-origin-1.0/</span>
 885           directory(<span class="fixed">/opt</span> recommended).</p>
 886         </li>
 887
 888         <li>
 889           <p>Run the following command to move the Java files into
 890           Tomcat's tree:</p>
 891
 892           <blockquote>
 893             <span class="fixed">cp /opt/shibboleth-origin-1.0/dist/shibboleth.war
 894             /usr/local/tomcat/webapps/</span>
 895           </blockquote>
 896         </li>
 897
 898         <li>
 899           <p>Tomcat 4.1.x requires that several Java jarfiles used
 900           by Shibboleth be located in a special "endorsed" folder to
 901           override obsolete classes that Sun includes with their JVM.
 902           To deal with this problem use the following command, adjusting
 903           paths as needed:</p>
 904           <blockquote>
 905             <span class="fixed">$ cp /opt/shibboleth-origin-1.0/endorsed/*.jar /usr/local/tomcat/common/endorsed</span>
 906           </blockquote>
 907          <p>Different versions of Tomcat or other Java servers may have
 908          other locations in which to place these files or deal with this
 909          problem. Refer to your application server's documentation to
 910          find out how to properly endorse classes, if necessary.</p>
 911         </li>
 912
 913         <li>
 914           <p>Restart Tomcat, which will automatically detect that
 915           there has been a new .war file added. This file will by
 916           default be expanded into
 917           <span class="fixed">/usr/local/tomcat/webapps/shibboleth</span>.</p>
 918         </li>
 919
 920         <li>
 921           <p>Apache must be told to map the URL's for the
 922           Shibboleth HS and AA to Tomcat. Two popular ways of doing
 923           this are to include the following text directly in
 924           <span class="fixed">httpd.conf</span>, or to place <span class="fixed">Include
 925           conf/mod_jk.conf</span> in <span class="fixed">httpd.conf</span>, and place
 926           the following lines in
 927           <span class="fixed">/etc/httpd/conf/mod_jk.conf</span>:</p>
 928
 929           <blockquote>
 930             <span class="fixed">--------- begin ---------<br>
 931             &lt;IfModule !mod_jk.c&gt;<br>
 932             &nbsp;LoadModule jk_module libexec/mod_jk.so<br>
 933             &lt;/IfModule&gt;<br>
 934             <br>
 935             JkWorkersFile
 936             "/usr/local/tomcat/conf/jk/workers.properties"<br>
 937             JkLogFile "/usr/local/apache/logs/mod_jk.log"<br>
 938             <br>
 939             JkLogLevel emerg<br>
 940             <br>
 941             JkMount /shibboleth/* ajp13<br>
 942             <br>
 943             --------- end ---------</span>
 944           </blockquote>
 945         </li>
 946
 947         <li>
 948           <p>Tomcat's <span class="fixed">/conf/server.xml</span>
 949           ships by default with the Coyote/JK2 connector enabled, which
 950           fails with Shibboleth due to the lack of support for <span
 951           class="fixed">REMOTE_USER</span>.  This connector must be
 952           commented out.  Then, uncomment and modify the traditional AJP
 953           1.3 connector as follows:</p>
 954
 955           <ol type="A">
 956             <li>
 957               <p>Add <span class="fixed">address="127.0.0.1"</span> inside the
 958               <span class="fixed">&lt;Ajp13Connector&gt;</span> configuration
 959               element to prevent off-host access.</p>
 960             </li>
 961
 962             <li>
 963               <p>Add <span class="fixed">tomcatAuthentication="false"</span> to the
 964               <span class="fixed">&lt;Ajp13Connector&gt;</span> configuration element
 965               to ensure that the user's identity is passed from
 966               Apache to the servlet environment.</p>
 967             </li>
 968           </ol>
 969         </li>
 970       </ol>
 971     </blockquote>
 972     <br>
 973     <hr>
 974     <br>
 975
 976
 977     <h3><a name="4."></a>4. Getting Running</h3>
 978
 979     <h4><a name="4.a."></a>4.a. Basic Configuration</h4>
 980
 981     <blockquote>
 982       <p>The main configuration file for Shibboleth's origin side is
 983       located in
 984       <span class="fixed">/webapps/shibboleth/WEB-INF/classes/conf/origin.properties.</span>. This file contains configuration information
 985       for the origin side in several sections.  The configuration
 986       must be consistent with values elsewhere in the deployment,
 987       such as the <a href="#4.c.">HS' certificate</a> and with
 988       directory access bindings, etc., or access errors may occur.</p>
 989
 990       <p>All pathnames are relative, and have an effective root
 991       path of
 992       <span class="fixed">$TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/</span>.  To
 993       specify files outside of the webapp, specify a full URI, such
 994       as <span class="fixed">file:///opt/shibboleth-origin-1.0/</span>.</p>
 995
 996       <p>Fields that are purple are optional; grey fields are
 997       mandatory.</p>
 998
 999
1000           <p>These are the variables that may be specified for each
1001       component of <span class="fixed">origin.properties</span>:</p>
1002
1003       <br>
1004       <p>General Configuration:</p>
1005
1006       <dl>
1007           <dd class="attributelong">
1008               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.issuer
1009               = &lt;domain name&gt;</span>
1010           </dd>
1011
1012           <dd class="value">
1013               <p>Specifies the DNS name the HS should use for
1014               itself in issuing assertions.</p>
1015           </dd>
1016
1017           <dd class="attributelong">
1018               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.siteName
1019               = &lt;URI&gt;</span>
1020           </dd>
1021
1022           <dd class="value">
1023               <p>Specifies the the <span
1024               class="fixed">URI</span> to use as the name of
1025               the origin site as a whole.  This field is primarily
1026               meant to be populated in the context of the federation
1027               in which the origin site resides, is intended to be
1028               globally unique, and will typically be assigned by the
1029               federation.</p>
1030           </dd>
1031
1032           <dd class="attributelong">
1033               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.AAUrl
1034               = &lt;url&gt;</span>
1035           </dd>
1036
1037           <dd class="value">
1038               <p>Specifies the <span class="fixed">URL</span>
1039               at which the HS' corresponding AA may be
1040               contacted.</p>
1041           </dd>
1042
1043           <dd class="attributeoptlong">
1044               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.username
1045               = &lt;var&gt;</span>
1046           </dd>
1047
1048           <dd class="valueopt">
1049               <p>Specifies the HTTP request header that should be used
1050               to acquire the user's principal name from the
1051               authentication service.  Defaults to <span
1052               class="fixed">REMOTE_USER</span>.</p>
1053           </dd>
1054
1055           <dd class="attributeoptlong">
1056               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.authMethod
1057               = &lt;uri&gt;</span>
1058           </dd>
1059
1060           <dd class="valueopt">
1061               <p>Specifes the URI used to populate <span
1062               class="fixed">AuthenticationMethod</span> in the SAML
1063               attribute assertion.  This corresponds to the method used
1064               to authenticate users by the authentication service used
1065               by the HS.  Some common authentication methods and
1066               corresponding URI's are listed below; for a complete list,
1067               please consult section 7.1 of the SAML 1.1 core
1068               specifications or your federation's guidelines.</p>
1069               <table border=2 cellpadding=0 cellspacing=0>
1070                 <tr>
1071                   <td><span class="fixed">urn:oasis:names:tc:SAML:1.0:am:password</span></td>
1072                   <td>The authentication was performed using a password.</td>
1073                 </tr>
1074                 <tr>
1075                   <td><span class="fixed">urn:ietf:rfc:1510</span></td>
1076                   <td>The authentication was performed using Kerberos.</td>
1077                 </tr>
1078                 <tr>
1079                   <td><span class="fixed">urn:oasis:names:tc:SAML:1.0:am:X509-PKI</span></td>
1080                   <td>The authentication was performed using a
1081                   certificate and key issued to the end user.  More
1082                   specific forms of PKI authentication such as SPKI and
1083                   XKMS are also assigned URN's in the SAML specs.</td>
1084                 </tr>
1085               </table>
1086           </dd>
1087       </dl>
1088
1089       <br>
1090       <p>Assertion Signing:</p>
1091
1092       <dl>
1093           <dd class="attributelong">
1094               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePath
1095               = &lt;pathname&gt;</span>
1096           </dd>
1097
1098           <dd class="value">
1099               <p>Specifies the location of the Java keystore
1100               containing the x.509 certificate and matching private
1101               key to be used by the HS.</p>
1102           </dd>
1103
1104           <dd class="attributelong">
1105               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStorePassword
1106               = &lt;password&gt;</span>
1107           </dd>
1108
1109           <dd class="value">
1110               <p>Specifies the password to the referenced
1111               keystore.</p>
1112           </dd>
1113
1114           <dd class="attributelong">
1115               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyAlias
1116               = &lt;alias&gt;</span>
1117           </dd>
1118
1119           <dd class="value">
1120               <p>Specifies the alias used for accessing the private
1121               key.</p>
1122           </dd>
1123
1124           <dd class="attributelong">
1125               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.keyStoreKeyPassword
1126               = &lt;password&gt;</span>
1127           </dd>
1128
1129           <dd class="value">
1130               <p>Specifies the password used to retrieve the private key.</p>
1131           </dd>
1132
1133           <dd class="attributeoptlong">
1134               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleServlet.certAlias
1135               = &lt;alias&gt;</span>
1136           </dd>
1137
1138           <dd class="valueopt">
1139               <p>Specifies the alias for the certificate
1140               corresponding to the private key used by the HS.
1141               Defaults to the private key's alias.</p>
1142           </dd>
1143       </dl>
1144       <br>
1145
1146       <p>General AA Configuration:</p>
1147
1148       <dl>
1149           <dd class="attributelong">
1150               <span class="fixed">edu.internet2.middleware.shibboleth.aa.AAServlet.authorityName
1151               = &lt;domain name&gt;</span>
1152           </dd>
1153
1154           <dd class="value">
1155               <p>Specifies the name of the AA, which is typically
1156               the domain name of the server running it.</p>
1157           </dd>
1158
1159           <dd class="attributelong">
1160               <span class="fixed">edu.internet2.middleware.shibboleth.aa.AAServlet.passThruErrors
1161               = &lt;true/false&gt;</span>
1162           </dd>
1163
1164           <dd class="value">
1165               <p>Specifies whether the AA should pass on internal errors
1166               to the SHAR for debugging purposes.  Defaults to <span
1167               class="fixed">false</span>.</p>
1168           </dd>
1169       </dl>
1170
1171       <p>AA Attribute Resolution:</p>
1172
1173         <dl>
1174           <dd class="attributelong">
1175               <span class="fixed">edu.internet2.middleware.shibboleth.aa.attrresolv.AttributeResolver.ResolverConfig
1176               = &lt;pathname&gt;</span>
1177           </dd>
1178
1179           <dd class="value">
1180               <p>Specifies the location of the configuration file
1181               for the resolver the AA uses to build attributes.
1182               Defaults to <span
1183               class="fixed">/conf/resolver.xml</span>.  For
1184               information on how to configure and use the attribute
1185               resolver, consult section <a href="4.e.">4.e</a>.</p>
1186           </dd>
1187         </dl>
1188
1189       <p>ARP Configuration:</p>
1190
1191       <dl>
1192           <dd class="attributelong">
1193               <span class="fixed">edu.internet2.middleware.shibboleth.aa.arp.ArpRepository.implementation
1194               = &lt;string&gt;</span>
1195           </dd>
1196
1197           <dd class="value">
1198               <p>References the type of ARP repository implemented.
1199               Shibboleth provides a built-in ARP repository
1200               specified by
1201               <span class="fixed">edu.internet2.middleware.shibboleth.aa.arp.
1202               provider.FileSystemArpRepository</span>.</p>
1203
1204               <p>Note that the set of principals that an ARP applies
1205               to is not expressed by the ARP itself, but rather the
1206               implementation of the ARP repository.  For example, if
1207               the ARP repository were implemented in LDAP, the ARP's
1208               that apply to a user would be attributes of that
1209               user's personal LDAP entry, and the site ARP would be
1210               an attribute of an entry representing the site.  While
1211               not performed by the built-in ARP repository, a
1212               repository implementation might also implement group
1213               ARP's; for example, in an LDAP directory, the user
1214               entry might have some group membership attributes that
1215               refer to group entries, and those group entries would
1216               have ARP attributes, and all those ARP's would be
1217               applicable.</p>
1218           </dd>
1219
1220           <dd class="attributelong">
1221               <span class="fixed">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path
1222               = &lt;pathname&gt;</span>
1223           </dd>
1224
1225           <dd class="value">
1226               <p>Specifies the relative or absolute path to the
1227               folder containing the ARP files.</p>
1228           </dd>
1229
1230           <dd class="attributeoptlong">
1231               <span class="fixed">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.ArpTTL
1232               = &lt;seconds&gt;</span>
1233           </dd>
1234
1235           <dd class="valueopt">
1236               <p>Specifies the duration in <span
1237               class="fixed">seconds</span> that ARP's may be
1238               cached by the AA.  Defaults to <span
1239               class="fixed">0</span>, or no caching.</p>
1240           </dd>
1241       </dl>
1242
1243       <p>Handle Repository Configuration:</p>
1244
1245       <dl>
1246           <dd class="attributeoptlong">
1247               <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleRepository.implementation
1248               = &lt;string&gt;</span>
1249           </dd>
1250
1251           <dd class="valueopt">
1252               <p>Specifies the method by which the HS and AA share
1253               handles.  These are by default passed by memory(which
1254               can be specified explicitly using
1255               <span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.
1256               MemoryHandleRepository</span>), and may also be passed
1257               using symmetric encryption with
1258               <span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository</span>.</p>
1259           </dd>
1260       </dl>
1261
1262       <p>edu.internet2.middleware.shibboleth.hs.provider.
1263       MemoryHandleRepository <font color="#5555EE">(specify
1264       if
1265       <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleRepository.
1266       implementation</span> is <span class="fixed">MemoryHandleRepository</span>)</font></p>
1267
1268       <blockquote>
1269         <dl>
1270             <dd class="attributeoptlong">
1271 <span class="fixed">edu.internet2.middleware.shibboleth.hs.BaseHandleRepository.handleTTL
1272             = &lt;seconds&gt;</span>
1273             </dd>
1274
1275             <dd class="valueopt">
1276               <p>Specifies the time in <span
1277               class="fixed">seconds</span> for which issued handles
1278               are valid.  Defaults to <span
1279               class="fixed">1800</span>, or 30 minutes.  The time
1280               should be long enough to allow for clock skew and short
1281               enough to protect against various attacks.  Consult your
1282               federation guidelines for further advice.</p>
1283             </dd>
1284           </dl>
1285       </blockquote>
1286
1287       <p>edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository <font color="#5555EE">(specify
1288       if
1289       <span class="fixed">edu.internet2.middleware.shibboleth.hs.HandleRepository.
1290       implementation</span> is <span class="fixed">CryptoHandleRepository</span>)</font></p>
1291
1292       <p>In order to use the crypto repository implementation, you must
1293       have a <span class="fixed">DESede</span> secret key in a
1294       keystore of type <span class="fixed">JCEKS</span>.  The
1295       origin distribution includes a program that will automatically
1296       generate such a key.  In order to invoke it, run <span
1297       class="fixed">./ant genSecret</span>, which will create a
1298       keystore in <span
1299       class="fixed">$SHIB_HOME/src/conf/handle.jks</span> that
1300       includes the key, with an alias of <span
1301       class="fixed">handleKey</span> and a password of <span
1302       class="fixed">shibhs</span>.  If <span
1303       class="fixed">./ant dist</span> is run subsequently, this
1304       keystore will be included in the webapp archive that is
1305       created.</p>
1306
1307       <blockquote>
1308         <dl>
1309             <dd class="attributelong">
1310               <span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePath
1311             = &lt;pathname&gt;</span>
1312             </dd>
1313
1314             <dd class="value">
1315               <p>Specifies the path to the keystore containing the
1316               key used to encrypt passed principal identifiers.</p>
1317             </dd>
1318
1319             <dd class="attributelong">
1320 <span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStorePassword
1321             = &lt;password&gt;</span>
1322             </dd>
1323
1324             <dd class="value">
1325               <p>Specifies the password for the keystore.</p>
1326             </dd>
1327
1328             <dd class="attributelong">
1329 <span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyAlias
1330              = &lt;password&gt;</span>
1331             </dd>
1332
1333             <dd class="value">
1334               <p>Specifies the alias for the appropriate encryption
1335               key within the keystore.</p>
1336             </dd>
1337
1338             <dd class="attributelong">
1339 <span class="fixed">edu.internet2.middleware.shibboleth.hs.provider.CryptoHandleRepository.keyStoreKeyPassword
1340             = &lt;password&gt;</span>
1341             </dd>
1342
1343             <dd class="valueopt">
1344               <p>Specifies the password used to retrieve the key.</p>
1345             </dd>
1346
1347             <dd class="attributeoptlong">
1348 <span class="fixed">edu.internet2.middleware.shibboleth.hs.CryptoHandleRepository.handleTTL
1349             = &lt;seconds&gt;</span>
1350             </dd>
1351
1352             <dd class="valueopt">
1353               <p>Specifies the time in <span
1354               class="fixed">seconds</span> for which issued handles
1355               are valid.  Defaults to <span
1356               class="fixed">1800</span>, or 30 minutes.  The time
1357               should be long enough to allow for clock skew and short
1358               enough to protect against various attacks.  Consult your
1359               federation guidelines for further advice.</p>
1360             </dd>
1361
1362         </dl>
1363       </blockquote>
1364
1365       <p>Federation Configuration:</p>
1366
1367         <dl>
1368           <dd class="attributelong">
1369               <span class="fixed">edu.internet2.middleware.shibboleth.audiences
1370               = &lt;URI's&gt;</span>
1371           </dd>
1372
1373           <dd class="value">
1374               <p>Specifies a list of <span
1375               class="fixed">URI</span>'s that will be used for
1376               the <span class="fixed">Audience</span> field of
1377               the SAML attribute assertion.  All URI's listed will
1378               be sent with any assertion issued by the AA.  These
1379               URI's are defined and provided by and correspond to
1380               federations.</p>
1381
1382               <p>Note that the values of the URI's here <b>must</b>
1383               match one of the policy URI's accepted by the
1384               receiving target in the <span
1385               class="fixed">[policies]</span> section of <span
1386               class="fixed">shibboleth.ini</span> or
1387               interoperation will fail by design.
1388           </dd>
1389         </dl>
1390
1391     </blockquote>
1392     <br>
1393
1394
1395     <h4><a name="4.b."></a>4.b. Key Generation and Certificate
1396     Installation</h4>
1397
1398     <blockquote>
1399       <p>The SAML messages generated by the HS must be digitally
1400       signed. Each HS must be issued a private and public keypair,
1401       which is stored in a Java keystore. The current
1402       implementation of Shibboleth requires the use of an ordinary
1403       file-based keystore. The keytool program is included with the
1404       Java development and runtime kits. Access parameters to the
1405       keystore will need to be consistent with those specified in
1406       <span class="fixed">origin.properties</span>.</p>
1407
1408       <p>A sample keystore is included in the distribution and can
1409       be found in
1410       <span class="fixed">/usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf/keystore.jks</span>
1411       with a password of <span class="fixed">shibhs</span>.  It is intended
1412       to serve as an example and not as a production keystore.</p>
1413
1414       <p>The following commands will generate a new RSA keypair and
1415       store it in the <span class="fixed">keystore.jks</span> file, with a keyentry
1416       alias of <span class="fixed">hs</span> and new passwords of your choosing:</p>
1417
1418       <blockquote>
1419         <span class="fixed">$ cd /usr/local/tomcat/webapps/shibboleth/WEB-INF/classes/conf<br>
1420         $ keytool -storepasswd -keystore keystore.jks -new
1421         &lt;newpassword&gt;<br>
1422         $ keytool -genkey -keystore keystore.jks -alias hs -keyalg
1423         rsa -keysize 2048<br>
1424         </span>
1425       </blockquote>
1426
1427       <p>You will be prompted for passwords during key generation
1428       as needed, to access the keystore and assign the key itself
1429       its own password. You will also be prompted for the
1430       distinguished name components to associate with the key. This
1431       DN will be placed in a self-signed certificate and will be
1432       the name that is associated with your HS by Shibboleth. In
1433       particular, the first component you enter for Name will be
1434       the <span class="fixed">Common Name</span>(when keytool asks for first and last
1435       name, common name is intended), which in most cases should be
1436       the hostname of the HS system. Note that a specific federation of
1437       sites may dictate what type of key algorithm, key size, or
1438       validity period is appropriate.</p>
1439
1440       <p>Once you have a keypair generated, the self-signed certificate
1441       must be replaced with a certificate signed by a CA acceptable to
1442       the federation you will be joining. Shibboleth is generally able to
1443       climb trust chains to reach an intermediate CA's root CA.  Note
1444       that the intermediate CA's signing certificate must still be
1445       signed by a root CA recognized by the federation.</p>
1446
1447       <p>To generate a certificate signing request for a CA, use
1448       the following command:</p>
1449
1450       <blockquote>
1451         <span class="fixed">$ keytool -certreq -keystore keystore.jks -alias hs
1452         -file &lt;csr-file&gt;<br>
1453         </span>
1454       </blockquote>
1455
1456       <p>The contents of <span class="fixed">&lt;csr-file&gt;</span> can then be sent
1457       to a CA for signing. You will receive a signed certificate in
1458       return in a file. To install the new certificate into your
1459       keystore, use the following command:</p>
1460
1461       <blockquote>
1462         <span class="fixed">$ keytool -import -keystore keystore.jks -alias hs
1463         -file &lt;cert-file&gt;</span>
1464       </blockquote>
1465
1466       <p>Note that if the signing CA's certificate is not already
1467       installed in your keystore as a trusted signer, you may need
1468       to download the CA's root certificate and import it into the
1469       keystore file under a different alias, using a command
1470       similar to the above.</p>
1471
1472           <p>For information on sharing certificate/key pairs between Apache
1473           and Java keystores see section <a href="#5.b.">5.b.</a>.</p>
1474     </blockquote>
1475
1476     <h4><a name="4.c."></a>4.c. Linking the Authentication System
1477     to the HS</h4>
1478
1479     <blockquote>
1480       <p>The interaction between the HS and the local authentication
1481       system is implemented by supplying the HS with the identity of
1482       the browser user. Most often, this will mean protecting the HS
1483       servlet with some form of local authentication that populates
1484       <span class="fixed">REMOTE_USER</span>. Location blocks can be added to
1485       <span class="fixed">httpd.conf</span>, associating the appropriate
1486       authentication mechanism with the URL of the HS servlet. The
1487       following example demonstrates association of a very basic
1488       authentication method with the HS:</p>
1489
1490       <blockquote>
1491         <span class="fixed">&lt;Location /shibboleth/HS&gt;<br>
1492         AuthType Basic<br>
1493         AuthName "Internet2 Handle Service"<br>
1494         AuthUserFile /usr/local/apache/conf/user.db<br>
1495         require valid-user<br>
1496         &lt;/Location&gt;<br>
1497         </span>
1498       </blockquote>
1499
1500       <p>Note that .htaccess files cannot be used for this purpose
1501       because URL's are "virtualized" by Tomcat.</p>
1502
1503       <p>It is recommended that the origin be tested at the end of
1504       this process using the process described in section <a href=
1505       "#6.a.">6.a</a>.</p>
1506     </blockquote>
1507
1508     <h4><a name="4.c.i."></a>4.c.i. Enabling client certificate
1509     authentication <font color="#5555EE">(optional)</font></h4>
1510
1511     <blockquote>
1512       <blockquote>
1513
1514       <p>Shibboleth supports client certificate authentication by
1515       utilization of a filter that relies on the web server to do all
1516       processing to ensure that the certificate is both valid and
1517       appropriate for the application.  An example deployment descriptor
1518       is included with the Shibboleth distribution at <span
1519       class="fixed">$SHIB_HOME/webAppConfig/origin-client-cert.xml</span>.
1520       To enable the filter, add the following to the deployment
1521       descriptor (<span class="fixed">web.xml</span>):</p>
1522
1523       <blockquote>
1524         <span class="fixed">&nbsp;&nbsp;&lt;filter&gt;<br>
1525         &nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-name&gt;<br>
1526         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Client Cert AuthN Filter<br>
1527         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter-name&gt;<br>
1528         &nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-class&gt;<br>
1529         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;edu.internet2.middleware.shibboleth.utils.ClientCertTrustFilter<br>
1530         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter-class&gt;<br>
1531         &nbsp;&nbsp;&lt;/filter&gt;<br>
1532         <br>
1533         <br>
1534         &nbsp;&nbsp;&lt;filter-mapping&gt;<br>
1535         &nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-name&gt;<br>
1536         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Client Cert AuthN Filter<br>
1537         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter-name&gt;<br>
1538         &nbsp;&nbsp;&nbsp;&nbsp;&lt;url-pattern&gt;<br>
1539         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/HS<br>
1540         &nbsp;&nbsp;&nbsp;&nbsp;&lt;/url-pattern&gt;<br>
1541         &nbsp;&nbsp;&lt;/filter-mapping&gt;<br></span>
1542      </blockquote>
1543
1544      <p>By default, the filter pulls the principal name out of the <span
1545      class="fixed">CN</span> of the cert's <span
1546      class="fixed">Subject</span> by using regular expression
1547      grouping.  This may be done using patterns such as:</p>
1548
1549      <blockquote>
1550        <span class="fixed">regex: '.*CN=([^,/]+).*' match group: 1</span>
1551      </blockquote>
1552
1553      <p>The servlet filter will accept two initialization parameters,
1554      <span class="fixed">regex</span> and <span
1555      class="fixed">matchGroup</span> that can be used to extract
1556      the principal name differently.</p>
1557
1558       </blockquote>
1559     </blockquote>
1560
1561     <h4><a name="4.d."></a>4.d. Establishing default ARP's for the
1562     origin community</h4>
1563
1564     <p><b>For a more basic introduction to ARP's, please refer to
1565     section <a href="#2.e.">2.e</a>.</b></p>
1566
1567     <blockquote>
1568       <p>An ARP determines which attributes are released to a SHAR
1569       when a user tries to access a resource.  It acts as a sort of
1570       filter on user information contained in the authoritative
1571       directory, deciding what can be released to whom, but not
1572       modifying or creating information itself.  ARP's are generally
1573       administered by the site, but Shibboleth will provide for users to
1574       broker control of their own information and privacy by
1575       allowing them to create ARP's pertaining to themselves.</p>
1576
1577       <p>It is recommended that a set of policies be established
1578       between an origin and frequently accessed targets to specify
1579       default releases of expected attributes.  Federation guidelines may
1580       provide more information on population of ARP's.</p>
1581
1582       <p>Currently, there is no direct mechanism for users to create
1583       their own ARP's besides direct XML writing.  In future
1584       versions, a GUI will be provided for simpler management of
1585       ARP's.  Care should be given to balancing giving sufficient
1586       control over information to users and avoiding access
1587       problems.  For example, users may decide to restrict the
1588       release of their personal information to such a degree that
1589       access to a site for a class may become impossible because
1590       Shibboleth cannot release enough information to grant
1591       access.</p>
1592
1593           <p>The Shibboleth distribution contains an example site arp that
1594           releases the eduPersonScopedAffiliation attribute to all targets.  For
1595           more precise information regarding how ARP's are processed or
1596           syntactically formed, please refer to section <a href="#5.a.i.">5.a.i</a>.</p>
1597     </blockquote>
1598
1599         <h4><a name="4.e."></a>4.e. Modifying the default Attribute Resolver configuration</h4>
1600         <blockquote>
1601         <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>
1602
1603         <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="fixed">/webapps/shibboleth/WEB-INF/classes/conf/resolver.xml.</span>  Two changes are necessary:</p>
1604
1605         <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>
1606
1607         <p>2. The comment indicators should be removed from around the definitions of those two elements ( &lt;!-- and --&gt; ).</p>
1608         </blockquote>
1609     <br>
1610     <hr>
1611     <br>
1612
1613     <h3><a name="5."></a>5. Advanced Configuration</h3>
1614
1615     <h4><a name="5.a."></a>5.a. ARP Overview</h4>
1616
1617     <blockquote>
1618       <h5>This section applies primarily to the syntactic and
1619       technical details of ARP's. For basic information on and
1620       explanation of what an ARP is and how it should be managed,
1621       please refer to sections <a href="#2.e.">2.e</a> and <a href=
1622       "#4.d.">4.d</a>.</h5>
1623
1624       <p>Every ARP file contains one ARP.  ARP's may be specified either
1625       as the site ARP or user ARP's.  The site ARP pertains to every
1626       principal for whom the AA retrieves information; a user ARP
1627       applies only to the individual user for whom it is defined.  The
1628       set of principals to whom the ARP applies is defined by the name
1629       of the ARP file: the site ARP is stored in <span
1630       class="fixed">arp.site.xml</span> and user ARP's are stored as
1631       <span class="fixed">arp.user.$PRINCIPALNAME.xml</span>.
1632       Up to two ARP's will apply to a principal: the site ARP, and the
1633       user ARP for that principal.</p>
1634
1635       <p>Each ARP acts as a container that holds a set of ARP rules
1636       that are applicable to the principals that ARP is effective
1637       for.  Each ARP rule specifies a single release policy within
1638       the ARP container pertaining to a specific set of targets.
1639       This set of targets may be specified as a specific SHAR, a
1640       SHAR tree, or a regular expression, and becomes the ARP rule's
1641       target definition. Each ARP rule may contain specifications
1642       regarding the release of any number of attribute values to
1643       requests matching that ARP rule for that user. ARP rules may
1644       be flagged as default, implying that they are always applied
1645       to any user matched by the ARP container.  Note that ARP's may
1646       also be used to restrict specific attribute/value pairs in
1647       addition to restricting or releasing individual attributes.</p>
1648
1649       <p>When a query is received, the AA generates an effective
1650       ARP, which is the fully evaluated set of ARP rules regarding
1651       that SHAR based on all ARP containers applicable to the
1652       principal.  This effective ARP is then applied to attribute
1653       values retrieved from the directory and the appropriate
1654       assertion is constructed.  Default rules are always
1655       included in construction of the effective ARP.</p>
1656
1657       <!-- ##To be included in future releases of the deploy guide.
1658
1659       <dl>
1660           <dd class="demo">
1661             <img src="arp.gif">
1662           </dd>
1663           <dd class="demo">
1664             <p>In this picture, meant to demonstrate the structure
1665             of ARP's, if all ARP's are taken to mean "Release this
1666             attribute," then attributes 1-4 will be released if that
1667             principal tries to access site A.  ARP #1 could not
1668             restrict the release of attribute 4 to site A.</p>
1669           </dd>
1670       </dl>
1671
1672       -->
1673
1674     </blockquote>
1675
1676     <h4><a name="5.a.i."></a>5.a.i. ARP Processing</h4>
1677
1678     <blockquote>
1679       <blockquote>
1680         <p>When a request arrives from a particular SHAR, the
1681         applicable set of ARP rules are parsed into an effective
1682         ARP.  This parsing is done as follows:</p>
1683
1684         <ol type=1>
1685           <li>Identify all ARP's that should be applied to a particular
1686           principal.  This is done by isolating the files in the folder
1687           specified by <span
1688           class="fixed">edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository.Path</span> that have the
1689           name either arp.site.xml or arp.user.$PRINCIPALNAME.xml.</li>
1690           <li>Find all ARP rules relevant to the query:
1691           <ol type=i>
1692             <li>Any ARP rules within the identified ARP's designated
1693             as defaults are automatically included in the effective
1694             ARP without performing any matching functions.</li>
1695             <li>For each non-default rule in each identified ARP,
1696             the matching functions specified in the rule's target
1697             definition are performed. A separate matching function
1698             is performed for the requesting SHAR and the resource on
1699             behalf of which the SHAR is making the request.</li>
1700             <li>Each matching function evaluates to <span class="fixed">TRUE</span> if
1701             the match is successful or <span class="fixed">FALSE</span> if it is
1702             unsuccessful. If both functions evaluate to
1703             <span class="fixed">TRUE</span>, the rule is included in the Effective
1704             ARP.</li>
1705           </ol></li>
1706           <li>Construct the Attribute Filter:
1707           <ol type=i>
1708             <li>For each attribute, compile a temporary list of
1709             associated rules that includes all values with a release
1710             qualifier of <span class="fixed">permit</span>.</li>
1711             <li>Subtract from this list all attribute values with
1712             rules specifying a release qualifier of <span class="fixed">deny</span>.
1713             The resulting list represents the allowable release
1714             values for the attribute and is used as a mask for the
1715             values which are returned from the Attribute
1716             Resolver.</li>
1717             <li>If a statement specifies that all values should be
1718             permitted, then specific <span class="fixed">deny</span> qualifiers for
1719             specific values should still be enforced.  If a
1720             statement specifies that all values should be denied,
1721             then <span class="fixed">permit</span> qualifiers for specific values will
1722             be ignored.</li>
1723           </ol></li>
1724           <li>Using the mask and attributes returned from the
1725           Attribute Resolver, an assertion is constructed.</li>
1726         </ol>
1727       </blockquote>
1728     </blockquote>
1729
1730
1731     <h4><a name="5.a.ii."></a>5.a.ii. ARP Syntax</h4>
1732
1733     <blockquote>
1734       <blockquote>
1735
1736       <p>Each ARP is described by an XML file based on a standard
1737       <span class="fixed">.xsd</span> schema.  It consists of a standard
1738       <span class="fixed">AttributeReleasePolicy</span> element referencing the
1739       appropriate <span class="fixed">xsi:schemaLocation</span> and a self-explanatory
1740       <span class="fixed">Description</span> element followed by any number of
1741       <span class="fixed">Rule</span> elements.  Each <span class="fixed">Rule</span> element must
1742       consist of a <span class="fixed">Target</span> element and one or more
1743       <span class="fixed">Attribute</span> elements.  The <span class="fixed">Target</span> element
1744       specifies the rules by which the target definition is formed.
1745       The <span class="fixed">Attribute</span> elements specifies the name and values
1746       of the attributes that may be released.</p>
1747
1748       <p>The simplest possible ARP is as follows, which releases
1749       <span class="fixed">eduPersonScopedAffiliation</span> to any target for the
1750       users the ARP applies to:</p>
1751
1752         <blockquote>
1753           <span class="fixed">
1754           &lt;?xml version=&quot;1.0&quot;?&gt;<br>
1755
1756           &lt;AttributeReleasePolicy
1757           xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot;
1758           xmlns=&quot;urn:mace:shibboleth:arp:1.0&quot;
1759           xsi:schemaLocation=&quot;urn:mace:shibboleth:arp:1.0
1760           shibboleth-arp-1.0.xsd&quot;&gt;<br>
1761
1762           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;
1763           &lt;Description&gt;Simplest possible
1764           ARP.&lt;/Description&gt;<br>
1765
1766           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;
1767           &lt;Rule&gt;<br>
1768
1769           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1770           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;Target&gt;<br>
1771
1772           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1773           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1774           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;AnyTarget/&gt;<br>
1775
1776           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1777           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/Target&gt;<br>
1778
1779           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1780           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;Attribute
1781           name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
1782
1783           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1784           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1785           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;AnyValue release=
1786           &quot;permit&quot;/&gt;<br>
1787
1788           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1789           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/Attribute
1790           &gt;<br>
1791
1792           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &lt;/Rule
1793           &gt;<br>
1794
1795           &lt;/AttributeReleasePolicy&gt;<br>
1796
1797           </span>
1798         </blockquote>
1799       </blockquote>
1800
1801       <p>All ARP's must take the same basic form.  A detailed
1802       description of how each element of the <span class="fixed">Rule</span> element
1803       may be sub-populated follows:</p>
1804
1805       <p>The <span class="fixed">Target</span> element:</p>
1806
1807       <blockquote>
1808
1809         <p><span class="fixed">Target</span> may contain either the
1810         <span class="fixed">AnyTarget</span> element, which will cause the
1811         <span class="fixed">Target</span> to always return <span class="fixed">TRUE</span>, or both the
1812         <span class="fixed">Requester</span> element, which provides for matches to be
1813         performed against the SHAR name and the <span class="fixed">Resource</span>
1814         element, which provides for matches to be performed against
1815         the requested URL.</p>
1816
1817         <p>There are three matches that may be performed by the AA
1818         in evaluating ARP's by using the <span class="fixed">matchFunction</span>
1819         component of the <span class="fixed">Requester</span> and <span class="fixed">Resource</span>
1820         elements.  The following match patterns may be
1821         specified directly following the <span class="fixed">Requester</span> or
1822         <span class="fixed">Resource</span> elements, such as <span class="fixed">&lt;Requester
1823         matchFunction=&quot;urn:mace:shibboleth:arp:matchFunction:regexMatch&quot;&gt;</span>:</p>
1824
1825         <ul type=disc>
1826           <li>
1827             <p><span class="fixed">urn:mace:shibboleth:arp:matchFunction:exactShar
1828             </span></p>
1829             <blockquote>
1830               <p>May be used with the <span class="fixed">Requester</span>
1831               element.</p>
1832
1833               <p>Evaluates to <span class="fixed">TRUE</span> when the string content
1834               of the <span class="fixed">Requester</span> element matches exactly the
1835               name of the requesting SHAR. Otherwise evaluates to
1836               <span class="fixed">FALSE</span>.  Serves as the default value
1837               associated with <span class="fixed">Requester</span> if none is
1838               specified.</p>
1839             </blockquote>
1840           </li>
1841           <li>
1842             <p><span class="fixed">urn:mace:shibboleth:arp:matchFunction:resourceTree
1843             </span></p>
1844             <blockquote>
1845               <p>May be used with the <span class="fixed">Resource</span> element.</p>
1846
1847               <p>Evaluates to <span class="fixed">TRUE</span> when the location of
1848               the resource either matches exactly or begins with
1849               the string content of the <span class="fixed">Resource</span> element.
1850               Otherwise evaluates to <span class="fixed">FALSE</span>.</p>
1851             </blockquote>
1852           </li>
1853           <li>
1854             <p><span class="fixed">urn:mace:shibboleth:arp:matchFunction:regexMatch
1855             </span></p>
1856             <blockquote>
1857               <p>May be used with both the <span class="fixed">Requester</span>
1858               and <span class="fixed">Resource</span> elements.</p>
1859
1860               <p>Evaluates to <span class="fixed">TRUE</span> when the name of the
1861               requesting SHAR or the requested URL tree is a valid
1862               match of the regular expression represented as the
1863               content of the containing element. Otherwise evaluates
1864               to <span class="fixed">FALSE</span>. Regular expressions are evaluated in
1865               accordance with the the <a
1866               href="http://java.sun.com/j2se/1.4/docs/api/java/util/
1867               regex/Pattern.html#sum">Java 1.4 Pattern API</a>.</p>
1868             </blockquote>
1869           </li>
1870         </ul>
1871
1872     </blockquote>
1873
1874       <p>The <span class="fixed">Attribute</span> element:</p>
1875
1876       <blockquote>
1877
1878         <p>The <span class="fixed">Attribute</span> element must always specify the
1879         URN of the attribute whose release parameters it specifies.
1880         Additionally, it must contain either the <span class="fixed">AnyValue</span>
1881         element or one or more <span class="fixed">Value</span> elements.  These
1882         elements, in turn, must specify either <span class="fixed">release</span> =
1883         <span class="fixed">permit</span> or <span class="fixed">deny</span>.  The <span class="fixed">Value</span>
1884         element must then contain one value for which the rule
1885         applies.  Examples:</p>
1886
1887         <blockquote>
1888           <span class="fixed">
1889           &lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot;&gt;<br>
1890           &nbsp;&nbsp;&lt;AnyValue release=&quot;Permit&quot;&gt;<br>
1891           &lt;/Attribute&gt;<br>
1892           </span><br>
1893           <p>Permits the release of <span class="fixed">eduPersonPrincipalName</span>
1894           with any value.</p>
1895         </blockquote>
1896
1897         <blockquote>
1898           <span class="fixed">
1899           &lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
1900           &nbsp;&nbsp;&lt;Value release=&quot;deny&quot;&gt;member@example.edu&lt;/Value&gt;<br>
1901           &lt;/Attribute&gt;<br>
1902           </span><br>
1903           <p>Denies the release of
1904           <span class="fixed">eduPersonScopedAffiliation</span> value
1905           <span class="fixed">member@example.edu</span>.  Other values of the
1906           attribute may still be released if so specified by a
1907           <span class="fixed">permit</span> ARP.</p>
1908         </blockquote>
1909       </blockquote>
1910
1911       <!-- ##To be included in future releases.  Not yet implemented.
1912
1913       <p>There is also a special <span class="fixed">AttributeIdentifier</span>
1914       element that allows internal references to an attribute
1915       within an ARP.  This is useful for quickly applying multiple
1916       rules to the same target.  It is used as follows:</p>
1917
1918         <blockquote>
1919           <span class="fixed">
1920           &nbsp;&nbsp;&lt;Rule&gt;<br>
1921
1922           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Target&gt;<br>
1923
1924           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;AnyTarget/&gt;<br>
1925
1926           &nbsp;&nbsp;&nbsp;&nbsp;&lt;/Target&gt;<br>
1927
1928           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Attribute
1929           name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;&gt;<br>
1930
1931           &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;Value
1932           release=&quot;permit&quot;&gt;member@example.edu&lt;/Value
1933           &gt;<br>
1934
1935           &nbsp;&nbsp;&nbsp;&nbsp;&lt;/Attribute&gt;<br>
1936
1937           &nbsp;&nbsp;&lt;/Rule&gt;<br>
1938
1939           &nbsp;&nbsp;&lt;AttributeReference identifier=&quot;http://www.example.edu/attributes/attribute1&quot;&gt;<br>
1940
1941           &nbsp;&nbsp;&lt;Attribute name=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot; identifier=&quot;http://www.example.edu/attributes/attribute1&quot;&gt;<br>
1942
1943           &nbsp;&nbsp;&nbsp;&nbsp;&lt;Value release=&quot;permit&quot;&gt;student@example.edu&lt;Value&gt;<br>
1944
1945           &nbsp;&nbsp;&lt;/Attribute&gt;<br>
1946           </span>
1947       -->
1948
1949         </blockquote>
1950     <h4><a name="5.b."></a>5.b. Sharing certificate/key pairs
1951     between Apache and Java keystores <font color="#5555EE">(optional)</font></h4>
1952
1953     <blockquote>
1954       <blockquote>
1955         <p>The JDK includes the command line program
1956         <span class="fixed">keytool</span> for managing Java keystores. This utility
1957         cannot import or export private key information, making it
1958         difficult to use the same private key and certificate for
1959         Apache and Java-based applications. The Shibboleth
1960         distribution includes <span class="fixed">extkeytool</span>, a program that
1961         can be used in conjunction with <span class="fixed">keytool</span> to perform
1962         these tasks. Select the appropriate step-by-step procedure
1963         for your situation from the following guides.</p>
1964
1965         <p>Before running <span class="fixed">extkeytool</span>, the variable
1966         SHIB_HOME must be set to the path to the directory where the
1967         Shibboleth tarball was exploded(typically
1968         /opt/shibboleth-origin-1.0/).</p>
1969
1970         <p><b>If you have a pre-exiting RSA key/certificate
1971         combination in a keystore and you would like to use it with
1972         Apache:</b></p>
1973
1974         <ol type="1">
1975           <li>
1976             <p>Determine the alias of the keystore keyEntry
1977             containing the key you would like to use in your Apache
1978             setup. Assuming that your keystore is named
1979             <span class="fixed">yourstore</span>, the following command should
1980             present a list of the entries in the keystore.</p>
1981
1982             <blockquote>
1983               <p><span class="fixed">$ keytool -list -v -keystore yourstore</span></p>
1984             </blockquote>
1985           </li>
1986
1987           <li>
1988             <p>Assuming that you identified the appropriate alias
1989             as <span class="fixed">youralias</span> and the password for the keystore
1990             is <span class="fixed">yourpass</span>, enter the following command to
1991             export the key in Base64-encoded pkcs8 format.</p>
1992
1993             <blockquote>
1994               <p><span class="fixed">$ extkeytool -exportkey -keystore yourstore
1995               -alias youralias -storepass yourpass -rfc -file
1996               yourkey.pkcs8</span></p>
1997             </blockquote>
1998           </li>
1999
2000           <li>
2001             <p>In order to use this key with Apache, you must
2002             convert it to PEM-encoded RSA native format. You have
2003             the option of storing the key unencrypted or
2004             encrypted:</p>
2005
2006             <ol type="A">
2007               <li>
2008                 <p>To use the unencrypted format, enter the
2009                 following command for the conversion:</p>
2010
2011                 <blockquote>
2012                   <p><span class="fixed">$ openssl pkcs8 -in yourkey.pkcs8
2013                   -nocrypt|openssl rsa -out yourkey.key</span></p>
2014                 </blockquote>
2015               </li>
2016
2017               <li>
2018                 <p>To use the encrypted format, enter the following
2019                 command for the conversion:</p>
2020
2021                 <blockquote>
2022                   <p><span class="fixed">$ openssl pkcs8 -in yourkey.pkcs8
2023                   -nocrypt|openssl rsa -des3 -out
2024                   yourkey.enckey</span></p>
2025                 </blockquote>
2026               </li>
2027             </ol>
2028           </li>
2029
2030           <li>
2031             <p>The following command will export the corresponding
2032             certificate.</p>
2033
2034             <blockquote>
2035               <p><span class="fixed">$ keytool -export -keystore yourstore -alias
2036               youralias -rfc -file yourcert</span></p>
2037             </blockquote>
2038           </li>
2039
2040           <li>
2041             <p>Set the <span class="fixed">mod_ssl</span>
2042             <span class="fixed">SSLCertificateKeyFile</span> and
2043             <span class="fixed">SSLCertificateFile</span> directives to point to the
2044             two files you have just created. Take care to remove
2045             any temporary files you created (i.e.
2046             <span class="fixed">yourkey.pkcs8</span>) and set appropriate file
2047             permissions, especially if you chose to store the key
2048             in an unencrypted format.</p>
2049           </li>
2050         </ol>
2051
2052         <p><b>If you have a pre-existing RSA key/certificate
2053         combination that you use with Apache and would like to
2054         import it into a java keystore:</b></p>
2055
2056         <ol type="1">
2057           <li>
2058             <p>Convert the private key to unencrypted DER-encoded
2059             pkcs8 format. Assuming your PEM-encoded key is stored
2060             in a file named <span class="fixed">yourkey.enckey</span>, enter the
2061             following command.</p>
2062
2063             <blockquote>
2064               <p><span class="fixed">$ openssl pkcs8 -in yourkey.enckey -topk8
2065               -nocrypt -outform DER -out yourkey.der.pkcs8</span></p>
2066             </blockquote>
2067           </li>
2068
2069           <li>
2070             <p>Create a certificate bundle file. This file should
2071             include a series of PEM-encoded X509 certificates
2072             representing a complete trust chain, from the root CA
2073             certificate to the certificate that matches your
2074             private key. If your certificate is stored in a file
2075             named <span class="fixed">mycert</span> and the CA signer certificate is
2076             stored in a file named <span class="fixed">ca.cert</span>, you might
2077             enter the following command to create the bundle.</p>
2078
2079             <blockquote>
2080               <p><span class="fixed">$ cat mycert ca.cert &gt; cert.bundle</span></p>
2081             </blockquote>
2082
2083             <b>Note: <span class="fixed">mod_ssl</span>-enabled Apache
2084             installations include a number of commonly recognized
2085             CA certificates in the <span class="fixed">ca-bundle.crt</span> file
2086             under the <span class="fixed">$ServerRoot/conf/ssl.crt/</span>
2087             directory.</b>
2088           </li>
2089
2090           <li>
2091             <p>Import the key and certificate into the keystore.
2092             Assuming you have already created a keystore named
2093             <span class="fixed">yourstore</span> with a password of of
2094             <span class="fixed">yourpass</span>, enter the following command to store
2095             the data under the alias <span class="fixed">youralias</span>.</p>
2096
2097             <blockquote>
2098               <p><span class="fixed">$ ./extkeytool -importkey -keystore yourstore
2099               -alias youralias -storepass yourpass -keyfile
2100               yourkey.der.pkcs8 -certfile cert.bundle -provider
2101               org.bouncycastle.jce.provider.BouncyCastleProvider</span></p>
2102             </blockquote>
2103           </li>
2104
2105           <li>
2106             <p>You can verify that the import was successful by
2107             listing entry. Use the command below.</p>
2108
2109             <blockquote>
2110               <p><span class="fixed">$ keytool -list -v -keystore yourstore -alias
2111               youralias</span></p>
2112             </blockquote>
2113           </li>
2114
2115           <li>
2116             <p>Remember to delete <span class="fixed">yourkey.der.pkcs8</span>, as it
2117             contains your unencrypted private key.</p>
2118           </li>
2119         </ol>
2120
2121         <p><b>If you are starting from scratch and do not yet have
2122         a certificate/key pair:</b></p>
2123
2124         <ol type="1">
2125           <li>
2126             <p>Generate an RSA private key. Use the command below,
2127             substituting <span class="fixed">yourkey</span> with an appropriate name
2128             to use to refer to the key.</p>
2129
2130             <blockquote>
2131               <p><span class="fixed">$ openssl genrsa -des3 -out yourkey.enckey
2132               1024</span></p>
2133             </blockquote>
2134           </li>
2135
2136           <li>
2137             <p>The following command generates a Certificate
2138             Signing Request, which should be communicated to a
2139             Certificate Authority.</p>
2140
2141             <blockquote>
2142               <p><span class="fixed">$ openssl req -new -key
2143               yourkey.enckey</span></p>
2144             </blockquote>
2145           </li>
2146
2147           <li>
2148             <p>The Certificate Authority should respond with a
2149             PEM-encoded X509 certificate. Set the <span class="fixed">mod_ssl</span>
2150             <span class="fixed">SSLCertificateKeyFile</span> directive to point to
2151             the key file you just created and the
2152             <span class="fixed">SSLCertificateFile</span> directive to point to file
2153             containing the certificate issued by the Certificate
2154             Authority. Previous sections explaion how to share the
2155             key/certificate pair with a Java keystore.</p>
2156           </li>
2157         </ol>
2158       </blockquote>
2159     </blockquote>
2160
2161     <br>
2162     <h4><a name="5.c."></a>5.c. The Attribute Resolver</h4>
2163
2164     <blockquote>
2165       <p>Shibboleth provides a powerful attribute resolver that allows
2166       origins to quickly configure the retrieval of simple attributes
2167       from standard types of attribute stores.  The resolver is configured
2168       using an xml file wich should be pointed to with the <span
2169       class="fixed">edu.internet2.middleware.shibboleth.aa.
2170       attrresolv.AttributeResolver.ResolverConfig</span> propety in <span
2171       class="fixed">origin.properties</span> as described in
2172       section <a href="#4.a.">4.a</a>.  For more complex attributes or
2173       those that require processing before release, customized Java
2174       classes will need to be written.  For more information,
2175       consult the programmer's guide.</p>
2176
2177       <p>The resolver is essentially a directed graph from attribute
2178       definitions to data connectors. The data connectors pull data, in
2179       the form of attributes, from external data sources.  The attribute
2180       definitions then process this data into a from suitable for use
2181       by Shibboleth.  This procedure can be as simple as taking an
2182       unmodified string value from a data connector and tagging it with
2183       a name or can include arbitrarily complex business rules.</p>
2184
2185       <p>The <span class="fixed">resolver.xml</span> file that is
2186       pointed to by <span class="fixed">origin.properties</span>
2187       consists of zero or more attribute definitions followed by zero or
2188       more data connectors.  Each attribute definition consists of an
2189           identifier corresponding to the URN of the attribute, and optional
2190           references to data connectors on which it depends.  Each data connector
2191       consists of a string identifier which is used by attribute
2192       definitions that refer to it, and one or more elements specific to
2193       the configuration of that data connector.</p>
2194
2195       <p>Shibboleth comes with two attribute definitions provided in
2196       version 1.0: the <span
2197       class="fixed">SimpleAttributeDefinition</span>, which acts as
2198       a basic proxy for attributes supplied by data connectors with some
2199       name conversion and attribute scoping added, and a <span
2200       class="fixed">CustomAttributeDefinition</span>, which can be
2201       used to configure user-created attribute definition plugins.
2202       Similarly, Shibboleth 1.0 comes with two data connectors: the
2203       <span class="fixed">JNDIDirectoryDataConnector</span>, which
2204       pulls data from any source for which there is a JNDI Directory
2205       Context implementation, including LDAP, NDS, etc., and the <span
2206       class="fixed">CustomDataConnector</span>, which is used to
2207       configure user-created data connector plugins.</p>
2208
2209       <p>A detailed explanation of each configuration option for the
2210       provided connectors follows:</p>
2211
2212       <p><span class="fixed">JNDIDirectoryDataConnector</span>:</p>
2213
2214       <dl>
2215         <dd class="attribute">
2216           <span class="fixed">id = &lt;string&gt;</span>
2217         </dd>
2218
2219         <dd class="value">
2220           <p>Specifies a unique, textual name for the connector used by
2221           attribute definitions to refer to and use it to build
2222           attributes.  Contained within the <span
2223           class="fixed">JNDIDirectoryDataConnector</span>
2224           element.</p>
2225         </dd>
2226
2227         <dd class="attribute">
2228           <span class="fixed">&lt;Property name=&quot;&lt;name&gt;&quot; value=&quot;&lt;value&gt;&quot;/&gt;</span>
2229         </dd>
2230
2231         <dd class="value">
2232           <p>An element of the element <span
2233           class="fixed">JNDIDirectoryDataConnector</span>.
2234           Specifies a set of name/value pairs that are used to configure
2235           the JNDI Directory Context.  This list of name/value pairs is
2236           defined by the context itself, but is specified within <span
2237           class="fixed">resolver.xml</span>.  Refer to the <a
2238           href="http://http://marsalis.internet2.edu/cgi-bin/viewcvs.cgi
2239           /shibboleth/java/src/conf/resolver.ldap.xml">Shibboleth
2240           CVS</a> for an example of names and values used to connect to
2241           an LDAP directory.</p>
2242         </dd>
2243
2244         <dd class="attributeopt">
2245           <span class="fixed">&lt;Search&gt;</span>
2246         </dd>
2247
2248         <dd class="valueopt">
2249           <p>An element of the element <span
2250           class="fixed">JNDIDirectoryDataConnector</span>.  This
2251           element defines the DN filter used to perform the LDAP search.
2252            The search string must return no more than one result.</p>
2253         </dd>
2254
2255         <dd class="attributeopt">
2256           <span class="fixed">&lt;Controls&gt;</span>
2257         </dd>
2258
2259         <dd class="valueopt">
2260           <p>An element of the element <span
2261           class="fixed">Search</span>.  This
2262           element grants some fine-grained control over the LDAP API
2263           calls.</p>
2264         </dd>
2265
2266         <dd class="attributeopt">
2267           <span class="fixed">&lt;cacheTime &quot;&lt;seconds&gt;&quot;/&gt;</span>
2268         </dd>
2269
2270         <dd class="valueopt">
2271           <p>An element of the element <span
2272           class="fixed">JNDIDirectoryDataConnector</span>.
2273           Specifies an optional duration in <span
2274           class="fixed">seconds</span> for which the attribute
2275           resolver may cache information retrieved from this
2276           connector.</p>
2277         </dd>
2278       </dl>
2279
2280       <p>A representation of a properly constructed <span
2281       class="fixed">JNDIDirectoryDataConnector</span> element would
2282       look like:</p>
2283
2284       <blockquote><span class="fixed">
2285         &lt;JNDIDirectoryDataConnector id=&quot;directory&quot;&gt;<br>
2286           &nbsp;&nbsp;&lt;Search filter=&quot;cn=%PRINCIPAL%&quot;&gt;<br>
2287             &nbsp;&nbsp;&nbsp;&nbsp;&lt;Controls searchScope=&quot;SUBTREE_SCOPE&quot; returningObjects=&quot;false&quot; /&gt;<br>
2288           &nbsp;&nbsp;&lt;/Search&gt;<br>
2289           &nbsp;&nbsp;&lt;Property name=&quot;java.naming.factory.initial&quot; value=&quot;com.sun.jndi.ldap.LdapCtxFactory&quot; /&gt;<br>
2290           &nbsp;&nbsp;&lt;cacheTime=&quot;2400&quot;/&gt;<br>
2291         &lt;/JNDIDirectoryDataConnector&gt;
2292       </span></blockquote>
2293
2294       <p><span class="fixed">SimpleAttributeDefinition</span>:</p>
2295
2296       <dl>
2297         <dd class="attribute">
2298           <span class="fixed">id = &lt;string&gt;</span>
2299         </dd>
2300
2301         <dd class="value">
2302           <p>Specifies a unique, textual name for the attribute which is
2303           used as the attribute's name when it is sent over the wire by
2304           Shibboleth.  Contained within the <span
2305           class="fixed">SimpleAttributeDefinition</span>
2306           element.</p>
2307         </dd>
2308
2309         <dd class="attributeopt">
2310           <span class="fixed">&lt;AttributeDependency / DataConnectorDependency requires=&quot;&lt;id&gt;&quot;/&gt;</span>
2311         </dd>
2312
2313         <dd class="valueopt">
2314           <p>An element of the element <span
2315           class="fixed">SimpleAttributeDefinition</span>, which may
2316           contain 0 or more of either <span
2317           class="fixed">AttributeDependency</span> or <span
2318           class="fixed">DataConnectorDependency</span>.  These
2319           specify attributes and data connectors that can be utilized by
2320           this attribute definition.  Each of these elements must
2321           contain a <span class="fixed">requires</span> statement
2322           which this attribute definition can then use to build its
2323           value.</p>
2324         </dd>
2325
2326         <dd class="attributeopt">
2327           <span class="fixed">smartScope = &quot;&lt;domain&gt;&quot;</span>
2328         </dd>
2329
2330         <dd class="valueopt">
2331           <p>Specifes a domain scope to be attached to the attribute. If
2332           the value of the attribute as retrieved from the data
2333           connector includes a pre-existing scope (<span
2334           class="fixed">bob@foo.edu</span>), that scope is used
2335           instead.  Contained within the <span
2336           class="fixed">SimpleAttributeDefinition</span>
2337           element.</p>
2338         </dd>
2339
2340         <dd class="attributeopt">
2341           <span class="fixed">sourceName = &quot;&lt;string&gt;&quot;</span>
2342         </dd>
2343
2344         <dd class="valueopt">
2345           <p>Specifies a different source attribute name to be used in
2346           calls to the data connector, while the name on the wire will
2347           be the specified <span class="fixed">id</span>.  This
2348           would be useful to send a local UniversityID attribute as
2349           eduPersonPrincipalName.  If not supplied, the connector
2350           tokenizes the <span class="fixed">id</span> field and
2351           uses the section following the <span
2352           class="fixed">#</span> to query data connectors.
2353           Contained within the <span
2354           class="fixed">SimpleAttributeDefinition</span>
2355           element.</p>
2356         </dd>
2357
2358         <dd class="attributeopt">
2359           <span class="fixed">&lt;cacheTime &quot;&lt;seconds&gt;&quot;/&gt;</span>
2360         </dd>
2361
2362         <dd class="valueopt">
2363           <p>An element of the element <span
2364           class="fixed">SimpleAttributeDefinition</span>.
2365           Specifies an optional duration in <span
2366           class="fixed">seconds</span> for which the attribute
2367           resolver may cache this attribute for use in additional
2368           assertions.</p>
2369         </dd>
2370
2371         <dd class="attributeopt">
2372           <span class="fixed">&lt;lifeTime &quot;&lt;seconds&gt;&quot;/&gt;</span>
2373         </dd>
2374
2375         <dd class="valueopt">
2376           <p>An element of the element <span
2377           class="fixed">SimpleAttributeDefinition</span>.
2378           Specifies in the attribute assertion how long the attribute
2379           should be cached and retained by the target upon receipt.
2380           Federations and trust agreements may have some bearing on the
2381           population and use of this field.</p>
2382         </dd>
2383       </dl>
2384
2385       <p>A representation of a properly constructed <span
2386       class="fixed">SimpleAttributeDefinition</span> element would
2387       look like:</p>
2388
2389       <blockquote><span class="fixed">
2390         &lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot; sourceName=&quot;universityPerson&quot;&gt;<br>
2391           &nbsp;&nbsp;&lt;DataConnectorDependency requires=&quot;dataConnector&quot;/&gt;<br>
2392           &nbsp;&nbsp;&lt;AttributeDependency requires=&quot;urn:mace:dir:attribute-def:eduPersonScopedAffiliation&quot;/&gt;<br>
2393               &nbsp;&nbsp;&lt;cacheTime=&quot;600&quot;/&gt;&lt;br&gt;<br>
2394               &nbsp;&nbsp;&lt;lifeTime=&quot;3600&quot;/&gt;&lt;br&gt;<br>
2395             &lt;/SimpleAttributeDefinition&gt;
2396       </span></blockquote>
2397
2398       <p>A properly formed <span class="fixed">resolver.xml</span>
2399       file to automatically generate a simple response for EPPN may take
2400       the form:</p>
2401
2402       <blockquote><span class="fixed">
2403          &lt;AttributeResolver xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xmlns=&quot;urn:mace:shibboleth:resolver:1.0&quot; xsi:schemaLocation=&quot;urn:mace:shibboleth:resolver:1.0 shibboleth-resolver-1.0.xsd&quot;&gt;<br>
2404              <br>
2405              &nbsp;&nbsp;&lt;SimpleAttributeDefinition id=&quot;urn:mace:dir:attribute-def:eduPersonPrincipalName&quot; smartScope=&quot;shibdev.edu&quot;&gt;<br>
2406                     &nbsp;&nbsp;&nbsp;&nbsp;&lt;DataConnectorDependency requires=&quot;echo&quot;/&gt;<br>
2407               &nbsp;&nbsp;&lt;/SimpleAttributeDefinition&gt;<br>
2408              <br>
2409         &nbsp;&nbsp;&lt;CustomDataConnector id=&quot;echo&quot;
2410                 class=&quot;edu.internet2.middleware.shibboleth.aa.attrresolv.provider.SampleConnector&quot; /&gt;<br>
2411         &lt;/AttributeResolver&gt;
2412       </span></blockquote>
2413
2414       <p>There are additional examples of <span class="fixed">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>
2415
2416     </blockquote>
2417     <br>
2418     <h4><a name="5.d."></a>5.d. Local Error Page</h4>
2419     <blockquote>
2420                 <p>Origin sites are encouraged to provide federations with the
2421                 URL of a local Shibboleth error page. If a browser user from the
2422                 origin site encounters a problem at a shibbolized target, the target
2423                 is likely to display an error page that includes a link back to this
2424                 origin provided page.</p>
2425
2426                 <p>The page should provide information on how to obtain local support
2427                 for using Shibbolized resources. It might also include suggestions on
2428                 what information should be recorded before beginning the problem
2429                 resolution process.</p>
2430     </blockquote>
2431
2432     <br>
2433     <br>
2434     <hr>
2435     <br>
2436
2437
2438     <h3><a name="6."></a>6. Troubleshooting</h3>
2439
2440     <p>This section provides basic information about testing,
2441     logging, and error handling for Shibboleth origins. This
2442     information is not intended to be comprehensive, but instead
2443     rudimentary guidelines for basic configuration tests and
2444     problems. For more detailed information or answers to specific
2445     problems not addressed in this section, please mail <a href=
2446     "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
2447     with a thorough description of errors and configurations
2448     used.</p>
2449
2450     <h4><a name="6.a."></a>6.a. Basic Testing</h4>
2451
2452     <blockquote>
2453       <p>Internet2 provides a basic target that can be used to test
2454       origin setup functionality. After your origin is recognized
2455       by InQueue, simply use any browser to access <a href=
2456       "https://wayf.internet2.edu/InQueue/sample.jsp">https://wayf.internet2.edu/InQueue/sample.jsp</a>.
2457       Select your origin's name and follow the login process as a
2458       user would. Note that SSL must be used, and both the HS and
2459       AA must be fully configured.</p>
2460
2461       <p>The test target will then display a simple page which
2462       includes the basic information sent to it by your origin and
2463       the authentication rules it is using.</p>
2464
2465       <p><b>For information regarding specific error messages that
2466       may be generated if the origin does not work successfully,
2467       please refer to section <a href="#6.c.">6.c</a>.</b></p>
2468     </blockquote>
2469
2470     <h4><a name="6.b."></a>6.b. Logging</h4>
2471
2472     <blockquote>
2473       <p>Shibboleth's origin components log various operations
2474       which may prove useful for auditing, testing, and security
2475       purposes. This data is sent through <span class="fixed">log4j</span>'s
2476       standard mechanism. The location of
2477       the log file, the level at which the log is output, the
2478       formatting of the logs, and many more options may be
2479       configured by editing
2480       <span class="fixed">/WEB-INF/classes/conf/log4j.properties</span>. By default,
2481       it is setup to log to the console of the servlet container, with a
2482       level of <span class="fixed">WARN</span>, but there is also a commented out
2483       example in the file to give a possible alternate configuration.</p>
2484     </blockquote>
2485
2486     <h4><a name="6.c."></a>6.c. Common Problems</h4>
2487
2488     <blockquote>
2489       <p>A knowledge base is being developed in the <a
2490                   href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.html">
2491                   Shibboleth Deployer's FAQ</a>.  Please mail <a href=
2492       "mailto:mace-shib-users@internet2.edu">mace-shib-users@
2493       internet2.edu</a> with any additional questions or problems
2494       encountered that are not answered by this basic guide.</p>
2495     </blockquote>
2496   </body>
2497 </html>
2498