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