doc/InQueue.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3         <head>
   4                 <title>InQueue Federation Policy and Configuration Guidelines</title>
   5                 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6                 <style type="text/css">
   7
   8                         html
   9                         {
  10                                 background-color: #FFFFFF;
  11                                 color: #000000;
  12                                 margin: .5em;
  13                         }
  14                         a:visited
  15                         {
  16                                 color: #999999;
  17                         }
  18                         a:link
  19                         {
  20                                 color: #990000;
  21                         }
  22                         a:active
  23                         {
  24                                 color: #440000;
  25                         }
  26                         dl
  27                         {
  28                                 background-color: #DDDDDD;
  29                                 background-image: none;
  30                                 margin: 5px;
  31                                 padding: 0px;
  32                                 border-style: solid;
  33                                 border-bottom-width: 2px;
  34                                 border-top-width: 2px;
  35                                 border-left-width: 2px;
  36                                 border-right-width: 2px;
  37                         }
  38                         dt
  39                         {
  40                                 background-color: #DDDDDD;
  41                                 background-image: none;
  42                                 margin: 1px;
  43                                 padding: 1px;
  44                         }
  45                         dd
  46                         {
  47                                 background-color: #DDDDDD;
  48                                 background-image: none;
  49                                 margin: 0px;
  50                                 padding: 1px;
  51                         }
  52                         .attribute
  53                         {
  54                                 font-size: 115%;
  55                                 font-color: #000000;
  56                                 text-align: left;
  57                                 background-color: #DDDDDD;
  58                                 border: 1px black inset;
  59                                 background-image: none;
  60                                 margin: 0px;
  61                                 padding: 2px;
  62                         }
  63                         .value
  64                         {
  65                                 font-color: #000000;
  66                                 text-align: left;
  67                                 background-color: #EEEEEE;
  68                                 background-image: none;
  69                                 padding-top: 0em;
  70                                 padding-bottom: 0.5em;
  71                                 padding-right: 1em;
  72                                 padding-left: 5em;
  73                                 border-style: solid;
  74                                 border-bottom-width: none;
  75                                 border-top-width: none;
  76                                 border-left-width: 1px;
  77                                 border-right-width: 1px;
  78                         }
  79                         .attributeopt
  80                         {
  81                                 font-size: 115%;
  82                                 font-color: #000000;
  83                                 text-align: left;
  84                                 background-color: #BCBCEE;
  85                                 border: 1px black inset;
  86                                 background-image: none;
  87                                 margin: 0px;
  88                                 padding: 2px;
  89                         }
  90                         .valueopt
  91                         {
  92                                 font-color: #000000;
  93                                 text-align: left;
  94                                 background-color: #DDDDFF;
  95                                 background-image: none;
  96                                 padding-top: 0em;
  97                                 padding-bottom: 0.5em;
  98                                 padding-right: 1em;
  99                                 padding-left: 5em;
 100                                 border-style: solid;
 101                                 border-bottom-width: none;
 102                                 border-top-width: none;
 103                                 border-left-width: 1px;
 104                                 border-right-width: 1px;
 105                         }
 106                         .attributelong
 107                         {
 108                                 font-size: 85%;
 109                                 font-color: #000000;
 110                                 text-align: left;
 111                                 background-color: #DDDDDD;
 112                                 border: 1px black inset;
 113                                 background-image: none;
 114                                 margin: 0px;
 115                                 padding: 2px;
 116                         }
 117                         .attributeoptlong
 118                         {
 119                                 font-size: 85%;
 120                                 font-color: #000000;
 121                                 text-align: left;
 122                                 background-color: #BCBCEE;
 123                                 border: 1px black inset;
 124                                 background-image: none;
 125                                 margin: 0px;
 126                                 padding: 2px;
 127                         }
 128                         .demo
 129                         {
 130                                 background-color: #EEEEEE;
 131                                 padding: 3px;
 132                         }
 133                         .fixed
 134                         {
 135                                 font-family: monospace;
 136                                 font-size: 90%;
 137                                 font-color: #121212;
 138                         }
 139
 140                 </style></head><body link="red" vlink="red" alink="black" bgcolor="white">
 141                 InQueue Federation Policy and Configuration Guidelines<br>
 142                 Version 1.2<br />
 143                 May 17, 2004<br />
 144
 145                 <h3>InQueue Federation Policy and Configuration Guidelines</h3>
 146
 147                 <h4>1.  Introduction to InQueue</h4>
 148                 <blockquote><p>
 149                         The InQueue Federation, operated by Internet2, is designed for
 150                         organizations that are becoming familiar with the Shibboleth software
 151                         package and the federated trust model.  InQueue provides the basic
 152                         services needed for a federation using Shibboleth:</p>
 153
 154                         <ul>
 155                                 <li>maintenance and distribution of participating site description and
 156                                 security files;</li>
 157                                 <li>a central WAYF ("where are you from") web site;</li>
 158                                 <li>specification of operational procedures and policies, including
 159                                 user data (attribute) definitions; and</li>
 160                                 <li>example target and origin sites with which to test
 161                                 interoperability.</li>
 162                         </ul>
 163
 164                         <p>Participating in InQueue permits an organization to learn about the
 165                         Shibboleth software via the experience of multi-party federated access,
 166                         while integrating its services into the organization's procedures and
 167                         policies.</p>
 168
 169                         <p>The InQueue federation is specifically <b>not</b> intended to support
 170                         production-level end-user access to protected resources.  Organizations
 171                         operating target sites are strongly discouraged from making sensitive or
 172                         valuable resources available via the Federation.</p>
 173                 </blockquote>
 174
 175                 <h4>2.  InQueue Policies</h4>
 176
 177                 <h4>2.1  Participation</h4>
 178
 179                 <blockquote><p>An organization may join InQueue as an origin, as a
 180                         target, or both.
 181                         Participants are expected to be authorized representatives of
 182                         their organization.  Internet2 reserves the right to make final
 183                         decisions about participation in the Federation.</p>
 184
 185                         <p>InQueue is intended to serve as a primary federation
 186                         for an organization only during the period an
 187                         organization is learning about Shibboleth and federated
 188                         operations.  Upon completion of this period, the
 189                         organization is expected to join a Federation (or some
 190                         other management solution) that meets its long-term
 191                         operational needs. </p>
 192
 193                         <p>By joining InQueue, an organization agrees that the
 194                         Federation can list their name on the Federation web
 195                         site as a member of the Federation.</p>
 196
 197                         <p>In joining InQueue, an organization will make a good
 198                         faith effort to maintain a web page describing their use
 199                         of Shibboleth. This page will be linked from the
 200                         Federation member list.</p>
 201
 202                         </blockquote>
 203
 204                         <h4>2.2  Data management</h4>
 205
 206                         <blockquote><p>
 207                                 By participating, origins agree that all attributes sent
 208                                 to targets in the Federation to the best of their knowledge accurately
 209                                 represent information about the authenticated individual accessing the
 210                                 target resource.</p>
 211
 212                                 <p>Targets agree to dispose of all received
 213                                 attributes properly by not mis-using them, aggregating them, or
 214                                 sharing them with other organizations.</p></blockquote>
 215
 216                         <h4>2.3  Security management</h4>
 217
 218                         <blockquote><p>InQueue distributes a set of root certificates for
 219                                 issuers from which server certificates may be obtained to identify
 220                                 InQueue server components.
 221                                 Additionally, sites with certificates not rooted
 222                                 in one of these trusted roots may have these certificates added to the
 223                                 appropriate trust file.  Targets must have a certificate signed by an
 224                                 acceptible CA.  The list of certificate authorities used by
 225                                 InQueue is:</p>
 226                                 <ul type="circle">
 227                                         <li><a href="http://www.verisign.com/">Verisign/RSA Secure Server CA</a></li>
 228                                         <li><a href="http://bossie.doit.wisc.edu/cert/i2server">Internet2
 229                                                 HEPKI Test CA</a></li>
 230                                         <li><a href="http://www.cren.net/crenca/">CREN CA</a></li>
 231                                 </ul>
 232
 233                                 <p>For origins, OpenSSL must also be configured to use the
 234                                 appropriate set of trusted roots for the issuance of SSL
 235                                 certificates that Shibboleth trusts.  For InQueue, this list may
 236                                 be obtained from <span
 237                                 class="fixed">http://wayf.internet2.edu/InQueue/ca-bundle.
 238                                 crt</span>.  This list should then be copied for <span
 239                                 class="fixed">mod_ssl</span>, which will typically need to
 240                                 be to <span
 241                                 class="fixed">/conf/ssl.crt/ca-bundle.crt</span>.  This
 242                                 list of CA's is <b>not</b> rigorous nor secure and may contain
 243                                 CA's which have no level of assurance or are questionable.</p>
 244                         </blockquote>
 245
 246                         <h4>2.4  Attributes</h4>
 247                         <blockquote><p>The InQueue
 248                                 Federation specifies a set of attribute definitions to support basic
 249                                 attribute-based authorization.</p>
 250                                 <ol>
 251                                 <li>If a Federation member sends or receives an Attribute Assertion
 252                                 containing the InQueue policy uri and referencing one of the listed
 253                                 attributes,
 254                                 the syntax and semantics of the associated attribute value should
 255                                 conform
 256                                 to the definitions specified in the <a href="http://www.educause.edu/eduperson/">EduPerson specification 2002/10</a>
 257
 258                                 <ul type="circle">
 259                                         <li>eduPersonPrincipalName</li>
 260                                         <li>eduPersonEntitlement</li>
 261                                         <li>eduPersonAffiliation (expressed in a slightly different form via
 262                                         a new attribute called eduPersonScopedAffiliation)</li>
 263                                 </ul>
 264                                 <li>If a Federation member sends or receives an Attribute Assertion
 265                                 containing the InQueue policy uri and referencing one of the listed
 266                                 attributes,
 267                                 the syntax and semantics of the associated attribute value should
 268                                 conform
 269                                 to the definitions specified in the relevant <a href="http://www/ietf.org">IETF</a> RFCs.
 270
 271                                 <ul type="circle">
 272                                         <li>cn
 273                                         <li>sn
 274                                         <li>telephoneNumber
 275                                         <li>title
 276                                         <li>initials
 277                                         <li>description
 278                                         <li>carLicense
 279                                         <li>departmentNumber
 280                                         <li>displayName
 281                                         <li>employeeNumber
 282                                         <li>employeeType
 283                                         <li>preferredLanguage
 284                                         <li>manager
 285                                         <li>roomNumber
 286                                         <li>seeAlso
 287                                         <li>facsimileTelephoneNumber
 288                                         <li>street
 289                                         <li>postOfficeBox
 290                                         <li>postalCode
 291                                         <li>st
 292                                         <li>givenName
 293                                         <li>l
 294                                         <li>businessCategory
 295                                         <li>ou
 296                                         <li>physicalDeliveryOfficeName
 297                                 </ul>
 298                                 <li>If a Federation member sends or receives an eduPersonEntitlement Attribute Assertion
 299                                 containing the InQueue policy uri and containing one of the listed
 300                                 values,
 301                                 the syntax and semantics of the associated attribute value should
 302                                 conform
 303                                 to these definitions
 304
 305                                 <ul type="circle">
 306                                         <li>urn:mace:incommon:entitlement:common:1
 307                                         <p>The person possesses an eduPersonAffiliation value of faculty, staff,  or student, or qualifies as a "library walk-in".
 308
 309                                 </ul>
 310                                 </ol>
 311                         </blockquote>
 312
 313                         <h4>3.  Joining InQueue</h4>
 314
 315                         <blockquote><p>To join InQueue, origins <a href="mailto:inqueue-support@internet2.edu?subject=Shib%20Origin%20Site%%0D%20%2020Application"> submit a request to
 316                                         inqueue-support@internet2.edu</a> containing the following
 317                                 information:</p></blockquote>
 318
 319                         <blockquote>
 320                                 <ul type="circle">
 321                                         <li>Domain Name of the origin site (e.g., Ohio State's is
 322                                         "osu.edu").</li>
 323                                         <li>Complete URL to access the Shibboleth Handle Service at the site.</li>
 324                                         <li>The CN (usually the hostname) of the HS's certificate's subject.
 325                                         This should also be the value of the <span class="fixed">providerID</span> attribute in the main <a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> element or the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element in <span class="fixed">origin.xml</span>.</li>
 326                                         <li>Complete URL to access the Shibboleth Attribute Authority at the site.</li>
 327                                         <li>The CN (usually the hostname) of the AA's certificate's subject.
 328                                         This should also be the value of the <a href="http://SHIBBOLETHORIGINGUIDEURL#confFileResolver"><span class="fixed">FileResolver</span></a> element pointed to by <span class="fixed">AASigningCredential</span> attribute in the main <a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> element or the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element in <span class="fixed">origin.xml</span>.</li>
 329                                         <li>Any shorthand aliases the WAYF should support for the origin
 330                                         site (e.g., Ohio State, OSU, Buckeyes)</li>
 331                                         <li>Contact names and addresses for technical and administrative
 332                                         issues.</li>
 333                                         <li>The URL of an error page that users selecting this origin from
 334                                         the WAYF may be referred to by targets if Shibboleth
 335                                         malfunctions. (optional)</li>
 336                                         <li>If the HS's certificate is not issueed by one of the root CAs
 337                                         used
 338                                         by InQueue, then it must be submitted in Base64-encoded DER (aka
 339                                         "PEM") format.</li>
 340                                         <li>(optional) Briefly describe the organization's planned uses of Shibboleth.
 341                         </ul></blockquote>
 342
 343                         <blockquote><p>To join InQueue, targets must <a href="mailto:inqueue-support@internet2.edu?subject=Shib%20Target%20Site%%0D%20%2020Application"> submit a basic application to
 344                                         inqueue-support@internet2.edu</a> containing the following
 345                                 information:</p></blockquote>
 346
 347                         <blockquote>
 348                                 <ul type="circle">
 349                                         <li>The name of the organization</li>
 350                                         <li>Contact names and addresses for both administrative and
 351                                         technical purposes</li>
 352                                         <li>The URL of all SHIRE services (specified using a shireURL attribute in a <a href="http://SHIBBOLETHTARGETGUIDEURL#confSessions"><span class="fixed">Sessions</span></a> element) set up for this organization.</li>
 353                                 </ul>
 354                         </blockquote>
 355
 356                         <h4>4.  Configuration for Using InQueue</h4>
 357
 358                         <blockquote><p>Once your site is accepted into and added to InQueue,
 359                                 the following configuration parameters must be entered to ensure
 360                                 interoperability and compliance with federation guidelines.  Consult
 361                                 the Shibboleth Deploy Guides for further information on these fields
 362                                 and on <span class="fixed">origin.xml</span> and <span class="fixed">shibboleth.xml</span>.</p></blockquote>
 363
 364                         <blockquote><h5>4.a. Origins:</h5>
 365                                 <p>The following steps must be undertaken to configure a
 366                                 standard Shibboleth origin configuration to use InQueue.  Some
 367                                 steps may vary or may be completed already depending on how
 368                                 <span class="fixed">origin.xml</span> has already been
 369                                 modified.</p>
 370                                 <ol>
 371                                         <li><a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> must be modified as follows:
 372                                         <ul>
 373                                                 <li><span class="fixed">providerId</span> must be populated with a URI that will be assigned by InQueue when you are accepted into the federation.</li>
 374                                                 <li><span class="fixed">defaultRelyingParty</span> should be changed to <span class="fixed">urn:mace:inqueue</span>.</li>
 375                                         </ul></li>
 376                                         <li>Uncomment the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element, and within it, modify the <span class="fixed">providerId</span> to match the value assigned by InQueue to this origin.</li>
 377                                         <li>A new <a href="http://SHIBBOLETHORIGINGUIDEURL#confKeyStoreResolver"><span class="fixed">KeyStoreResolver</span></a> element must be added pointing to the private key and certificate for use by this origin.  See <a href="http://SHIBBOLETHORIGINGUIDEURL#4.b.">section 4.b</a> of the origin deploy guide for further information.</li>
 378                                         <li>Add a <a href="http://SHIBBOLETHORIGINGUIDEURL#confFederationProvider"><span class="fixed">FederationProvider</span></a> element for InQueue as follows:
 379                                         <blockquote><span class="fixed">
 380                                                 &lt;FederationProvider type=&quot;edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadataLoadWrapper&quot; uri=&quot;/conf/inqueue_sites.xml&quot;/&gt;
 381                                         </span></blockquote></li>
 382                                 </ol>
 383                                 </blockquote>
 384
 385                                 <blockquote><h5>4.b. Targets:</h5>
 386
 387                                 <p>The following steps must be undertaken to configure a
 388                                 standard Shibboleth origin configuration to use InQueue.  Some
 389                                 steps may vary or may be completed already depending on how
 390                                 <span class="fixed">shibboleth.xml</span> has already been
 391                                 modified.  This guide covers modification of the default <a
 392                                 href="http://SHIBBOLETHTARGETGUIDEURL#confApplications"><span
 393                                 class="fixed">Applications</span></a> element from localhost
 394                                 operation to InQueue operation for simplicity's sake.</p>
 395                                 <ol>
 396                                         <li>The <span class="fixed">providerId</span> attribute of the <a href="http://SHIBBOLETHTARGETGUIDEURL#confApplications"><span class="fixed">Applications</span></a> element should be changed to the InQueue-assigned value.</li>
 397                                         <li>Ensure that the <a href="http://SHIBBOLETHTARGETGUIDEURL#confSessions"><span class="fixed">Sessions</span></a> element's <span class="fixed">wayfURL</span> is <span class="fixed">https://wayf.internet2.edu/InQueue/WAYF</span>.</li>
 398                                         <li>Uncomment the InQueue <a href="http://SHIBBOLETHTARGETGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element within the <a href="http://SHIBBOLETHTARGETGUIDEURL#confCredentialsUse"><span class="fixed">CredentialsUse</span></a> element.</li>
 399                                         <li>Uncomment the <a href="http://SHIBBOLETHTARGETGUIDEURL#confFileResolver"><span class="fixed">FileResolver</span></a> element with a <span class="fixed">Id</span> of <span class="fixed">inqueuecreds</span>.  The key path, key password, and certificate path should be modified to match new credentials generated according to <a href="http://SHIBBOLETHTARGETGUIDEURL#4.c.">section 4.c</a> of the target deploy guide.</li>
 400                                 </ol>
 401                                 </blockquote>
 402
 403                                 <blockquote><h5>4.c. Refreshing Federation Metadata:</h5>
 404                                         <p>Shibboleth 1.2 includes metadata both for origin sites
 405                                         and for target sites.  The origin has the <a
 406                                         href="http://SHIBBOLETHORIGINGUIDEURL#4.e."><span
 407                                         class="fixed">metadatatool</span></a> and the target uses
 408                                         the <a href="http://SHIBBOLETHTARGETGUIDEURL#4.g."><span
 409                                         class="fixed">siterefresh</span></a> tool to maintain
 410                                         locally cached versions of various files.   Once your site
 411                                         is accepted into the InQueue federation, it is necessary
 412                                         that you periodically update the federation's metadata.
 413                                         This metadata includes information used to identify and
 414                                         authenticate InQueue sites.  This should be frequently run
 415                                         by adding it to a <span class="fixed">crontab</span> to
 416                                         ensure that the data is fresh.</p>
 417
 418                                         <p>InQueue's metadata is digitally signed, so the first step is to obtain the InQueue signing certificate.
 419                                         It can be downloaded from <span class="fixed">http://wayf.internet2.edu/InQueue/internet2.pem
 420                                         </span> and has a fingerprint of:</p>
 421                                         <p><span class="fixed">b4 42 6c 1e 8b 7d 8e b3 68 03 00 e4 c4 57 dd 74 89 f8 9a 80</span>.</p>
 422
 423                                         <p>The following commands can be used to obtain the federation's metadata for a Shibboleth <b>target</b>:</p>
 424                                         <blockquote><span class="fixed">
 425                                         $ cd /opt/shibboleth/etc/shibboleth<br>
 426                     $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/sites.xml --out sites.xml --cert internet2.pem<br>
 427                                         $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/trust.xml --out trust.xml --cert internet2.pem</span>
 428                                         </blockquote>
 429
 430                                         <p>The following commands can be used to obtain the federation's metadata for a Shibboleth <b>origin</b>:</p>
 431                                         <blockquote><span class="fixed">bin/metadatatool -i https://wayf.internet2.edu/InQueue/sites.xml -k conf/internet2.jks -p shib123 -a sitesigner -o /conf/sites.xml
 432                                         </span></blockquote>
 433                                 </blockquote>
 434
 435                                 <h4>5.  Testing</h4>
 436                                 <blockquote><p>A <a href="https://wayf.internet2.edu/InQueue/sample.jsp">sample shibboleth target</a>
 437                                         is available for testing newly installed origin sites.  New targets can make use of a sample origin,
 438                                         which is listed as "Example State University" on the InQueue WAYF ( Username: demo / Password: demo ).</p></blockquote>
 439
 440                 </body></html>
 441