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