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