doc/DEPLOY-GUIDE-TARGET.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2
   3 <html>
   4   <head>
   5     <title>Shibboleth Target Deployment Guide</title>
   6     <meta http-equiv="Content-Type" content=
   7     "text/html; charset=utf-8">
   8     <style type="text/css">
   9
  10 html
  11 {
  12 background-color: #FFFFFF;
  13 color: #000000;
  14 margin: .5em;
  15 }
  16 a:visited
  17 {
  18 color: #999999;
  19 }
  20 a:link
  21 {
  22 color: #990000;
  23 }
  24 a:active
  25 {
  26 color: #440000;
  27 }
  28 dl
  29 {
  30 background-color: #DDDDDD;
  31 background-image: none;
  32 margin: 5px;
  33 padding: 0px;
  34 border-style: solid;
  35 border-bottom-width: 2px;
  36 border-top-width: 2px;
  37 border-left-width: 2px;
  38 border-right-width: 2px;
  39 }
  40 dt
  41 {
  42 background-color: #DDDDDD;
  43 background-image: none;
  44 margin: 1px;
  45 padding: 1px;
  46 }
  47 dd
  48 {
  49 background-color: #DDDDDD;
  50 background-image: none;
  51 margin: 0px;
  52 padding: 1px;
  53 }
  54 .attribute
  55 {
  56 font-size: 115%;
  57 font-color: #000000;
  58 text-align: left;
  59 background-color: #DDDDDD;
  60 border: 1px black inset;
  61 background-image: none;
  62 margin: 0px;
  63 padding: 2px;
  64 }
  65 .value
  66 {
  67 font-color: #000000;
  68 text-align: left;
  69 background-color: #EEEEEE;
  70 background-image: none;
  71 padding-top: 0em;
  72 padding-bottom: 0.5em;
  73 padding-right: 1em;
  74 padding-left: 5em;
  75 border-style: solid;
  76 border-bottom-width: none;
  77 border-top-width: none;
  78 border-left-width: 1px;
  79 border-right-width: 1px;
  80 }
  81 .attributeopt
  82 {
  83 font-size: 115%;
  84 font-color: #000000;
  85 text-align: left;
  86 background-color: #BCBCEE;
  87 border: 1px black inset;
  88 background-image: none;
  89 margin: 0px;
  90 padding: 2px;
  91 }
  92 .valueopt
  93 {
  94 font-color: #000000;
  95 text-align: left;
  96 background-color: #DDDDFF;
  97 background-image: none;
  98 padding-top: 0em;
  99 padding-bottom: 0.5em;
 100 padding-right: 1em;
 101 padding-left: 5em;
 102 border-style: solid;
 103 border-bottom-width: none;
 104 border-top-width: none;
 105 border-left-width: 1px;
 106 border-right-width: 1px;
 107 }
 108 .attributelong
 109 {
 110 font-size: 85%;
 111 font-color: #000000;
 112 text-align: left;
 113 background-color: #DDDDDD;
 114 border: 1px black inset;
 115 background-image: none;
 116 margin: 0px;
 117 padding: 2px;
 118 }
 119 .attributeoptlong
 120 {
 121 font-size: 85%;
 122 font-color: #000000;
 123 text-align: left;
 124 background-color: #BCBCEE;
 125 border: 1px black inset;
 126 background-image: none;
 127 margin: 0px;
 128 padding: 2px;
 129 }
 130 .demo
 131 {
 132 background-color: #EEEEEE;
 133 padding: 3px;
 134 }
 135 .fixedwidth
 136 {
 137 font-family: monospace;
 138 font-size: 90%;
 139 font-color: #121212;
 140 }
 141
 142   </style>
 143   </head>
 144
 145   <body link="red" vlink="red" alink="black" bgcolor="white">
 146     <center>
 147       <h2>Shibboleth Target Deployment Guide</h2>
 148     </center>
 149
 150     Shibboleth Target Deployment Guide<br>
 151     draft-internet2-mace-shibboleth-shib-target-deploy-33.html<br>
 152     Nate Klingenstein<br>
 153     9 June, 2003<br>
 154     Comments should be directed to <a href=
 155     "mailto:ndk@internet2.edu">ndk@internet2.edu</a>.<br>
 156
 157     <h3>This version of the deploy guide is for Shibboleth v1.0.  For
 158     documentation related to prior versions of Shibboleth, please
 159     consult the appropriate branch in the Shibboleth CVS.</h3>
 160
 161     <h3>Federations have been abstracted out from the Shibboleth
 162     documentation.  For further information on using Shibboleth in a
 163     federation, refer to the federation guide.</h3>
 164
 165     <p>Shibboleth v1.0 is stable and secure enough to deploy in
 166     production scenarios.  While attempts have been made to include all
 167     functionality that would represent a break of interoperability with
 168     previous versions in v1.0, be aware that future versions of
 169     Shibboleth are likely to be developed and may include further
 170     implementation of the architectural document, functional
 171     enhancements, and user interface improvements.</p>
 172
 173     <p>Functionality which has been added since the previous
 174     version (v0.8) includes:</p>
 175
 176     <ul>
 177       <li>
 178         <p>Various improvements to error handling.  Origin sites are now
 179         able to supply a URL to a federation for users to be referred to
 180         when Shibboleth encounters a problem.  Targets will be able to
 181         utilize this URL in error templates.</p>
 182       </li>
 183
 184       <li>
 185         <p>The SHAR may now store its session and attribute cache in a
 186         back-end database in addition to the previously available
 187         in-memory option.  The method by which <span
 188         class="fixedwidth">sites.xml</span> is refreshed has been
 189         modified to improve robustness.</p>
 190       </li>
 191
 192       <li>
 193         <p>Attribute acceptance policies have been greatly enhanced,
 194         with filtering of attribute values by sites supported.</p>
 195       </li>
 196
 197       <li>
 198         <p>OpenSAML now populates <span
 199         class="fixedwidth">AuthType</span> element in the SAML Subject
 200         element using a value specified by origin sites using a
 201         configuration directive.  This value describes the type of
 202         authentication mechanism used at the origin site(e.g. Kerberos,
 203         PKI, etc.). This value is made available on the target side as
 204         another variable that may be used in authorization
 205         decisions.</p>
 206       </li>
 207
 208       <li>
 209         <p>Origin sites whose HS certificate is not signed by one of a
 210         federation's trusted roots are able to provide that federation
 211         with the certificate; this cert can now be stored in the sites
 212         metadata, and targets will be able to use this certificate to
 213         validate the HS' signature.</p>
 214       </li>
 215
 216       <li>
 217         <p>The AA implementation has been improved with a powerful
 218         attribute resolver.  This should greatly simplify the process of
 219         configuring the AA to support additional general attributes,
 220         while Java classes may still be written for more complex
 221         evaluations.</p>
 222       </li>
 223
 224       <li>
 225         <p>Local time string values are now used in log files.</p>
 226       </li>
 227
 228       <li>
 229         <p>Targets may now also be run under Apache on a W2K box.</p>
 230       </li>
 231     </ul>
 232
 233     <p>Before starting, please sign up for all applicable <a href=
 234     "http://shibboleth.internet2.edu/shib-misc.html#mailinglist">
 235     mailing lists</a>. Announcements pertinent to Shibboleth
 236     deployments and developments and resources for deployment
 237     assistance can be found here.</p>
 238
 239     <p>Please send any questions, concerns, or eventual confusion
 240     to <a href=
 241     "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.
 242     This should include, but not be limited to, questions about the
 243     documentation, undocumented problems, installation or
 244     operational issues, and anything else that arises. Please
 245     ensure that you have the <a href=
 246     "http://shibboleth.internet2.edu/release/shib-download.html">appropriate
 247     tarball</a> for your operating system.</p>
 248     <br>
 249     <hr>
 250     <br>
 251     <br>
 252
 253
 254     <h3><a name="TOC"></a>Shibboleth Target -- Table of
 255     Contents</h3>
 256     <br>
 257
 258
 259     <ol type="1">
 260       <li>
 261         <h4><a href="#1."><font color="black">Shibboleth
 262         Overview</font></a></h4>
 263
 264         <ol type="a">
 265           <li><a href="#1.a."><font color=
 266           "black">Origin</font></a></li>
 267
 268           <li><a href="#1.b."><font color=
 269           "black">Target</font></a></li>
 270
 271           <li><a href="#1.c."><font color=
 272           "black">WAYF</font></a></li>
 273
 274           <li><a href="#1.d."><font color=
 275           "black">Federations</font></a></li>
 276         </ol>
 277       </li>
 278
 279       <li>
 280         <h4><a href="#2."><font color=
 281         "black">Planning</font></a></h4>
 282
 283         <ol type="a">
 284           <li><a href="#2.a."><font color=
 285           "black">Requirements</font></a></li>
 286
 287           <li><a href="#2.b."><font color="black">Join a
 288           Federation</font></a></li>
 289
 290           <li><a href="#2.c."><font color="black">Security
 291           Considerations</font></a></li>
 292
 293           <li><a href="#2.d."><font color="black">Server
 294           Certs</font></a></li>
 295
 296           <li><a href="#2.e."><font color="black">Attribute Release
 297           Policies</font></a></li>
 298
 299           <li><a href="#2.f."><font color="black">Designate
 300           Contacts</font></a></li>
 301
 302           <li><a href="#2.g."><font color="black">Browser
 303           Requirements</font></a></li>
 304
 305           <li><a href="#2.h."><font color=
 306           "black">Clocks</font></a></li>
 307
 308           <li><a href="#2.i."><font color="black">Other
 309           Considerations</font></a></li>
 310         </ol>
 311       </li>
 312
 313       <li>
 314         <h4><a href="#3."><font color=
 315         "black">Installation</font></a></h4>
 316
 317         <ol type="a">
 318           <li><a href="#3.a."><font color="black">Software
 319           Requirements</font></a></li>
 320
 321           <li><a href="#3.b."><font color="black">Deploy the
 322           Shibboleth Package</font></a></li>
 323
 324           <li><a href="#3.c."><font color="black">Configure
 325           Apache</font></a></li>
 326         </ol>
 327       </li>
 328
 329       <li>
 330         <h4><a href="#4."><font color="black">Getting
 331         Running</font></a></h4>
 332
 333         <ol type="a">
 334           <li><a href="#4.a."><font color="black">Configuring
 335           <span class="fixedwidth">shibboleth.ini</span></font></a></li>
 336
 337           <li><a href="#4.b."><font color="black">Dynamic Error
 338           Page Generation</font></a></li>
 339
 340           <li><a href="#4.c."><font color="black">Key Generation
 341           and Certificate Installation</font></a></li>
 342
 343           <li><a href="#4.d."><font color="black">Protecting
 344           Webpages</font></a></li>
 345
 346           <li><a href="#4.e."><font color="black">Designing
 347           AAP's</font></a></li>
 348
 349           <li><a href="#4.f."><font color="black">Using Attributes
 350           in Applications</font></a></li>
 351
 352           <li><a href="#4.g."><font color="black"><span
 353           class="fixedwidth">siterefresh</span></font></a></li>
 354         </ol>
 355       </li>
 356
 357       <li>
 358         <h4><a href="#5."><font color=
 359         "black">Troubleshooting</font></a></h4>
 360
 361         <ol type="a">
 362           <li><a href="#5.a."><font color="black">Basic
 363           Testing</font></a></li>
 364
 365           <li><a href="#5.b."><font color="black">Common
 366           Problems</font></a></li>
 367         </ol>
 368       </li>
 369     </ol>
 370     <br>
 371     <hr>
 372     <br>
 373
 374
 375     <h3><a name="1."></a>1. Shibboleth Overview</h3>
 376
 377     <p>Shibboleth is a system designed to exchange attributes
 378     across realms for the primary purpose of authorization. It
 379     provides a secure framework for one organization to transmit
 380     attributes about a web-browsing individual across security
 381     domains to another institution. In the primary usage case, when
 382     a user attempts to access a resource at a remote domain, the
 383     user's own home security domain can send certain information
 384     about that user to the target site in a trusted exchange. These
 385     attributes can then be used by the resource to help determine
 386     whether to grant the user access to the resource. The user may
 387     have the ability to decide whether to release specific
 388     attributes to certain sites by specifying personal Attribute
 389     Release Policies (ARP's), effectively preserving privacy while
 390     still granting access based on trusted information.</p>
 391
 392     <p>When a user first tries to access a resource protected by
 393     Shibboleth, they are redirected to a service which asks the
 394     user to specify the organization from which they want to
 395     authenticate. If the user has not yet locally authenticated to
 396     a WebISO service, the user will then be redirected to their
 397     home institution's authentication system. After the user
 398     authenticates, the Shibboleth components at the local
 399     institution will generate a temporary reference to the user,
 400     known as a handle, for the individual and send this to the
 401     target site. The target site can then use the handle to ask for
 402     attributes about this individual. Based on these attributes,
 403     the target can decide whether or not to grant access to the
 404     resource. The user may then be allowed to access the requested
 405     materials.</p>
 406
 407     <p>There are several controls on privacy in Shibboleth, and
 408     mechanisms are provided to allow users to determine exactly
 409     which information about them is released. A user's actual
 410     identity isn't necessary for many access control decisions, so
 411     privacy often is needlessly compromised. Instead, the resource
 412     often utilizes other attributes such as faculty member or member
 413     of a certain class. While these are commonly determined using
 414     the identity of the user, Shibboleth provides a way to mutually
 415     refer to the same principal without revealing that principal's
 416     identity. Because the user is initially known to the target site
 417     only by a randomly generated temporary handle, if sufficient,
 418     the target site might know no more about the user than that the
 419     user is a member of the origin organization. This handle should
 420     never be used to decide whether or not to grant access, and is
 421     intended only as a temporary reference for requesting
 422     attributes.</p>
 423
 424     <h4><a name="1.a."></a>1.a. Origin</h4>
 425
 426     <blockquote>
 427       <p>There are four primary components to the origin side in
 428       Shibboleth: the Attribute Authority (AA), the Handle Service
 429       (HS), the directory service, and the local sign-on system
 430       (SSO). The AA and HS are provided with Shibboleth, and an
 431       open-source WebISO solution Pubcookie is also supplied; the
 432       directory is provided by the origin site. Shibboleth is able
 433       to interface with a directory exporting an LDAP interface or a
 434       SQL database containing user attributes, and is designed such
 435       that programming interfaces to other repositories should be
 436       readily implemented. Shibboleth relies on standard web server
 437       mechanisms to trigger local authentication. A .htaccess file
 438       can be easily used to trigger either the local WebISO system
 439       or the web server's own Basic Auth mechanism, which will
 440       likely utilize an enterprise authentication system, such as
 441       Kerberos.</p>
 442
 443       <p>From the origin site's point of view, the first contact
 444       will be the redirection of a user to the handle service,
 445       which will then consult the SSO system to determine whether
 446       the user has already been authenticated. If not, then the
 447       browser user will be asked to authenticate, and then sent
 448       back to the target URL with a handle bundled in an attribute
 449       assertion. Next, a request from the Shibboleth Attribute
 450       Requester (SHAR) will arrive at the AA which will include the
 451       previously mentioned handle. The AA then consults the ARP's
 452       for the directory entry corresponding to the handle, queries
 453       the directory for these attributes, and releases to the SHAR
 454       all attributes the SHAR is entitled to know about that
 455       user.</p>
 456     </blockquote>
 457
 458     <h4><a name="1.b."></a>1.b. Target</h4>
 459
 460     <blockquote>
 461       <p>There are three primary components to the target side in
 462       Shibboleth: the Shibboleth Indexical Reference Establisher
 463       (SHIRE), the Shibboleth Attribute Requester (SHAR), and the
 464       resource manager (RM). An implementation of each of these is
 465       included in the standard Shibboleth distribution. These
 466       components are intended to run on the same web server.</p>
 467
 468       <p>From the target's point of view, a browser will hit the RM
 469       with a request for a Shibboleth-protected resource. The RM
 470       then allows the SHIRE to step in, which will use the WAYF to
 471       acquire the name of a handle service to ask about the user.
 472       The handle service (HS) will then reply with a SAML
 473       authentication assertion containing a handle, which the SHIRE
 474       then hands off to the SHAR. The SHAR uses the handle and the
 475       supplied address of the corresponding attribute authority
 476       (AA) to request all attributes it is allowed to know about
 477       the handle. The SHAR performs some basic validation and
 478       analysis based on attribute acceptance policies (AAP's).
 479       These attributes are then handed off to the RM, which is
 480       responsible for using these attributes to decide whether to
 481       grant access.</p>
 482     </blockquote>
 483
 484     <h4><a name="1.c."></a>1.c. Where are you from? (WAYF)</h4>
 485
 486     <blockquote>
 487       <p>The WAYF service can be either outsourced and operated by a
 488       federation or deployed as part of the SHIRE. It is responsible for
 489       allowing a user to associate themself with an institution of their
 490       specification, then redirecting the user to the known address for
 491       the handle service of that institution.</p>
 492     </blockquote>
 493
 494     <h4><a name="1.d."></a>1.d. Federations</h4>
 495
 496     <blockquote>
 497       <p>A federation provides part of the underlying trust required for
 498       function of the Shibboleth architecture. A federation in the
 499       context of Shibboleth is a group of organizations(universities,
 500       corporations, content providers, etc.) who agree to exchange
 501       attributes using the SAML/Shibboleth protocols and abide by a
 502       common set of policies and practices. In so doing, they must
 503       implicitly or explicitly agree to a common set of guidelines.
 504       Joining a federation is not explicitly necessary for operation of
 505       Shibboleth, but it dramatically expands the number of targets and
 506       origins that can interact without defining bilateral agreements
 507       between all these parties.</p>
 508
 509       <p>A federation can be created in a variety of formats and trust
 510       models, but to support Shibboleth, it must provide a certain set
 511       of services to federation members. It needs to supply a registry
 512       to process applications to the federation and distribute
 513       membership information to the origin and target sites. This must
 514       include distribution of the PKI components necessary for trust
 515       between origins and targets. There also needs to be a set of
 516       agreements and best practices defined by the federation governing
 517       the exchange, use, and population of attributes before and after
 518       transit, and there should be a way to find information on local
 519       authentication and authorization practices for federation
 520       members.</p>
 521     </blockquote>
 522     <br>
 523     <br>
 524     <br>
 525     <hr>
 526     <br>
 527
 528
 529     <h3><a name="2."></a>2. Planning</h3>
 530
 531     <p>There are several essential elements that must be present in
 532     the environment to ensure Shibboleth functions well, both
 533     political and technical. Shibboleth currently runs on a
 534     specific range of platforms and web server environments. The
 535     SHAR and SHIRE are implemented entirely in C/C++. These are the
 536     recommendations and requirements for a successful implementation
 537     of a Shibboleth target.</p>
 538
 539     <h4><a name="2.a."></a>2.a. Requirements</h4>
 540
 541     <blockquote>
 542       <p>Shibboleth currently only supports Linux and Solaris. At
 543       present, Shibboleth consists of Apache plugins and a separate SHAR
 544       process. The plugins use the ONC RPC mechanism to communicate with
 545       the SHAR. The target's web servers must be running <a href=
 546       "http://http://www.apache.org/dist/httpd/">Apache</a> 1.3.26+, but
 547       not Apache 2. More precise technical details are discussed in <a
 548       href="#3.a.">3.a</a>.</p>
 549     </blockquote>
 550
 551     <h4><a name="2.b."></a>2.b. Join a Federation</h4>
 552
 553     <blockquote>
 554       <p>While it is not necessary for a target or origin to join a
 555       federation, doing so greatly facilitates the implementation of
 556       multilateral trust relationships. Each federation will have a
 557       different application process.</p>
 558
 559       <p>For more information on federations, refer to <a href=
 560       "#1.d.">1.d</a> or the Shibboleth v1.0 architectural
 561       document.</p>
 562     </blockquote>
 563
 564     <h4><a name="2.c."></a>2.c. Security Considerations</h4>
 565
 566     <blockquote>
 567       <p>Shibboleth's protocols and software have been extensively
 568       engineered to provide protection against many attacks.
 569       However, the most secure protocol can be compromised if it is
 570       placed in an insecure environment. To ensure Shibboleth is as
 571       secure as possible, there are several recommended security
 572       precautions which should be in place at local sites.</p>
 573
 574       <ol type="i">
 575         <li>
 576           <p>SSL use is optional for target sites. Federation guidelines
 577           should be considered when determining whether to
 578           implement SSL, and, in general, SSL should be used for
 579           interactions with client machines to provide the
 580           necessary authentication and encryption to ensure
 581           protection from man-in-the-middle attacks. It is strongly
 582           suggested that all password traffic or similarly
 583           sensitive data should be SSL-protected. Assessment of the
 584           risk tradeoff against possible performance degradation
 585           should be performed for all applications.</p>
 586         </li>
 587
 588         <li>
 589           <p>Many other attacks can be made on the several
 590           redirection steps that Shibboleth takes to complete
 591           attribute transfer. The best protection against this is
 592           safeguarding the WAYF service and ensuring that rogue
 593           targets and origins are not used, generally by
 594           development of the trust model underneath Shibboleth.
 595           Shibboleth also leverages DNS for security, which is not
 596           uncommon, but attacks concerning bad domain information
 597           should be considered.</p>
 598         </li>
 599
 600         <li>
 601           <p>Information regarding origin users is generally
 602           provided by the authoritative enterprise directory, and
 603           the acceptance of requests from target applications can
 604           be carefully restricted to ensure that all requests the
 605           SHAR performs are authorized and all information the
 606           origin provides is accurate. Use of plaintext passwords
 607           is strongly advised against.</p>
 608         </li>
 609
 610         <li>
 611           <p>Server platforms should be properly secured,
 612           commensurate with the level that would be expected for a
 613           campus' other security services, and cookie stores on
 614           client machines should be well protected.</p>
 615         </li>
 616       </ol>
 617     </blockquote>
 618
 619     <h4><a name="2.d."></a>2.d. Server Certs</h4>
 620
 621     <blockquote>
 622       <p>In the Shibboleth architecture, the SHAR, HS, and AA must
 623       all have various client and/or server certificates for use in
 624       signing assertions and creating SSL channels. These should be
 625       issued by a commonly accepted CA, which may be stipulated by
 626       your federation.  After understanding the CA's acceptible to your
 627       federations, consult chapter <a href="#4.c.">4.c</a> for
 628       information on certificate and key generation.</p>
 629     </blockquote>
 630
 631     <h4><a name="2.e."></a>2.e. Attribute Release Policies</h4>
 632
 633     <blockquote>
 634       <p>The Attribute Authority maintains a set of rules called
 635       Attribute Release Policies (ARP's) that define which
 636       attributes are released to which targets. When a browser user
 637       tries to access a resource, the SHAR asks the origin site AA
 638       to release all the attributes it is allowed to know. The SHAR
 639       provides its own name and an optional URL on behalf of which
 640       the attribute request is made which can further refine the
 641       information the SHAR is allowed to know. The AA processes this
 642       request using all applicable ARP's, determines which
 643       attributes and values it will release, and then obtains the
 644       values actually associated with the browser user. The AA sends
 645       these attributes and values back to the SHAR.</p>
 646
 647       <p>Targets should work together with expected origin sites to
 648       ensure that the sets of attributes that both sites expect to
 649       correspond using are congruent.</p>
 650     </blockquote>
 651
 652     <h4><a name="2.f."></a>2.f. Designate Contacts</h4>
 653
 654     <blockquote>
 655       <p>Since Shibboleth deals both with daily technical and
 656       operational issues and also with contractual issues, a set of
 657       contacts should be set up to support the user base and to
 658       facilitate interactions with other Shibboleth sites and federation
 659       members. It is recommended that at least technical and
 660       administrative contacts be designated. Names, titles, e-mail
 661       addresses, and phone numbers may all be useful information to
 662       provide.</p>
 663     </blockquote>
 664
 665     <h4><a name="2.g."></a>2.g. Browser Requirements</h4>
 666
 667     <blockquote>
 668       <p>A primary Shibboleth design consideration was to require
 669       very little or no modification to client machines. The only
 670       requirement is that a browser is used which supports cookies,
 671       redirection and SSL. Browser users will have to perform an
 672       additional click to submit the authentication assertion if
 673       JavaScript is not functional.</p>
 674     </blockquote>
 675
 676     <h4><a name="2.h."></a>2.h. Clocks</h4>
 677
 678     <blockquote>
 679       <p><a href="http://www.eecis.udel.edu/~ntp/">NTP</a> should
 680       be run on all web servers. Shibboleth employs a short handle
 681       issuance time to protect against replay attacks. Because of
 682       this, any significant degree of clock skew can hinder the
 683       ability of users to access sites successfully.</p>
 684     </blockquote>
 685
 686     <h4><a name="2.h."></a>2.i. Other Considerations</h4>
 687
 688     <blockquote>
 689       <p>Especially for higher education, there are a handful of
 690       laws enacted which may have important ramifications on the
 691       disclosure of personal information and attributes. Since
 692       Shibboleth does not necessarily need to transmit identity, it
 693       is an ideal solution for many higher education situations.
 694       Nevertheless, all parties within the United States of America
 695       are strongly advised to consult the <a href=
 696       "http://www.ed.gov/offices/OM/fpco/ferpa/">Family Educational
 697       Rights and Privacy Act of 1974(FERPA)</a>, and all other
 698       relevant state and federal legislation before deploying
 699       Shibboleth.</p>
 700     </blockquote>
 701     <br>
 702     <br>
 703     <hr>
 704     <br>
 705
 706
 707     <h3><a name="3."></a>3. Installation</h3>
 708
 709     <h4><a name="3.a."></a>3.a. Software Requirements</h4>
 710
 711     <p>The Shibboleth project makes binary packages available for
 712     Solaris and Linux that are precompiled against recent releases
 713     of various required libraries such as OpenSSL. It is highly
 714     advisable to build from source when using Shibboleth in a
 715     production environment in order to permit patching or updating
 716     of packages as security holes and bugs are fixed. Building from
 717     source is necessary to give you complete control over your
 718     deployment platform. The binary packages represent a snapshot in
 719     time only. To build from source, see the <span class="fixedwidth">INSTALL.txt</span>
 720     files in the root of the OpenSAML and Shibboleth source
 721     distributions.</p>
 722
 723     <blockquote>
 724       <b>Operating System:</b>
 725
 726       <ul type="circle">
 727         <li>
 728           RedHat 7.2-7.3:
 729
 730           <ul type="disc">
 731             <li>
 732               <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
 733
 734               <blockquote>
 735                 <p>Apache must be compiled with mod_so for DSO
 736                 module support, and must include SSL
 737                 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
 738                 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
 739                 provides). Shibboleth can coexist with
 740                 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
 741                 into the server for use elsewhere, but Shibboleth
 742                 does not need or use it.  The most recent Red Hat
 743                 RPM (1.3.23-14 as of this writing) is sufficient.
 744                 </p>
 745               </blockquote>
 746
 747               <blockquote>
 748                 <p>On Linux, Shibboleth requires that Apache and
 749                 Apache-SSL be built with <span
 750                 class="fixedwidth">libpthread</span>, or loading the
 751                 <span class="fixedwidth">mod_shibrm</span> or <span
 752                 class="fixedwidth">mod_shire</span> modules will
 753                 cause Apache to stop.  While RedHat's Apache is
 754                 compatible, Debian's Apache must be rebuilt with
 755                 <span class="fixedwidth">libpthread</span>:</p>
 756                 <blockquote>
 757                   <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
 758                   $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
 759                 </blockquote>
 760               </blockquote>
 761             </li>
 762
 763             <li><a href=
 764             "http://shibboleth.internet2.edu/release/shib-download.html">
 765             Shibboleth v1.0 Target for RedHat</a></li>
 766
 767             <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
 768             revision <span class="fixedwidth">i</span> or newer</a></li>
 769
 770             <li>
 771               libstdc++3-3.0.4-1.i386.rpm and
 772               libgcc-3.0.4-1.i386.rpm
 773
 774               <blockquote>
 775                 <p>Shibboleth binaries are currently built with <a href=
 776                 "http://www.gnu.org/software/gcc/gcc.html">GCC
 777                 3.04</a>, and require these specific library
 778                 versions. They are available as RPMs and are
 779                 available in the RedHat 7.2 updates directory on
 780                 any <a href=
 781                 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
 782                 RedHat mirror</a>. They can be installed alongside
 783                 earlier and later GCC libraries.</p>
 784               </blockquote>
 785             </li>
 786
 787             <li><b>Portions of the <span
 788             class="fixedwidth">libphp4</span> Apache plugin are written
 789             in C++, as is Shibboleth.  There is a known conflict between
 790             the PHP extensions <span
 791             class="fixedwidth">libpspell.so</span> and <span
 792             class="fixedwidth">libsablot.so</span> which will manifest
 793             itself as segmentation faults when starting Apache.  If a
 794             site wants to use <span class="fixedwidth">libphp4.so</span>
 795             and Shibboleth at once, then one of the following may be
 796             done:</b>
 797               <ol>
 798                 <li>
 799                 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
 800                 </li>
 801                 <li>
 802                 Rebuild these two modules using
 803                 the same version of GCC that was used to compile Shibboleth.
 804                 </li>
 805               </ol>
 806             </li>
 807           </ul>
 808         </li>
 809         <br>
 810         <li>
 811           Solaris 2.8:
 812
 813           <ul type="disc">
 814             <li><a href=
 815             "ftp://ftp.openssl.org/source/openssl-0.9.7a.tar.gz">
 816             openssl-0.9.7a</a>
 817
 818               <blockquote>
 819                 <p>The shared library version of OpenSSL is required
 820                 by Shibboleth.  The static libraries may be installed as
 821                 well if necessary for other applications, but cannot be
 822                 used within mod_ssl or any other Apache modules.</p>
 823               </blockquote>
 824             </li>
 825
 826             <li>
 827               <a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
 828
 829               <blockquote>
 830                 <p>Apache must be compiled with mod_so for DSO
 831                 module support, and must include SSL
 832                 support (preferably using <span class="fixedwidth">mod_ssl</span>) and EAPI
 833                 support (which <span class="fixedwidth">mod_ssl</span> requires and
 834                 provides). Shibboleth can coexist with
 835                 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
 836                 into the server for use elsewhere, but Shibboleth
 837                 does not need or use it.</p>
 838
 839                 <p><span class="fixedwidth">mod_ssl</span>'s
 840                 loadable module, <span class="fixedwidth">libssl.so</span>, must be
 841                 compiled against <span class="fixedwidth">OpenSSL
 842                 0.9.7a</span>'s shared libraries.  Other versions or
 843                 a statically linked build of <span
 844                 class="fixedwidth">libssl.so</span> will cause
 845                 failures such as bus errors when used with
 846                 Shibboleth.</p>
 847
 848                 <p>To check how OpenSSL was built, run the <span
 849                 class="fixedwidth">ldd</span> command against <span
 850                 class="fixedwidth">libssl.so</span> in the Apache
 851                 <span class="fixedwidth">/libexec/</span> folder and
 852                 check the output for references to <span
 853                 class="fixedwidth">libssl.so.0.9.7a</span>. If you
 854                 see an earlier version mentioned, or no mention of
 855                 it at all, then <span class="fixedwidth">OpenSSL
 856                 0.9.7a</span> must be rebuilt with shared libraries
 857                 from source.</p>
 858               </blockquote>
 859             </li>
 860
 861             <li><a href=
 862             "ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/libgcc-3.2.2-sol8-sparc-local.gz">
 863             libgcc v3.2.2+ and libstdc++ v3.2.2+</a></li>
 864
 865             <li><a href=
 866             "http://shibboleth.internet2.edu/release/shib-download.html">
 867             Shibboleth v1.0 Target for Solaris</a></li>
 868
 869             <li><b>Portions of the <span
 870             class="fixedwidth">libphp4</span> Apache plugin are written
 871             in C++, as is Shibboleth.  There is a known conflict with
 872             the PHP extensions <span
 873             class="fixedwidth">libpspell.so</span> and <span
 874             class="fixedwidth">libsablot.so</span> which will manifest
 875             itself as segmentation faults when starting Apache.  If a
 876             site wants to use <span class="fixedwidth">libphp4.so</span>
 877             and Shibboleth at once, then one of the following may be
 878             done:</b>
 879               <ol>
 880                 <li>
 881                 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
 882                 </li>
 883                 <li>
 884                 Rebuild these two modules using the same version of GCC
 885                 that was used to compile Shibboleth.
 886                 </li>
 887               </ol>
 888             </li>
 889           </ul>
 890         </li>
 891         <br>
 892         <li>
 893           RedHat 8:
 894            <blockquote>
 895             <p>RedHat 8 ships with Apache 2, which is not supported by
 896             Shibboleth.  To run Shibboleth under this OS, <a
 897             href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a>
 898             must be installed.</p>
 899           </blockquote>
 900               <blockquote>
 901                 <p>Apache must be compiled with mod_so for DSO
 902                 module support, and must include SSL
 903                 support (preferably using <span class="fixedwidth">mod_ssl</span>), and
 904                 EAPI support (which <span class="fixedwidth">mod_ssl</span> requires and
 905                 provides). Shibboleth can coexist with
 906                 <span class="fixedwidth">mod_auth</span>, which may be compiled or loaded
 907                 into the server for use elsewhere, but Shibboleth
 908                 does not need or use it.  The most recent Red Hat
 909                 RPM (1.3.23-14 as of this writing) is sufficient.
 910                 </p>
 911               </blockquote>
 912
 913               <blockquote>
 914                 <p>On Linux, Shibboleth requires that Apache and
 915                 Apache-SSL be built with <span
 916                 class="fixedwidth">libpthread</span>, or loading the
 917                 <span class="fixedwidth">mod_shibrm</span> or <span
 918                 class="fixedwidth">mod_shire</span> modules will
 919                 cause Apache to stop.  While RedHat's Apache is
 920                 compatible, Debian's Apache must be rebuilt with
 921                 <span class="fixedwidth">libpthread</span>:</p>
 922                 <blockquote>
 923                   <span class="fixedwidth">$ export LDFLAGS=-lpthread'<br>
 924                   $ apt-build --rebuild --reinstall install apache-common apache \ apache-ssl</span>
 925                 </blockquote>
 926               </blockquote>
 927
 928          <ul type=disc>
 929
 930             <li><a href=
 931             "http://shibboleth.internet2.edu/release/shib-download.html">
 932             Shibboleth 1.0 Target for RedHat</a></li>
 933
 934             <li><a href= "http://www.openssl.org/source/">openssl-0.9.6,
 935             revision <span class="fixedwidth">i</span> or newer</a></li>
 936
 937             <li>
 938               libstdc++3-3.0.4-1.i386.rpm and
 939               libgcc-3.0.4-1.i386.rpm
 940
 941               <blockquote>
 942                 <p>Shibboleth binaries are currently built with <a href=
 943                 "http://www.gnu.org/software/gcc/gcc.html">GCC
 944                 3.04</a>, and require these specific library
 945                 versions. They are available as RPMs and are
 946                 available in the RedHat 7.2 updates directory on
 947                 any <a href=
 948                 "ftp://rufus.w3.org/linux/redhat/updates/7.2/en/os/i386/">
 949                 RedHat mirror</a>. They can be installed alongside
 950                 earlier and later GCC libraries.</p>
 951               </blockquote>
 952             </li>
 953
 954             <li><b>Portions of the <span
 955             class="fixedwidth">libphp4</span> Apache plugin are written
 956             in C++, as is Shibboleth.  There is a known conflict with
 957             the PHP extensions <span
 958             class="fixedwidth">libpspell.so</span> and <span
 959             class="fixedwidth">libsablot.so</span> which will manifest
 960             itself as segmentation faults when starting Apache.  If a
 961             site wants to use <span class="fixedwidth">libphp4.so</span>
 962             and Shibboleth at once, then one of the following may be
 963             done:</b>
 964               <ol>
 965                 <li>
 966                 Remove the options <span class="fixedwidth">--with-pspell</span> and <span class="fixedwidth">--with-xslt-sablot</span> from PHP's configuration.
 967                 </li>
 968                 <li>
 969                 Rebuild these two modules using
 970             the same version of GCC that was used to compile Shibboleth.
 971                 </li>
 972               </ol>
 973             </li>
 974           </ul>
 975         </li>
 976       </ul>
 977     </blockquote>
 978
 979     <h4><a name="3.b."></a>3.b. Deploy the Shibboleth Package</h4>
 980
 981     <blockquote>
 982       <p>For the sake of clarity, this deployment guide assumes
 983       that standard directories are used for all installations.
 984       These directories may be changed for local implementations,
 985       but must be done so consistently.</p>
 986
 987       <ol type="1">
 988         <li>
 989           <p>Ensure that you have obtained the proper <a href=
 990           "http://shibboleth.internet2.edu/release/shib-download.html">
 991           tarball</a> for your operating system.</p>
 992         </li>
 993
 994         <li>
 995           <p>The tarballs expand into <span class="fixedwidth">/opt/shibboleth</span>,
 996           and should be expanded as <span class="fixedwidth">root</span> from <span class="fixedwidth">/</span>.
 997           You should see the following directory structure:</p>
 998
 999           <blockquote>
1000             <span class="fixedwidth">$ ls -al<br>
1001              drwxr-xr-x 10 root root 4096 Oct 24 03:54 .<br>
1002             drwxr-xr-x 3 root root 4096 Oct 24 00:37 ..<br>
1003             drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin<br>
1004             drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc<br>
1005             drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc<br>
1006             drwxr-xr-x 13 root root 4096 Oct 24 03:54 include<br>
1007             drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib<br>
1008             drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec<br>
1009             drwxr-xr-x 4 root root 4096 Oct 24 02:02 share<br>
1010             </span>
1011           </blockquote>
1012         </li>
1013       </ol>
1014     </blockquote>
1015
1016     <h4><a name="3.c."></a>3.c. Configure Apache</h4>
1017
1018     <blockquote>
1019       <ol type="1">
1020         <li>
1021           <p>Shibboleth includes configuration directives in the
1022           file <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/apache.config</span>
1023           which must be added to the httpd.conf file used locally.
1024           It is recommended that these directives simply be added
1025           to the end of the existing <span class="fixedwidth">httpd.conf</span> file
1026           rather than trying to merge it in-line;
1027           <a href="#3.c.2.">step 2</a> describes the necessary
1028           modifications to the Apache startup script. The default
1029           configuration will often work, but if customization is
1030           necessary, these options may be modified:</p>
1031
1032           <dl>
1033
1034               <dd class="attribute">
1035                   <span class="fixedwidth">LoadModule &lt;module&gt;
1036                   &lt;pathname&gt;</span>
1037               </dd>
1038
1039               <dd class="value">
1040                   <p>Specifies the title and location of the
1041                   <span class="fixedwidth">shibrm_module</span> resource manager and
1042                   <span class="fixedwidth">shire_module</span> SHIRE modules. These are
1043                   installed by default at
1044                   <span class="fixedwidth">/opt/shibboleth/libexec/mod_shibrm.so</span>
1045                   and
1046                   <span class="fixedwidth">/opt/shibboleth/libexec/mod_shire.so</span></p>
1047               </dd>
1048
1049               <dd class="attribute">
1050                   <span class="fixedwidth">SHIREConfig &lt;pathname&gt;</span>
1051               </dd>
1052
1053               <dd class="value">
1054                   <p>Specifies the <span class="fixedwidth">pathname</span> of the SHIRE's
1055                   configuration file. Defaults to
1056                   <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>.</p>
1057               </dd>
1058
1059               <dd class="attribute"><span class="fixedwidth">SHIREURL &lt;url&gt;<br>
1060               &lt;Location &lt;url&gt;&gt;<br>
1061               &nbsp;&nbsp;SetHandler &lt;method&gt;<br>
1062               &lt;/Location&gt;</span></dd>
1063
1064               <dd class="value">
1065                   <p>Specifies the <span class="fixedwidth">URL</span> and the
1066                   <span class="fixedwidth">method</span> the target uses to handle
1067                   requests for Shibboleth-protected resources.
1068                   Currently, <span class="fixedwidth">shib-shire-post</span> is the only
1069                   available handler <span class="fixedwidth">method</span>.
1070                   <span class="fixedwidth">SHIREURL</span> is used by Shibboleth when
1071                   re-directing the user to the WAYF and
1072                   <span class="fixedwidth">&lt;Location&gt;</span> by Apache; for this
1073                   reason, both <span class="fixedwidth">URL</span> specifications must
1074                   match. Note that the configuration file itself
1075                   contains &lt;&gt;'s, and <span class="fixedwidth">Location</span> should
1076                   not be replaced.</p>
1077
1078                   <p>The referenced <span class="fixedwidth">URL</span> can be either a
1079                   partial path or an absolute URL. The partial path
1080                   allows each virtual server to use its own
1081                   hostname and port in the SHIRE for session cookie
1082                   purposes, while the absolute URL forces HTTP
1083                   virtual servers to use HTTPS for the SHIRE. Use
1084                   of a full <span class="fixedwidth">https://</span> URL is advised.</p>
1085               </dd>
1086
1087               <dd class="attribute">
1088                   <span class="fixedwidth">ShibMapAttribute &lt;attribute-uri&gt;
1089                   &lt;HTTP-header&gt; [alias]</span>
1090               </dd>
1091
1092               <dd class="value">
1093                   <p>Registers attributes to be recognized and maps
1094                   them to an authorization <span class="fixedwidth">alias</span> for use
1095                   in <span class="fixedwidth">.htaccess</span> files or Location Blocks
1096                   with <span class="fixedwidth">require</span> directives.
1097                   <span class="fixedwidth">REMOTE_USER</span> is a special case, suggested
1098                   for use with <span class="fixedwidth">eduPersonPrincipalName</span>, and
1099                   is automatically checked by a <span class="fixedwidth">require
1100                   user</span> rule.</p>
1101               </dd>
1102           </dl>
1103
1104         </li>
1105
1106         <li>
1107           <a name="3.c.2."></a>
1108
1109           <p>These modifications must be made to the Apache startup
1110           script:</p>
1111
1112           <p>Add the following environment variables:</p>
1113
1114           <blockquote>
1115             <span class="fixedwidth">
1116             SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini;
1117             export SHIBCONFIG</span>
1118           </blockquote>
1119
1120           <p>If the OpenSSL libraries are not in the system's search
1121           path, they should be added to <span class="fixedwidth">LD_LIBRARY_PATH</span> as
1122           well.</p>
1123
1124           <p>If the SHIBCONFIG environment variable is not
1125           specified, Shibboleth will use
1126           <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span> by
1127           default.</p>
1128         </li>
1129
1130         <li>
1131           <p>The SHAR must be started before Apache. Among other
1132           methods, this can be done either by creating a separate
1133           SHAR startup script or by modifying Apache's RC script to
1134           start/stop the <span class="fixedwidth">SHAR</span> <b>before</b>
1135           <span class="fixedwidth">httpd</span>. It is suggested that Apache's script be
1136           modified by adding:</p>
1137
1138           <blockquote>
1139             <span class="fixedwidth">/opt/shibboleth/bin/shar &amp;</span>
1140           </blockquote>
1141
1142           <p>Sample <span class="fixedwidth">init.d</span> scripts may be included with
1143           future releases. Ensure that the environment variables
1144           referenced in <a href="#3.c.2">3.c.2</a> are in
1145           place.</p>
1146
1147         </li>
1148
1149         <li>
1150           <p>The options in <span class="fixedwidth">shibboleth.ini</span> must be
1151           configured as documented in <a href="#4.a.">4.a</a>.
1152           Apache content will then need to be modified for
1153           Shibboleth authentication. This is discussed in <a href=
1154           "#4.d.">4.d</a>. It is recommended that the target then
1155           be tested as detailed in section <a href=
1156           "#5.a.">5.a</a>.</p>
1157         </li>
1158       </ol>
1159     </blockquote>
1160     <br>
1161     <hr>
1162     <br>
1163
1164
1165     <h3><a name="4."></a>4. Getting Running</h3>
1166
1167     <h4><a name="4.a."></a>4.a. Configuring
1168     <span class="fixedwidth">shibboleth.ini</span></h4>
1169
1170     <blockquote>
1171       <p>Most of the configuration for the SHAR, SHIRE, and RM is stored
1172       in the file <span class="fixedwidth">shibboleth.ini</span>. This
1173       file is split into several pre-defined sections. The first
1174       sections, <span class="fixedwidth">general</span>, <span
1175       class="fixedwidth">shire</span>, and <span
1176       class="fixedwidth">shar</span>, define the operational parameters
1177       for the <span class="fixedwidth">SHIRE</span> and <span
1178       class="fixedwidth">SHAR</span>. The <span
1179       class="fixedwidth">general</span> section holds global tags, used
1180       by all pieces. The <span class="fixedwidth">shire</span> and <span
1181       class="fixedwidth">shar</span> sections can override the <span
1182       class="fixedwidth">general</span> tags with SHIRE- or
1183       SHAR-specific configuration. For example, if the SHAR is looking
1184       for a tag, it will look first in the <span
1185       class="fixedwidth">shar</span> section; if it does not find the
1186       tag there, it will proceed to look in the <span
1187       class="fixedwidth">general</span> section. The following
1188       sections, <span class="fixedwidth">metadata_shire</span>, <span
1189       class="fixedwidth">metadata_shar</span>, <span
1190       class="fixedwidth">attributes</span>, and <span
1191       class="fixedwidth">policies</span>, define the trust framework
1192       within the SHIRE and SHAR operate.  Example configuration files
1193       are bundled with the Shibboleth distribution.</p>
1194
1195       <p>There is also information that must be configured in
1196       <span class="fixedwidth">/usr/local/apache/conf/httpd.conf</span>; for more
1197       information, refer to <a href="#3.c.2.">3.c</a>.</p>
1198
1199       <p>Information in the logger files referenced by
1200       <span class="fixedwidth">shibboleth.ini</span> may require additional configuration.
1201       It is recommended that after initial installation is
1202       completed, the log level in both files be changed to either
1203       <span class="fixedwidth">INFO</span> or <span class="fixedwidth">WARN</span>.</p>
1204
1205       <p>Fields that are purple are optional; grey fields are
1206       mandatory.</p>
1207
1208       <p><span class="fixedwidth">[general]</span>:</p>
1209
1210       <dl>
1211           <dd class="attribute">
1212               <span class="fixedwidth">logger = &lt;pathname&gt;</span>
1213           </dd>
1214
1215           <dd class="value">
1216               <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
1217               configuration file for most Shibboleth events. This
1218               element may also be optionally specified for each of
1219               the components individually. Default logging settings
1220               should suffice. The <span class="fixedwidth">syslog</span> daemon must
1221               accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1222               <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
1223               <span class="fixedwidth">enable logging from remote machines.</span> The
1224               logging levels are defined in the logger
1225               configuration. The configuration format is similar to
1226               that of the <a
1227               href="http://jakarta.apache.org/log4j/docs/
1228               documentation.html">Log4j</a> package's format.</p>
1229           </dd>
1230
1231           <dd class="attribute">
1232               <span class="fixedwidth">schemadir = &lt;pathname&gt;</span>
1233           </dd>
1234
1235           <dd class="value">
1236               <p>Specifies the directory in which the XML schema
1237               files are located; defaults to
1238               <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>. Note that
1239               the <span class="fixedwidth">pathname</span> <b>must</b> have a trailing
1240               <span class="fixedwidth">/</span>.</p>
1241           </dd>
1242
1243           <dd class="attribute">
1244               <span class="fixedwidth">sharsocket = &lt;pathname&gt;</span>
1245           </dd>
1246
1247           <dd class="value">
1248               <p>Specifies the location of the socket the SHAR uses to
1249               form connections.</p>
1250           </dd>
1251       </dl>
1252
1253       <p>The next segment of the <span class="fixedwidth">[general]</span> configuration
1254       section defines server-specific tags in sections defined by
1255       the server name for use by the SHIRE and RM. For example, if
1256       you have a web server at www.example.edu, you can define a
1257       section <span class="fixedwidth">[www.example.edu]</span> and override global tags
1258       with tags for that server only.</p>
1259
1260       <p>The following table lists the server-specific tags. It is
1261       broken into mandatory tags, and optional tags. Tags in the <span
1262       class="fixedwidth">[general]</span> section correspond to all
1263       servers; to override specific tags on a per-server basis, use
1264       <span class="fixedwidth">[&lt;FQDN&gt;]</span> as the header for a
1265       section.</p>
1266
1267       <span class="fixedwidth">[&lt;general&gt;]</span>:
1268
1269       <dl>
1270
1271           <dd class="attributeopt">
1272               <span class="fixedwidth">normalizeRequest = &lt;true/false&gt;</span>
1273           </dd>
1274
1275           <dd class="valueopt">
1276               <p>If true, all redirects generated by
1277               <span class="fixedwidth">mod_shire</span> will be created using the virtual
1278               server name assigned to the server containing this
1279               command. If <span class="fixedwidth">false</span>, the browser's supplied
1280               URL is used to compute the redirect back.</p>
1281           </dd>
1282
1283           <dd class="attributeopt">
1284               <span class="fixedwidth">checkIPAddress = &lt;true/false&gt;</span>
1285           </dd>
1286
1287           <dd class="valueopt">
1288               <p>If <span class="fixedwidth">true</span>, Shibboleth will check client
1289               addresses for impersonation protection. In most
1290               circumstances, this should be enabled to prevent
1291               certain attacks concerning stolen cookies. Defaults
1292               to <span class="fixedwidth">false</span>.</p>
1293           </dd>
1294
1295           <dd class="attributeopt">
1296               <span class="fixedwidth">supportContact = &lt;e-mail&gt;</span>
1297           </dd>
1298
1299           <dd class="valueopt">
1300               <p>Specifies the e-mail address used in the
1301               generation of error pages.</p>
1302           </dd>
1303
1304           <dd class="attributeopt">
1305               <span class="fixedwidth">logoLocation = &lt;pathname&gt;</span>
1306           </dd>
1307
1308           <dd class="valueopt">
1309               <p>Specifies the location of the logo used in the
1310               generation of error pages. This logo can be in any
1311               format that the web browser will understand.</p>
1312           </dd>
1313
1314           <dd class="attribute">
1315               <span class="fixedwidth">wayfURL = &lt;url&gt;</span>
1316           </dd>
1317
1318           <dd class="value">
1319               <p>Specifies the URL of the WAYF service the user is
1320               redirected to. Federations will generally provide this URL
1321               or provide information on how to locally host WAYF's with
1322               a distributed hosts file. Defaults to <span
1323               class="fixedwidth">https://wayf.internet2.edu/InQueue/WAYF</span>.</p>
1324           </dd>
1325
1326           <dd class="attribute">
1327               <span class="fixedwidth">cookieName = &lt;string&gt;</span>
1328           </dd>
1329
1330           <dd class="value">
1331               <p>Defines the name to be used for session cookies.</p>
1332           </dd>
1333
1334           <dd class="attribute">
1335               <span class="fixedwidth">shireSSLOnly = &lt;true/false&gt;</span>
1336           </dd>
1337
1338           <dd class="value">
1339               <p>If <span class="fixedwidth">true</span>, the SHIRE will reject HTTP
1340               connections that are not SSL-protected. This guards the initial session
1341               sign-on from the browser, but does not preclude non-SSL content. Use of
1342               SSL is strongly recommended; see section <a href=
1343               "#2.c.">2.c</a> for more information.</p>
1344           </dd>
1345
1346           <dd class="attribute">
1347               <span class="fixedwidth">shireError = &lt;pathname&gt;</span>
1348           </dd>
1349
1350           <dd class="value">
1351               <p>Specifies the location of the template for the
1352               error page generated when there is an error
1353               re-directing the user to the WAYF or processing a
1354               SHIRE POST.</p>
1355           </dd>
1356
1357           <dd class="attribute">
1358               <span class="fixedwidth">rmError = &lt;pathname&gt;</span>
1359           </dd>
1360
1361           <dd class="value">
1362               <p>Specifies the location of the template for the
1363               error page generated if internal errors occur in the
1364               RM.</p>
1365           </dd>
1366
1367           <dd class="attribute">
1368               <span class="fixedwidth">accessError = &lt;pathname&gt;</span>
1369           </dd>
1370
1371           <dd class="value">
1372               <p>Specifies the location of the template for the
1373               page displayed to users when access to a protected
1374               resource is denied by the RM.</p>
1375           </dd>
1376       </dl>
1377
1378       <span class="fixedwidth">[shire]</span>:
1379
1380       <dl>
1381           <dd class="attribute">
1382               <span class="fixedwidth">logger = &lt;pathname&gt;</span>
1383           </dd>
1384
1385           <dd class="value">
1386               <p>Specifies the location of a <span class="fixedwidth">log4cpp</span> which
1387               overrides the <span class="fixedwidth">[general]</span> log parameters for
1388               SHIRE events.  Default logging settings should
1389               suffice. The <span class="fixedwidth">syslog</span> daemon must accept
1390               <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1391               <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
1392               <span class="fixedwidth">enable logging from remote machines.</span> The
1393               logging levels are defined in the logger
1394               configuration. The configuration format is similar to
1395               that of the <a
1396               href="http://jakarta.apache.org/log4j/docs/
1397               documentation.html">Log4j</a> package's format.</p>
1398           </dd>
1399
1400           <dd class="attributeopt">
1401               <span class="fixedwidth">aap-uri = &lt;uri&gt;</span>
1402           </dd>
1403
1404           <dd class="valueopt">
1405               <p>Specifies the URI of an attribute acceptance policy XML
1406               file. Attributes must be listed in the <span
1407               class="fixedwidth">aap-uri</span> file if they are to be
1408               visible. For more information, refer to section <a
1409               href="#4.e.">4.e</a>.</p>
1410           </dd>
1411
1412           <dd class="attributeopt">
1413               <span class="fixedwidth">metadata = &lt;tag&gt;</span>
1414           </dd>
1415
1416           <dd class="valueopt">
1417               <p>Specifies the tag that defines the section of <span
1418               class="fixedwidth">shibboleth.ini</span> the SHIRE should
1419               use to acquire its metadata. The SHIRE does not need trust
1420               metadata, and so generally it will only need sites data to
1421               enforce attribute policies like scope limitations(e.g. MIT
1422               not asserting @brown.edu attributes.)</p>
1423           </dd>
1424       </dl>
1425
1426       <span class="fixedwidth">[shar]</span>:
1427       <dl>
1428
1429           <dd class="attribute">
1430               <span class="fixedwidth">logger = &lt;pathname&gt;</span>
1431           </dd>
1432
1433           <dd class="value">
1434               <p>Specifies the location of a <span class="fixedwidth">log4cpp</span> which
1435               overrides the <span class="fixedwidth">[general]</span> log parameters for
1436               SHAR events.  Default logging settings should suffice.
1437               The <span class="fixedwidth">syslog</span> daemon must accept
1438               <span class="fixedwidth">UDP:514</span> messages, and on Linux,
1439               <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
1440               <span class="fixedwidth">enable logging from remote machines.</span> The
1441               logging levels are defined in the logger
1442               configuration. The configuration format is similar to
1443               that of the <a
1444               href="http://jakarta.apache.org/log4j/docs/
1445               documentation.html">Log4j</a> package's format.</p>
1446           </dd>
1447
1448           <dd class="attributeopt">
1449               <span class="fixedwidth">metadata = &lt;tag&gt;</span>
1450           </dd>
1451
1452           <dd class="valueopt">
1453               <p>Specifies the tag that defines the section of <span
1454               class="fixedwidth">shibboleth.ini</span> the SHAR should
1455               use to acquire its metadata.</p>
1456           </dd>
1457
1458           <dd class="attributeopt">
1459               <span class="fixedwidth">certFile = &lt;pathname&gt;</span>
1460           </dd>
1461
1462           <dd class="valueopt">
1463               <p>Specifies the location of the PEM-format
1464               certificate used by the SHAR to communicate with
1465               AA's.</p>
1466           </dd>
1467
1468           <dd class="attributeopt">
1469               <span class="fixedwidth">keyFile = &lt;pathname&gt;</span>
1470           </dd>
1471
1472           <dd class="valueopt">
1473               <p>Specifies the location of the PEM-format private
1474               key used by the SHAR to communicate with AA's.</p>
1475           </dd>
1476
1477           <dd class="attributeopt">
1478               <span class="fixedwidth">keyPass = &lt;password&gt;</span>
1479           </dd>
1480
1481           <dd class="valueopt">
1482               <p>Specifies the <span class="fixedwidth">password</span> used to access the
1483               <span class="fixedwidth">keyfile</span>.</p>
1484           </dd>
1485
1486           <dd class="attribute">
1487               <span class="fixedwidth">calist = &lt;pathname&gt;</span>
1488           </dd>
1489
1490           <dd class="value">
1491               <p>Specifies a single file of PEM-format
1492               certificates containing the certificates of root CA's
1493               the SHAR will consider valid signers of AA
1494               certificates.</p>
1495           </dd>
1496
1497           <dd class="attribute">
1498               <span class="fixedwidth">AATimeout = &lt;seconds&gt;</span>
1499           </dd>
1500
1501           <dd class="value">
1502               <p>Specifies the number of seconds that the SHAR will wait
1503               for attributes to be sent from an AA.  Defaults to <span
1504               class="fixedwidth">60</span>.</p>
1505           </dd>
1506
1507           <dd class="attribute">
1508               <span class="fixedwidth">AAConnectTimeout = &lt;seconds&gt;</span>
1509           </dd>
1510
1511           <dd class="value">
1512               <p>Specifies the number of seconds that the SHAR will wait
1513               for a connection to be established with a remote AA.
1514               Defaults to <span class="fixedwidth">30</span>.</p>
1515           </dd>
1516
1517           <dd class="attribute">
1518               <span class="fixedwidth">cacheType = &lt;method&gt;</span>
1519           </dd>
1520
1521           <dd class="value">
1522               <p>Specifies the method used by the SHAR to cache received
1523               attributes.  The default is <span
1524               class="fixedwidth">memory</span>, which indicates that
1525               Shibboleth should store received attributes in memory.
1526               Another option is <span
1527               class="fixedwidth">mysql</span>, which will use the MySQL
1528               Credential Cache.  The steps to using this are described
1529               in the MySQL Credential Cache guide.</p>
1530           </dd>
1531
1532           <dd class="attribute">
1533               <span class="fixedwidth">cacheClean = &lt;seconds&gt;</span>
1534           </dd>
1535
1536           <dd class="value">
1537               <p>Specifies the duration in seconds between cleanups of
1538               the SHAR's cached attributes.  Defaults to <span
1539               class="fixedwidth">300</span>, or 5 minutes.</p>
1540           </dd>
1541
1542           <dd class="attribute">
1543               <span class="fixedwidth">cacheTimeout = &lt;seconds&gt;</span>
1544           </dd>
1545
1546           <dd class="value">
1547               <p>Specifies the duration in <span
1548               class="fixedwidth">seconds</span> that must elapse
1549               between user accesses before that user's session is
1550               destroyed, including the associated handle and all
1551               cached attributes.  Defaults to <span
1552               class="fixedwidth">28800</span> seconds, or 8 hours.</p>
1553           </dd>
1554       </dl>
1555
1556       <p><span class="fixedwidth">[metadata]</span> sections must be
1557       created and named in accordance with the value of the <span
1558       class="fixedwidth">metadata</span> parameter in the <span
1559       class="fixedwidth">[shire]</span> and <span
1560       class="fixedwidth">[shar]</span> sections.  Metadata sections may
1561       be shared or defined for each component. Two providers are
1562       supported by Shibboleth, but additional providers may be
1563       specified with name/value pairs consisting of <span
1564       class="fixedwidth">&lt;DEFANGED_metadata provider
1565       type&gt;=&lt;source&gt;</span>.</p>
1566
1567       <p><span class="fixedwidth">[&lt;metadata&gt;]</span>:</p>
1568
1569       <dl>
1570           <dd class="attributelong">
1571               <span class="fixedwidth">edu.internet2.middleware.shibboleth.metadata.XML = &lt;pathname&gt;</span>
1572           </dd>
1573
1574           <dd class="value">
1575               <p>Specifies the location of the file to load site
1576               metadata from.  This will often be a <span
1577               class="fixedwidth">sites.xml</span> file stored locally,
1578               and may be used by both the SHIRE and SHAR.</p>
1579
1580               <p>Shibboleth provides a simple utility called <span
1581               class="fixedwidth">siterefresh</span> for updating the
1582               metadata file as described in section <a
1583               href="#4.g.">4.g</a>.</p>
1584           </dd>
1585
1586           <dd class="attributelong">
1587               <span class="fixedwidth">edu.internet2.middleware.shibboleth.trust.XML = &lt;pathname&gt;</span>
1588           </dd>
1589
1590           <dd class="value">
1591               <p>Specifies the location of the trust database of
1592               certificates and/or CA roots used by the SHAR during
1593               session initiation.  The SHIRE does not need trust
1594               data.</p>
1595           </dd>
1596       </dl>
1597
1598       <p>In order for an attribute to be used by Shibboleth, it must be
1599       recognized as valid by the SHAR and implemented with any specific
1600       rules for how to understand and express its value based on the XML
1601       from the AA. Additional string-valued attributes may be added to
1602       the SHAR using the <span class="fixedwidth">[attributes]</span>
1603       section.</p>
1604
1605       <p><span class="fixedwidth">[attributes]</span>:</p>
1606
1607       <dl>
1608           <dd class="attribute">
1609               <span class="fixedwidth">&lt;attribute_URI&gt;=&lt;type&gt;</span>
1610           </dd>
1611
1612           <dd class="value">
1613               <p>Attribute names are URI's that are assigned by the
1614               parties standardizing the attribute.  Frequently, a
1615               federation or standard object class may define these URI's.
1616               The attribute type may be either <span
1617               class="fixedwidth">scoped</span> or <span
1618               class="fixedwidth">simple</span>, which defines how
1619               the attribute is processed as described in section <a
1620               href="#4.e.">4.e</a>.</p>
1621           </dd>
1622       </dl>
1623
1624       <p>The <span class="fixedwidth">[policies]</span> section contains the policy URI
1625       values that control acceptance of assertions from origin
1626       sites.  This may eventually have multiple elements associated
1627       it for targets that are members of multiple federations.</p>
1628
1629       <p><span class="fixedwidth">[policies]</span>:</p>
1630
1631       <dl>
1632           <dd class="attribute">
1633               <span class="fixedwidth">&lt;federation&gt; = &lt;URI&gt;</span>
1634           </dd>
1635
1636           <dd class="value">
1637               <p>The name of the <span
1638               class="fixedwidth">federation</span> and its
1639               associated policy <span class="fixedwidth">URI</span>.
1640               These URI's will be provided by federations.</p>
1641
1642               <p>This set of URI values is matched against the SAML
1643               <span class="fixedwidth">Audience</span> fields of
1644               assertions received from HS's and AA's.  One of the
1645               URI's specified by the origin in <span
1646               class="fixedwidth">edu.internet2.middleware.shibboleth.audiences</span>
1647               must match one of these URIs or the
1648               assertion will not be accepted by design.</p>
1649           </dd>
1650       </dl>
1651
1652       <p>Additional sections for individual servers may be defined with
1653       either parameters overriding those found in <span
1654       class="fixedwidth">[general]</span>, or the following additional
1655       parameters:</p>
1656
1657       <p><span class="fixedwidth">[&lt;FQDN&gt;]</span>:</p>
1658
1659       <dl>
1660           <dd class="attributeopt">
1661               <span class="fixedwidth">requestAttributes = &lt;attr1&gt; &lt;attr2&gt;
1662               &lt;attr3&gt;...</span>
1663           </dd>
1664
1665           <dd class="valueopt">
1666               <p>Specifies a space-delimited list of attributes named by
1667               URI that the SHAR will request of an AA.  If the parameter
1668               does not exist or is null, then the SHAR will receive all
1669               attributes the AA is willing to release to it.</p>
1670           </dd>
1671       </dl>
1672
1673     </blockquote>
1674
1675     <h4><a name="4.b."></a>4.b. Dynamic Error Page Generation</h4>
1676
1677     <blockquote>
1678       <p>Shibboleth supports the dynamic generation of information
1679       in error pages referenced by <span class="fixedwidth">shibboleth.ini</span>. The
1680       Shib Target employs a special Markup Language Processor to
1681       insert special tags into the generated HTML. The parser will
1682       read the error file looking for any tag that looks like:</p>
1683
1684       <blockquote>
1685         <span class="fixedwidth">&lt;shibmlp tag-name /&gt;</span>
1686       </blockquote>
1687
1688       <p>Shibboleth will replace <span class="fixedwidth">tag-name</span> with the
1689       appropriate markup tag from the table below:</p>
1690
1691       <dl>
1692           <dd class="attribute"><span class="fixedwidth">supportContact</span></dd>
1693
1694           <dd class="value">The value of the <span class="fixedwidth">supportContact</span> for this
1695           server.</dd>
1696
1697           <dd class="attribute"><span class="fixedwidth">logoLocation</span></dd>
1698
1699           <dd class="value">The value of the <span
1700           class="fixedwidth">logoLocation</span> for this server.  This
1701           is used to fill in the template error page only; if a custom
1702           error page is created, then the image may be linked to
1703           statically by the page itself.</dd>
1704
1705           <dd class="attribute"><span class="fixedwidth">requestURL</span></dd>
1706
1707           <dd class="value">The user's requested URL.</dd>
1708
1709           <dd class="attribute"><span class="fixedwidth">errorType</span></dd>
1710
1711           <dd class="value">The type of error.</dd>
1712
1713           <dd class="attribute"><span class="fixedwidth">errorText</span></dd>
1714
1715           <dd class="value">The actual error message.</dd>
1716
1717           <dd class="attribute"><span class="fixedwidth">errorDesc</span></dd>
1718
1719           <dd class="value">A textual description of the error intended for human
1720           consumption.</dd>
1721       </dl>
1722
1723       <p>This configuration is only for Apache servers, and is only
1724       used by resources protected by Shibboleth.  See section <a
1725       href= "#4.d.">4.d</a>.</p>
1726
1727       <p>A sample error template is included in the Shibboleth
1728       distribution, and can be triggered by anything that will cause
1729       Shibboleth to be unable to make an authorization decision,
1730       including a bad sites file, certificate chain, or skewed
1731       clock.</p>
1732
1733     </blockquote>
1734
1735     <h4><a name="4.c."></a>4.c. Key Generation and Certificate
1736     Installation</h4>
1737
1738     <blockquote>
1739       <p>The only target component that must have a private key and
1740       certificate is the SHAR. While the target server itself should support
1741       SSL in most cases, it is mandatory for the SHAR to
1742       authenticate when contacting an AA, and it must therefore be
1743       given a key and an SSL client certificate. It is permissible
1744       for the SHAR to use the same keypair and certificate used by
1745       the target server itself, provided the certificate is signed
1746       by a CA accepted by the community of sites.</p>
1747
1748       <p>The certificate and key should be placed based on whether
1749       they will also be used for Apache's server cert. If they will
1750       be used as a server certificate as well, they should probably
1751       be in the Apache tree in the usual <span class="fixedwidth">mod_ssl</span> spot, and
1752       the SHAR can read them from there. If the SHAR is not running
1753       as <span class="fixedwidth">root</span>, permissions might need to be changed to
1754       allow this access. If the certificate and key will only be
1755       used for the SHAR, they can be put in the same folder with the
1756       <span class="fixedwidth">shibboleth.ini</span> file.</p>
1757
1758       <p>The SHAR is assigned a key and a certificate using
1759       shibboleth.ini's <span class="fixedwidth">certfile</span>, <span class="fixedwidth">keyfile</span> and
1760       <span class="fixedwidth">keypass</span>, described in <a href="#4.a.">4.a</a>. These
1761       files must currently be in PEM format. OpenSSL commands to
1762       generate a new keypair and a certificate request are shown
1763       here, assuming RSA keys are to be used:</p>
1764
1765       <blockquote>
1766         <span class="fixedwidth">$ openssl genrsa -des3 -out ssl.key 2048 $ openssl req
1767         -new -key ssl.key -out ssl.csr</span>
1768       </blockquote>
1769
1770       <p>The signed certificate file returned by the CA should be
1771       usable directly, or can be converted to PEM format using the
1772       <span class="fixedwidth">openssl x509</span> command.</p>
1773
1774       <p>The key and certificate files can be placed anywhere,
1775       though in or beneath <span class="fixedwidth">/usr/local/apache/conf
1776       directory</span> is a good choice. The Apache child processes,
1777       often running as <span class="fixedwidth">nobody</span>, must be able to read them
1778       while the server is running, which may require permission
1779       changes.</p>
1780
1781       <p>This particularly applies when sharing the key and
1782       certificate used by mod_ssl, which are only readable by root
1783       by default. The password, if any, must be placed in the conf
1784       file, since the module cannot prompt for it as the initial
1785       startup of mod_ssl can. The issues surrounding how to
1786       securely obtain a key while running as <span class="fixedwidth">nobody</span> will
1787       be addressed in a later release. Since the password will be
1788       stored in clear text in a frequently examined file, it is
1789       suggested to not reuse a password used elsewhere, or to place
1790       the <span class="fixedwidth">keypass</span> directive in a separate file that is
1791       <span class="fixedwidth">Included</span> in the main configuration file, so that its
1792       permissions can be further restricted.</p>
1793
1794       <p>Finally, the <span class="fixedwidth">calist</span> command provides the SHAR
1795       with a set of CA roots to trust when validating AA server
1796       certificates. In all cases, the SHAR verifies that the
1797       certificate's CN equals the AA's hostname, but the CA root
1798       bundle restricts the accepdl signers to those permitted by
1799       the SHAR. The parameter can be omitted to skip such signer
1800       validation.</p>
1801     </blockquote>
1802
1803     <h4><a name="4.d."></a>4.d. Protecting Webpages</h4>
1804
1805     <blockquote>
1806       <p>Protection of webpages is primarily achieved through
1807       "mapping" attributes provided by an AA to a localized
1808       vocabulary for authorization rules. Each attribute can be
1809       mapped using the <span class="fixedwidth">ShibMapAttribute</span> command to an HTTP
1810       header name where it can subsequently be accessed by
1811       applications, and optionally to an <span class="fixedwidth">alias</span> that can be
1812       used in a <span class="fixedwidth">Require</span> command to search for a matching
1813       value. This mapping command must be in <span class="fixedwidth">httpd.conf</span>,
1814       while the rest of the commands described here appear in
1815       content-specific configuration or <span class="fixedwidth">.htaccess</span>
1816       files.</p>
1817
1818       <p>Any of the typical ways of protecting content may be used
1819       (.htaccess, Directory, Location, Files, etc.). There are two
1820       ways to trigger Shibboleth authentication: specifying an
1821       <span class="fixedwidth">AuthType</span> of <span class="fixedwidth">shibboleth</span> to use Shibboleth
1822       directly, or specifying <span class="fixedwidth">ShibBasicHijack On</span> to
1823       process existing .htaccess files using Shibboleth instead.
1824       Support for authorization consists of mod_auth-style require
1825       directives, as well as support for mod_auth group files.</p>
1826
1827       <p>A complete list of the directives and their values is
1828       below:</p>
1829
1830       <dl>
1831           <dd class="attribute">
1832               <span class="fixedwidth">AuthType &lt;string&gt;</span>
1833           </dd>
1834
1835           <dd class="value">
1836               <p>Use <span class="fixedwidth">shibboleth</span> for direct invocation, or
1837               <span class="fixedwidth">Basic</span> plus the <span class="fixedwidth">ShibBasicHijack On</span>
1838               option described below.</p>
1839           </dd>
1840
1841           <dd class="attribute">
1842               <span class="fixedwidth">ShibSSLOnly&lt;on/off&gt;</span>
1843           </dd>
1844
1845           <dd class="value">
1846               <p>Controls whether Shibboleth will reject non-SSL
1847               requests from clients. Defaults to <span class="fixedwidth">off</span>.</p>
1848           </dd>
1849
1850           <dd class="attribute">
1851               <span class="fixedwidth">ShibBasicHijack &lt;on/off&gt;</span>
1852           </dd>
1853
1854           <dd class="value">
1855               <p>Controls whether Shibboleth should or should not
1856               ignore requests for <span class="fixedwidth">AuthType Basic</span>. Defaults
1857               to <span class="fixedwidth">off</span>.</p>
1858           </dd>
1859
1860           <dd class="attribute">
1861               <span class="fixedwidth">ShibAuthTimeout &lt;seconds&gt;</span>
1862           </dd>
1863
1864           <dd class="value">
1865               <p>Sets the maximum number of seconds without any
1866               user activity that a session will remain alive. After
1867               <span class="fixedwidth">seconds</span> seconds without activity, the
1868               session is considered dead. Omission or <span class="fixedwidth">0</span>
1869               results in an arbitrary session timeout.</p>
1870           </dd>
1871
1872           <dd class="attribute">
1873               <span class="fixedwidth">ShibExportAssertion &lt;on/off&gt;</span>
1874           </dd>
1875
1876           <dd class="value">
1877               <p>Controls whether the SAML attribute assertion
1878               provided by the AA is exported in a base64-encoded
1879               HTTP header, <span class="fixedwidth">Shib-Attributes</span>. Defaults to
1880               <span class="fixedwidth">off</span>.</p>
1881           </dd>
1882
1883           <dd class="attribute">
1884               <span class="fixedwidth">ShibAuthLifetime &lt;seconds&gt;</span>
1885           </dd>
1886
1887           <dd class="value">
1888               <p>Sets the maximum lifetime in seconds that a user
1889               session can survive. Omission or zero results in
1890               arbitrary session lifetime.</p>
1891           </dd>
1892
1893           <dd class="attribute">
1894               <span class="fixedwidth">AuthGroupFile &lt;pathname&gt;</span>
1895           </dd>
1896
1897           <dd class="value">
1898               <p>Same as mod_auth; collects EPPN's into a named
1899               group for access control. Note that mod_auth will not
1900               support group files when mod_shibrm is loaded, since
1901               they share the same command.</p>
1902
1903
1904             <blockquote>
1905               <p><a href=
1906               "http://httpd.apache.org/docs/mod/core.html#require">This
1907               is implemented</a> by placing a <span class="fixedwidth">.htaccess</span>
1908               file that references an <span class="fixedwidth">AuthGroupFile</span> stored
1909               at <span class="fixedwidth">/path</span>:</p>
1910
1911               <blockquote>
1912                 <span class="fixedwidth">authgroupfile /path<br>
1913                 require group workgroup</span>
1914               </blockquote>
1915
1916               <p>Note that an <a href=
1917               "http://httpd.apache.org/docs/mod/mod_auth.html#authgroupfile">
1918               AuthGroupFile</a> used by Shibboleth would resemble
1919               <span class="fixedwidth">workgroup: joe@example.edu, jane@demo.edu,
1920               jim@sample.edu</span>.</p>
1921             </blockquote>
1922           </dd>
1923
1924           <dd class="attribute">
1925               <span class="fixedwidth">Require &lt;string&gt;</span>
1926           </dd>
1927
1928           <dd class="value">
1929             <p>Enforce authorization using one of the following methods.
1930             <b>Please note that <span
1931             class="fixedwidth">valid-user</span> is not a valid access
1932             rule because there it is not clear what <span
1933             class="fixedwidth">valid-user</span> would signify in the
1934             context of Shibboleth</b>.</p>
1935
1936             <ul type="circle">
1937               <li>
1938
1939               <li>
1940                 <span class="fixedwidth">valid-user</span>
1941
1942                 <blockquote>
1943                   <p>Any Shibboleth user from a trusted origin site
1944                   is accepted.</p>
1945                 </blockquote>
1946               </li>
1947
1948                 <span class="fixedwidth">user</span>
1949
1950                 <blockquote>
1951                   <p>A space-delimited list of EPPN values,
1952                   provided that the
1953                   <span class="fixedwidth">urn:mace:eduPerson:1.0:eduPersonPrincipalName</span>
1954                   attribute has been mapped to the
1955                   <span class="fixedwidth">REMOTE_USER</span> header (as per the earlier
1956                   example configuration commands).</p>
1957                 </blockquote>
1958               </li>
1959
1960               <li>
1961                 <span class="fixedwidth">group</span>
1962
1963                 <blockquote>
1964                   <p>A space-delimited list of group names defined
1965                   within <span class="fixedwidth">AuthGroupFile</span> files, again
1966                   provided that the mapping to <span class="fixedwidth">REMOTE_USER</span>
1967                   exists.</p>
1968                 </blockquote>
1969               </li>
1970
1971               <li>
1972                 <span class="fixedwidth">&lt;alias&gt;</span>
1973
1974                 <blockquote>
1975                   <p>An arbitrary rule tag that matches an alias
1976                   defined in a <span class="fixedwidth">ShibMapAttribute</span> server
1977                   command. The rule value is a space- delimited
1978                   list of attribute values, whose format depends on
1979                   the attribute in question (e.g. an affiliation
1980                   rule might look like <span class="fixedwidth">require affiliation
1981                   staff@osu.edu faculty@mit.edu</span>).</p>
1982                 </blockquote>
1983               </li>
1984             </ul>
1985
1986             <p>Additionally, for <span class="fixedwidth">user</span> and
1987             <span class="fixedwidth">&lt;alias&gt;</span>-based rules, if a tilde character
1988             is placed immediately following <span class="fixedwidth">user</span> or
1989             <span class="fixedwidth">&lt;alias&gt;</span>, the expressions that follow are
1990             treated as regular expressions.</p>
1991
1992             <p>For example, the regular expression AAP <span
1993             class="fixedwidth">require affiliation ~
1994             ^member@.+\.edu$</span> would evaluate to allowing
1995             anyone with an <span
1996             class="fixedwidth">eduPersonScopedAffiliation</span> of
1997             <span class="fixedwidth">member</span> from a .edu
1998             domain.</p>
1999
2000           </dd>
2001         </dl>
2002       <br>
2003     </blockquote>
2004
2005     <h4><a name="4.e."></a>4.e. Designing AAP's</h4>
2006
2007     <blockquote>
2008       <p>Shibboleth allows a user and a site to release a varying
2009       set of attributes to a destination site, and does not impose
2010       restrictions on the kinds of attribute information provided
2011       by an AA. Target implementations must also be prepared to
2012       examine the attributes they receive and filter them based on
2013       policies about what information to permit an origin site to
2014       assert about its users.</p>
2015
2016       <p>Attribute acceptance is the process of filtering attribute
2017       values before passing them on to a resource manager, such as
2018       the <span class="fixedwidth">mod_shibrm</span> module. Data blocked by AAP filters
2019       will not be passed to the CGI environment or used when
2020       enforcing <span class="fixedwidth">.htaccess</span> rules.
2021       Note that the attribute assertion exported to the
2022       <span class="fixedwidth">Shib-Attributes</span> header is pre-filtered.</p>
2023
2024       <p>The Shibboleth distribution <span class="fixedwidth">scoped</span> and
2025       <span class="fixedwidth">simple</span> filtering policies for different kinds of
2026       attributes.</p>
2027
2028       <p><b>An essential part of the Shibboleth trust fabric is ensuring
2029       that sites only assert attributes for domains for which they are
2030       considered authoritative by the target.  Typically, this means
2031       that Brown University will be trusted to assert attributes only
2032       scoped to <span class="fixedwidth">*brown.edu</span>.  Unless
2033       there are very specific circumstances requiring this restriction
2034       be removed, it is strongly encouraged that it be included in any
2035       and all AAP's.</b></p>
2036
2037       <h4>Scoped:</h4>
2038       <blockquote>
2039         <p>Scoped attributes are a special kind of attribute whose
2040         values are a combination of a <span class="fixedwidth">value</span> and a
2041         <span class="fixedwidth">scope</span>, or <span class="fixedwidth">context</span> for the value. An
2042         example is <span class="fixedwidth">eduPersonScopedAffiliation</span>, which adds a
2043         scope to the defined set of <span class="fixedwidth">eduPersonAffiliation</span>
2044         values, such as <span class="fixedwidth">student</span>, <span class="fixedwidth">member</span>, or
2045         <span class="fixedwidth">faculty</span>. Scopes are expressed as DNS domains and
2046         subdomains.</p>
2047
2048         <p>Any <span class="fixedwidth">scoped</span> attribute can be
2049         scoped only to the origin site's permitted domains. These
2050         domains are listed in the sites file that provides trust
2051         information to the system. Domains can be explicit or
2052         regular expressions, and can be changed by a target to meet
2053         its needs if a local version of the file is created. Thus,
2054         attribute acceptance processing for <span class="fixedwidth">scoped</span>
2055         attributes is based on the sites file.</p>
2056       </blockquote>
2057
2058       <h4>Simple:</h4>
2059       <blockquote>
2060         <p>Simple attributes are attributes whose value is expressed
2061         in XML as a Text node; that is, the value is just a string.
2062         Multiple values are permitted.
2063         <span class="fixedwidth">eduPersonEntitlement</span>, in which the values are URIs,
2064         is one example of a simple attribute.</p>
2065         <p>In this release, simple attribute acceptance is
2066         controlled with an external policy file written in XML. The
2067         schema for the file is described by the
2068         <span class="fixedwidth">eduPerson.xsd</span> schema, and an example file is
2069         included, <span class="fixedwidth">AAP.xml</span>. If the <span class="fixedwidth">aap-uri</span>
2070         parameter in the <span class="fixedwidth">shibboleth.ini</span> file is left out,
2071         then no policy is applied, and no filtering is done.
2072         Otherwise, the rules encoded in the file are used.</p>
2073         <p>The policy is a default-deny algorithm that requires
2074         permissible attributes and values be listed explicitly. That
2075         is, an empty file permits nothing. Each attribute to be
2076         permitted must be listed in the file by name in an
2077         <span class="fixedwidth">&lt;AttributeRule&gt;</span>. Each such rule is a
2078         collection of <span class="fixedwidth">&lt;SiteRule&gt;</span> elements along with
2079         an optional <span class="fixedwidth">&lt;AnySite&gt;</span> default rule. In turn
2080         each site rule is a set of <span class="fixedwidth">&lt;Value&gt;</span> rules that
2081         specify matches to permit, either literal or regular
2082         expressions.</p>
2083       </blockquote>
2084
2085       <p>A syntax summary follows:</p>
2086       <blockquote>
2087
2088         <p><span class="fixedwidth">&lt;AttributeAcceptancePolicy</span></p>
2089           <blockquote>The top level element in the
2090           file.</blockquote>
2091
2092         <p><span class="fixedwidth">&lt;AttributeRule Name=&quot;attribute
2093         URI&quot;&gt;</span></p>
2094           <blockquote>Specifies a rule for an attribute, named with
2095           its URI.</blockquote>
2096         <p><span class="fixedwidth">&lt;AnySite&gt;</span></p>
2097           <blockquote>Specifies a rule that always applies to the
2098           attribute, regardless of the asserting AA.</blockquote>
2099
2100         <p><span class="fixedwidth">&lt;SiteRule
2101         Name=&quot;site.domain.name&quot;&gt;</span></p>
2102           <blockquote>A rule that applies to the origin site AA
2103           corresponding to the domain name.</blockquote>
2104
2105         <p><span class="fixedwidth">&lt;Value Type=&quot;type&quot;&gt;</span></p>
2106           <blockquote>Specifies a value to permit, either directly
2107           using <span class="fixedwidth">type</span> <span class="fixedwidth">literal</span>, or using a set of
2108           matching expressions as <span class="fixedwidth">type</span> <span class="fixedwidth">regexp</span>.
2109           <span class="fixedwidth">literal</span> is the default if <span class="fixedwidth">Type</span> is not
2110           specified.</blockquote>
2111
2112        </blockquote>
2113
2114        <p>The regular expression syntax is a subset of the usual
2115        Perl and Unix syntaxes that is described in the XML Schema
2116        specification by the W3C. Most typical expressions should
2117        work. Be sure to anchor them using <span class="fixedwidth">^</span> and <span class="fixedwidth">$</span>
2118        to avoid unintentional matches midstring.</p>
2119
2120        <p>Note that the AAP rules described in this section are not
2121        part of the Shibboleth architecture and are simply one
2122        possible set of approaches implemented in the
2123        <span class="fixedwidth">eduPerson</span> attribute plugin. The OpenSAML API permits
2124        attribute classes to derive from <span class="fixedwidth">SAMLAttribute</span> and
2125        override the accept() method to implement
2126        application-specific AAP requirements. The eduPerson source
2127        files can be used as an example of how to build highly
2128        customized rules.</p>
2129     </blockquote>
2130
2131     <h4><a name="4.f."></a>4.f. Using Attributes in
2132     Applications</h4>
2133
2134     <blockquote>
2135       <p>Apart from the simple RM functionality provided, attribute
2136       information may be made available directly to applications
2137       via the standard practice of creating custom HTTP request
2138       headers before passing control to the application.
2139       Applications should make no assumption about the presence of
2140       specific attributes for their use unless they have intimate
2141       knowledge of the attribute release policies in place.</p>
2142
2143       <p>The <span class="fixedwidth">ShibMapAttribute</span> directive controls this
2144       interface, and maps a Shibboleth attribute (identified by an
2145       unambiguous URI) to a header name, such as
2146       <span class="fixedwidth">Shib-EP-Affiliation</span>. Using that example, any values
2147       of the mapped attribute will be placed in that header,
2148       delimited by spaces. An application that uses a CGI-like
2149       syntax to access the header will find the values in the
2150       <span class="fixedwidth">HTTP_SHIB_EP_AFFILIATION</span> variable. Using the
2151       command, any attribute can be placed in any header, to drive
2152       legacy applications that expect information in a particular
2153       header.</p>
2154
2155       <p>The <span class="fixedwidth">REMOTE_USER</span> variable is a special case that
2156       is generally populated automatically by the web server based
2157       on an internal piece of data that represents the user's
2158       <span class="fixedwidth">username</span>. Unlike many authentication modules,
2159       Shibboleth does not guarantee that <span class="fixedwidth">REMOTE_USER</span> will
2160       have any value. If it does, it is set solely based on a
2161       <span class="fixedwidth">ShibMapAttribute</span> command. For most purposes, the
2162       <span class="fixedwidth">urn:mace:eduPerson:1.0:eduPersonPrincipalName</span>
2163       attribute should be mapped to <span class="fixedwidth">REMOTE_USER</span>. Even so,
2164       EPPN may not be provided by the AA, and <span class="fixedwidth">REMOTE_USER</span>
2165       might still be empty.</p>
2166
2167       <p>Finally, the <span class="fixedwidth">ShibExportAssertion</span> flag instructs
2168       the module to place the entire XML message containing the
2169       SAML attribute information from the AA into a base64-encoded
2170       header called <span class="fixedwidth">Shib-Attributes</span>. This is a raw
2171       interface that provides an application with the entire AA
2172       response, and is not a filtered view based on any attribute
2173       acceptance rules or even based on what attributes are
2174       recognized by the target. What was sent is what you see.</p>
2175     </blockquote>
2176
2177     <h4><a name="4.g."></a>4.g. <span
2178     class="fixedwidth">siterefresh</span></h4>
2179
2180     <blockquote>
2181       <p>Shibboleth provides a simple tool called <span
2182       class="fixedwidth">siterefresh</span> in the <span
2183       class="fixedwidth">/opt/shibboleth/bin</span> folder of the
2184       distribution to maintain metadata files referenced by <span
2185       class="fixedwidth">shibboleth.ini</span>.  It will return 0 on
2186       success and a negative number on failure and log errors to <span
2187       class="fixedwidth">stderr</span>.  If the data in the new metadata
2188       file is bad or the signature is invalid, the existing copy is
2189       kept.  The SHAR and SHIRE stat the file each time the data is
2190       used, allowing them to detect and utilize updates in real-time
2191       operation.</p>
2192
2193       <p><span class="fixedwidth">siterefresh</span> takes the following
2194       command-line parameters:</p>
2195
2196       <dl>
2197         <dd class="attribute">
2198           <span class="fixedwidth">--url &lt;URL&gt;</span>
2199         </dd>
2200
2201         <dd class="value">
2202           <p>Specifies the <span class="fixedwidth">URL</span> of the
2203           remote metadata file to update the local file.</p>
2204         </dd>
2205
2206         <dd class="attribute">
2207           <span class="fixedwidth">--out &lt;pathname&gt;</span>
2208         </dd>
2209
2210         <dd class="value">
2211           <p>Specifies the local file to write the new metadata to.</p>
2212         </dd>
2213
2214         <dd class="attributeopt">
2215           <span class="fixedwidth">--cert &lt;pathname&gt;</span>
2216         </dd>
2217
2218         <dd class="valueopt">
2219           <p>Specifies the location of a certificate stored in <span
2220           class="fixedwidth">PEM</span> format used to validate the
2221           signature of the metadata file.  Since much of Shibboleth's
2222           trust flows from this metadata file, this option is highly
2223           recommended.</p>
2224         </dd>
2225
2226         <dd class="attributeopt">
2227           <span class="fixedwidth">--schema &lt;pathname&gt;</span>
2228         </dd>
2229
2230         <dd class="valueopt">
2231           <p>Optionally defines a base path for schemas.  Defaults to
2232           <span
2233           class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
2234         </dd>
2235        </dl>
2236
2237        <p>A complete command issued to <span
2238        class="fixedwidth">siterefresh</span> would take the form:</p>
2239
2240        <blockquote><span class="fixedwidth">
2241          /opt/shibboleth/bin/siterefresh --url
2242          http://wayf.internet2.edu/InQueue/sites.xml --out sites.xml
2243          --cert internet2.pem
2244        </span></blockquote>
2245
2246        <p>It is recommended that a similar command be added to a <span
2247        class="fixedwidth">crontab</span> to keep the file refreshed.</p>
2248     </blockquote>
2249
2250
2251     <br>
2252     <hr>
2253     <br>
2254
2255     <h3><a name="5."></a>5. Troubleshooting</h3>
2256
2257     <p>This section provides basic information about testing
2258     Shibboleth targets. This information is not intended to be
2259     comprehensive, but instead rudimentary guidelines for basic
2260     configuration tests and problems. For more detailed information
2261     or answers to specific problems not addressed in this section,
2262     please mail <a href=
2263     "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
2264     with a thorough description of errors and configurations
2265     used.</p>
2266
2267     <h4><a name="5.a."></a>5.a. Basic Testing</h4>
2268
2269     <blockquote>
2270       <p>The target may be tested by generating a folder with very
2271       basic access controls on it, and accessing it using a web
2272       browser. Place a simple webpage such as <span class="fixedwidth">index.html</span>
2273       in <span class="fixedwidth">/secure/</span>. Then, add the following lines to
2274       <span class="fixedwidth">httpd.conf</span>, which should be removed when testing is
2275       over:</p>
2276
2277       <blockquote>
2278         <span class="fixedwidth"># Configure a test directory<br>
2279         &lt;Location /secure&gt;<br>
2280         &nbsp;&nbsp;AuthType shibboleth<br>
2281         &nbsp;&nbsp;require valid-user<br>
2282         <br>
2283         &nbsp;&nbsp;# Per-directory SHIRE Configuration<br>
2284         &nbsp;&nbsp;#ShibBasicHijack On<br>
2285         &nbsp;&nbsp;#ShibSSLOnly On<br>
2286         &nbsp;&nbsp;#ShibAuthLifetime 60<br>
2287         &nbsp;&nbsp;#ShibAuthTimeout 600<br>
2288         <br>
2289         &nbsp;&nbsp;# RM Configuration<br>
2290         &nbsp;&nbsp;#AuthGroupFile /foo<br>
2291         &nbsp;&nbsp;#ShibExportAssertion On<br>
2292         &lt;/Location&gt;<br>
2293         </span>
2294       </blockquote>
2295
2296       <p><b>For information regarding specific error messages that
2297       may be generated if the target does not work successfully,
2298       please refer to section <a href="#4.b.">4.b</a>, or write <a
2299       href=
2300       "mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>.</b></p>
2301     </blockquote>
2302
2303     <h4><a name="5.b."></a>5.b. Common Problems</h4>
2304
2305     <blockquote>
2306       <p>A knowledge base is being developed in the <a
2307       href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.
2308       html">Shibboleth Deployer's FAQ</a>.  Please mail <a href=
2309       "mailto:mace-shib-users@internet2.edu">mace-shib-users@
2310       internet2.edu</a> with any additional questions or problems
2311       encountered that are not answered by this basic guide.</p>
2312     </blockquote>
2313   </body>
2314 </html>