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                         .fixed
  27                         {
  28                                 font-family: monospace;
  29                                 font-size: 90%;
  30                                 font-color: #121212;
  31                         }
  32
  33                 </style></head><body link="red" vlink="red" alink="black" bgcolor="white">
  34                 InQueue Federation Policy and Configuration Guidelines<br>
  35                 Version 1.2<br />
  36                 May 19, 2004<br />
  37
  38                 <h3>InQueue Federation Policy and Configuration Guidelines</h3>
  39
  40                 <h4>1.  Introduction to InQueue</h4>
  41                 <blockquote><p>
  42                         The InQueue Federation, operated by Internet2, is designed for
  43                         organizations that are becoming familiar with the Shibboleth
  44                         software package and the federated trust model.  It is also
  45                         available as a temporary alternative to sites for which no suitable
  46                         production-level federation exists.  InQueue provides the basic
  47                         services needed for a federation using Shibboleth:</p>
  48
  49                         <ul>
  50                                 <li>maintenance and distribution of participating site description and
  51                                 security files;</li>
  52                                 <li>a central WAYF ("where are you from") web site;</li>
  53                                 <li>specification of operational procedures and policies, including
  54                                 user data (attribute) definitions; and</li>
  55                                 <li>example target and origin sites with which to test
  56                                 interoperability.</li>
  57                         </ul>
  58
  59                         <p>Participating in InQueue permits an organization to learn about the
  60                         Shibboleth software via the experience of multi-party federated access,
  61                         while integrating its services into the organization's procedures and
  62                         policies.</p>
  63
  64                         <p>The InQueue federation is specifically <b>not</b> intended to support
  65                         production-level end-user access to protected resources.  Organizations
  66                         operating target sites are strongly discouraged from making sensitive or
  67                         valuable resources available via the Federation.</p>
  68                 </blockquote>
  69
  70                 <h4>2.  InQueue Policies</h4>
  71
  72                 <h4>2.1  Participation</h4>
  73
  74                 <blockquote><p>An organization may join InQueue as an origin, as a
  75                         target, or both.
  76                         Participants are expected to be authorized representatives of
  77                         their organization.  Internet2 reserves the right to make final
  78                         decisions about participation in the Federation.</p>
  79
  80                         <p>InQueue is intended to serve as a primary federation
  81                         for an organization only during the period an
  82                         organization is learning about Shibboleth and federated
  83                         operations.  Upon completion of this period, the
  84                         organization is expected to join a Federation (or some
  85                         other management solution) that meets its long-term
  86                         operational needs. </p>
  87
  88                         <p>By joining InQueue, an organization agrees that the
  89                         Federation can list their name on the Federation web
  90                         site as a member of the Federation.</p>
  91
  92                         <p>In joining InQueue, an organization will make a good
  93                         faith effort to maintain a web page describing their use
  94                         of Shibboleth. This page will be linked from the
  95                         Federation member list.</p>
  96
  97                         </blockquote>
  98
  99                         <h4>2.2  Data management</h4>
 100
 101                         <blockquote><p>
 102                                 By participating, origins agree that all attributes sent
 103                                 to targets in the Federation to the best of their knowledge accurately
 104                                 represent information about the authenticated individual accessing the
 105                                 target resource.</p>
 106
 107                                 <p>Targets agree to dispose of all received
 108                                 attributes properly by not mis-using them, aggregating them, or
 109                                 sharing them with other organizations.</p></blockquote>
 110
 111                         <h4>2.3  Security management</h4>
 112
 113                         <blockquote><p>InQueue distributes a set of root certificates for
 114                         issuers from which server certificates may be obtained to identify
 115                         InQueue server components.  Both targets and origins should have a
 116                         certificate obtained from one of the authorities below.  Additional
 117                         certificate authorities may be recognized as necessary to support
 118                         use of both free and common commercial certificates for testing.
 119                         The list of certificate authorities used by InQueue is:</p>
 120                                 <ul type="circle">
 121                                         <li><a href="http://www.verisign.com/">Verisign/RSA Secure Server CA</a></li>
 122                                         <li><a href="http://bossie.doit.wisc.edu/cert/i2server">Internet2
 123                                                 HEPKI Test CA</a></li>
 124                                         <li><a href="http://www.cren.net/crenca/">CREN CA</a></li>
 125                                         <li><a href="http://www.thawte.com/ssl/index.html">Thawte Server & Premium Server CA's</a></li>
 126                                         <li><a href="http://www.incommonfederation.org/">InCommon CA</a></li>
 127                                 </ul>
 128
 129                         </blockquote>
 130
 131                         <h4>2.4  Attributes</h4>
 132                         <blockquote><p>The InQueue
 133                                 Federation specifies a set of attribute definitions to support basic
 134                                 attribute-based authorization.</p>
 135                                 <ol>
 136                                 <li>Attribute assertions issued or received by InQueue members including eduPerson attributes should conform to the syntax and semantics defined by the <a href="http://www.educause.edu/eduperson/">eduPerson 2003/12</a> specification.
 137
 138                                 <ul type="circle">
 139                                         <li>urn:mace:dir:attribute-def:eduPersonEntitlement</li>
 140                                         <li>urn:mace:dir:attribute-def:eduPersonPrincipalName</li>
 141                                         <li>urn:mace:dir:attribute-def:eduPersonScopedAffiliation</li>
 142                                 </ul></li>
 143                                 <li>If a Federation member sends or receives an Attribute Assertion
 144                                 containing the InQueue policy uri and referencing one of the listed
 145                                 attributes,
 146                                 the syntax and semantics of the associated attribute value should
 147                                 conform
 148                                 to the definitions specified in the relevant <a href="http://www/ietf.org">IETF</a> RFCs.
 149
 150                                 <ul type="circle">
 151                                         <li>cn
 152                                         <li>sn
 153                                         <li>telephoneNumber
 154                                         <li>title
 155                                         <li>initials
 156                                         <li>description
 157                                         <li>carLicense
 158                                         <li>departmentNumber
 159                                         <li>displayName
 160                                         <li>employeeNumber
 161                                         <li>employeeType
 162                                         <li>preferredLanguage
 163                                         <li>manager
 164                                         <li>roomNumber
 165                                         <li>seeAlso
 166                                         <li>facsimileTelephoneNumber
 167                                         <li>street
 168                                         <li>postOfficeBox
 169                                         <li>postalCode
 170                                         <li>st
 171                                         <li>givenName
 172                                         <li>l
 173                                         <li>businessCategory
 174                                         <li>ou
 175                                         <li>physicalDeliveryOfficeName
 176                                 </ul>
 177                                 <li>If a Federation member sends or receives an eduPersonEntitlement Attribute Assertion
 178                                 containing the InQueue policy uri and containing one of the listed
 179                                 values,
 180                                 the syntax and semantics of the associated attribute value should
 181                                 conform
 182                                 to these definitions
 183
 184                                 <ul type="circle">
 185                                         <li>urn:mace:incommon:entitlement:common:1
 186                                         <p>The person possesses an eduPersonAffiliation value of faculty, staff,  or student, or qualifies as a "library walk-in".
 187
 188                                 </ul>
 189                                 </ol>
 190                         </blockquote>
 191
 192                         <h4>3.  Joining InQueue</h4>
 193
 194                         <blockquote><p>To join InQueue, origins <a href="mailto:inqueue-support@internet2.edu?subject=Shib%20Origin%20Site%%0D%20%2020Application"> submit a request to
 195                                         inqueue-support@internet2.edu</a> containing the following
 196                                 information:</p></blockquote>
 197
 198                         <blockquote>
 199                                 <ul type="circle">
 200                                         <li>Domain Name of the origin site (e.g., Ohio State's is
 201                                         "osu.edu").</li>
 202                                         <li>Complete URL to access the Shibboleth Handle Service at
 203                                         the site.</li>
 204                                         <li>The CN (usually the hostname) or the full subject of the
 205                                         HS's certificate's subject.  If the certificate is readable
 206                                         by OpenSSL (not keytool), this value can be obtained using
 207                                         the following command:
 208                                         <blockquote><span class="fixed">
 209                                                 $ openssl x509  -in &lt;file&gt; -subject -nameopt rfc2253
 210                                         </span></blockquote></li>
 211                                         <li>Complete URL to access the Shibboleth Attribute Authority at the site.</li>
 212                                         <li>Any shorthand aliases the WAYF should support for the origin
 213                                         site (e.g., Ohio State, OSU, Buckeyes)</li>
 214                                         <li>Contact names and e-mail addresses for technical and
 215                                         administrative issues.</li>
 216                                         <li>The URL of an error page that users selecting this
 217                                         origin from the WAYF may be referred to by targets if there
 218                                         is a problem encountered by the target, such as incorrect
 219                                         attributes leading to an access failure. (optional)</li>
 220                                         <li>(optional) Briefly describe the organization's planned
 221                                         uses of Shibboleth.
 222                         </ul></blockquote>
 223
 224                         <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
 225                                         inqueue-support@internet2.edu</a> containing the following
 226                                 information:</p></blockquote>
 227
 228                         <blockquote>
 229                                 <ul type="circle">
 230                                         <li>The name of the organization</li>
 231                                         <li>Contact names and e-mail addresses for techincal and
 232                                         administrative issues.</li>
 233                                         <li>The CN (usually the hostname) or the full subject of the
 234                                         SHAR's certificate's subject.  If the certificate is readable
 235                                         by OpenSSL (not keytool), this value can be obtained using
 236                                         the following command:
 237                                         <blockquote><span class="fixed">
 238                                                 $ openssl x509  -in &lt;file&gt; -subject -nameopt rfc2253
 239                                         </span></blockquote></li>
 240                                         <li>The URL of all SHIRE locations (specified using a
 241                                         <span class="fixed">shireURL</span> attribute in a <a
 242                                         href="http://SHIBBOLETHTARGETGUIDEURL#confSessions"><span
 243                                         class="fixed">Sessions</span></a> element) set up for this
 244                                         organization, e.g. <span
 245                                         class="fixed">https://example.org/Shibboleth.shire</span>.
 246                                         Note that the assumption is that access will only occur over
 247                                         the protocol specified by the SHIRE URL submitted (<span
 248                                         class="fixed">https</span> or <span
 249                                         class="fixed">http</span>); if there is a desire to listen
 250                                         on both ports, this should be noted in the application.</li>
 251                                 </ul>
 252                         </blockquote>
 253
 254                         <h4>4.  Configuration for Using InQueue</h4>
 255
 256                         <blockquote><p>Once your site is accepted into and added to InQueue,
 257                                 the following configuration parameters must be entered to ensure
 258                                 interoperability and compliance with federation guidelines.  Consult
 259                                 the Shibboleth Deploy Guides for further information on these fields
 260                                 and on <span class="fixed">origin.xml</span> and <span class="fixed">shibboleth.xml</span>.</p></blockquote>
 261
 262                         <blockquote><h5>4.a. Origins:</h5>
 263                                 <p>The following steps must be undertaken to configure a
 264                                 standard Shibboleth origin configuration to use InQueue.  Some
 265                                 steps may vary or may be completed already depending on how
 266                                 <span class="fixed">origin.xml</span> has already been
 267                                 modified.</p>
 268                                 <ol>
 269                                         <li><a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> must be modified as follows:
 270                                         <ul>
 271                                                 <li><span class="fixed">providerId</span> must be
 272                                                 populated with a URI that will be assigned by InQueue
 273                                                 when you are accepted into the federation.</li>
 274                                                 <li><span class="fixed">defaultRelyingParty</span>
 275                                                 should be changed to <span
 276                                                 class="fixed">urn:mace:inqueue</span>.</li>
 277                                                 <li>Ensure that <span class="fixed">AAUrl</span> has
 278                                                 been changed to reflect the value sent in with the
 279                                                 application.</li>
 280                                         </ul></li>
 281                                         <li>Uncomment the InQueue <a href="http://SHIBBOLETHORIGINGUIDEURL#confRelyingParty"><span class="fixed">RelyingParty</span></a> element.  If the default <span class="fixed">providerId</span> as specified in <a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> is not the one supplied by InQueue, modify the <span class="fixed">providerId</span> to match the value assigned by InQueue to this origin.</li>
 282                                         <li>A new <a href="http://SHIBBOLETHORIGINGUIDEURL#confKeyStoreResolver"><span class="fixed">KeyStoreResolver</span></a> or <a href="http://SHIBBOLETHORIGINGUIDEURL#confFileResolver"><span class="fixed">FileResolver</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>
 283                                         <li>Uncomment the <a href="http://SHIBBOLETHORIGINGUIDEURL#confFederationProvider"><span class="fixed">FederationProvider</span></a> element for InQueue.</li>
 284                                         <li>OpenSSL must also be configured to use the
 285                                 appropriate set of trusted roots for the issuance of SSL
 286                                 certificates that Shibboleth trusts.  For InQueue, this list may
 287                                 be obtained from <span
 288                                 class="fixed">http://wayf.internet2.edu/InQueue/ca-bundle.
 289                                 crt</span>.  This list should then be copied for <span
 290                                 class="fixed">mod_ssl</span>, which will typically need to
 291                                 be to <span
 292                                 class="fixed">/conf/ssl.crt/ca-bundle.crt</span>.  This
 293                                 list of CA's is <b>not</b> rigorous nor secure and may contain
 294                                 CA's which have no level of assurance or are questionable.</li>
 295                                 </ol>
 296                                 </blockquote>
 297
 298                                 <blockquote><h5>4.b. Targets:</h5>
 299
 300                                 <p>The following steps must be undertaken to configure a
 301                                 standard Shibboleth target configuration to use InQueue.  Some
 302                                 steps may vary or may be completed already depending on how
 303                                 <span class="fixed">shibboleth.xml</span> has already been
 304                                 modified.  This guide covers modification of the default <a
 305                                 href="http://SHIBBOLETHTARGETGUIDEURL#confApplications"><span
 306                                 class="fixed">Applications</span></a> element from localhost
 307                                 operation to InQueue operation for simplicity's sake.</p>
 308                                 <ol>
 309                                         <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>
 310                                         <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>
 311                                         <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>
 312                                         <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>
 313                                 </ol>
 314                                 </blockquote>
 315
 316                                 <blockquote><h5>4.c. Refreshing Federation Metadata:</h5>
 317                                         <p>Shibboleth 1.2 includes metadata both for origin sites
 318                                         and for target sites.  The origin has the <a
 319                                         href="http://SHIBBOLETHORIGINGUIDEURL#4.e."><span
 320                                         class="fixed">metadatatool</span></a> and the target uses
 321                                         the <a href="http://SHIBBOLETHTARGETGUIDEURL#4.g."><span
 322                                         class="fixed">siterefresh</span></a> tool to maintain
 323                                         locally cached versions of various files.   Once your site
 324                                         is accepted into the InQueue federation, it is necessary
 325                                         that you periodically update the federation's metadata.
 326                                         This metadata includes information used to identify and
 327                                         authenticate InQueue sites.  This should be frequently run
 328                                         by adding it to a <span class="fixed">crontab</span> to
 329                                         ensure that the data is fresh.</p>
 330
 331                                         <p>InQueue's metadata is digitally signed, so the first step is to obtain the InQueue signing certificate.
 332                                         It can be downloaded from <span class="fixed">http://wayf.internet2.edu/InQueue/inqueue.pem
 333                                         </span> and has a fingerprint of:</p>
 334                                         <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>
 335
 336                                         <p>The following commands can be used to obtain the federation's metadata for a Shibboleth <b>target</b>:</p>
 337                                         <blockquote><span class="fixed">
 338                                         $ cd /opt/shibboleth/etc/shibboleth<br>
 339                     $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/sites-1.2.xml --out sites.xml --cert inqueue.pem<br>
 340                                         $ ../../bin/siterefresh --url http://wayf.internet2.edu/InQueue/trust-1.2.xml --out trust.xml --cert inqueue.pem</span>
 341                                         </blockquote>
 342
 343                                         <p>The origin metadatatool's operation is greatly simplified
 344                                         if a keystore file is downloaded from <span
 345                                         class="fixed">https://wayf.internet2.edu/InQueue/inqueue.jks</span>
 346                                         and placed in the same directory as <span
 347                                         class="fixed">metadatatool</span>.  After this has been
 348                                         done, the following commands can be used to obtain the
 349                                         federation's metadata for a Shibboleth <b>origin</b>:</p>
 350                                         <blockquote><span class="fixed">metadatatool -i http://wayf.internet2.edu/InQueue/sites-1.2.xml \ -k inqueue.jks -a inqueue<br>
 351                                         metadatatool -i http://wayf.internet2.edu/InQueue/trust-1.2.xml \
 352         -k inqueue.jks -a inqueue
 353                                         </span></blockquote>
 354                                 </blockquote>
 355
 356                                 <h4>5.  Testing</h4>
 357                                 <blockquote><p>A <a href="https://wayf.internet2.edu/InQueue/sample.jsp">sample shibboleth target</a>
 358                                         is available for testing newly installed origin sites.  New targets can make use of a sample origin,
 359                                         which is listed as "Example State University" on the InQueue WAYF ( Username: demo / Password: demo ).</p></blockquote>
 360         </body>
 361 </html>