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