doc/DEPLOY-GUIDE-ORIGIN.html

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