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