1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
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">
10 background-color: #FFFFFF;
28 font-family: monospace;
33 </style></head><body link="red" vlink="red" alink="black" bgcolor="white">
34 InQueue Federation Policy and Configuration Guidelines<br>
38 <h3>InQueue Federation Policy and Configuration Guidelines</h3>
40 <h4>1. Introduction to InQueue</h4>
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>
50 <li>maintenance and distribution of participating site description and
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>
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
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
73 <h4>2. InQueue Policies</h4>
75 <h4>2.1 Participation</h4>
77 <blockquote><p>An organization may join InQueue as an origin, as a
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>
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>
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>
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>
102 <h4>2.2 Data management</h4>
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
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>
114 <h4>2.3 Security management</h4>
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>
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>
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>
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.
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>
146 <li>If a Federation member sends or receives an Attribute Assertion
147 containing the InQueue policy uri and referencing one of the listed
149 the syntax and semantics of the associated attribute value should
151 to the definitions specified in the relevant <a href="http://www/ietf.org">IETF</a> RFCs.
165 <li>preferredLanguage
169 <li>facsimileTelephoneNumber
178 <li>physicalDeliveryOfficeName
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
183 the syntax and semantics of the associated attribute value should
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".
195 <h4>3. Joining InQueue</h4>
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>
203 <li>Domain Name of the origin site (e.g., Ohio State's is
205 <li>Complete URL to access the Shibboleth Handle Service at
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 <file> -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
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>
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 <file> -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>
257 <h4>4. Configuration for Using InQueue</h4>
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>
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
272 <li><a href="http://SHIBBOLETHORIGINGUIDEURL#confShibbolethOriginConfig"><span class="fixed">ShibbolethOriginConfig</span></a> must be modified as follows:
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
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
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>
301 <blockquote><h5>4.b. Targets:</h5>
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>
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>
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>
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>
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>
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
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>