</center>
<p>Shibboleth Target Deployment Guide<br>
Shibboleth Version 1.0.1<br />
-July 15, 2003<br />
+July 25, 2003<br />
</p>
<h3>This version of the deploy guide is for Shibboleth v1.0.1. For documentation
related to prior versions of Shibboleth, please consult the appropriate branch
<li>Support for a runtime-derived per-requester persistent identifier
attribute to support anonymous personalization by targets has been added via
an attribute plugin. <span class="feature">[1.0.1]</span></li>
- <li>Specialized sites without privacy needs can configure identity-based
+ <li>Specialized deployments without privacy needs can configure identity-based
handles interoperable with other SAML deployments. <span class="feature">
[1.0.1]</span></li>
</ol>
This would allow a site to run an apache server farm, with multiple SHARs,
supporting the same set of sessions.</li>
<li>Federation supplied files (sites.xml and trust.xml) are now refreshed in
- a much more robust manner. </li>
- </li>
+ a much more robust manner.</li>
<li>The SHAR can be configured to request specific attributes from the
- Origin. </li>
+ Origin.</li>
<li>The SHAR can use TCP sockets when responding to the Apache module, for
specialized deployment behind firewalls. <span class="feature">[1.0.1]</span>
</li>
<li>Attribute acceptance policies have been greatly enhanced, and are now
used to configure all aspects of attribute handling by the target, except
for requesting specific attributes by sitename. Adding attributes now takes
- place in one configuration step. <span class="feature">[1.0.1]</span> </li>
+ place in one configuration step. <span class="feature">[1.0.1]</span></li>
<li>Support for Apache 1.3 on Windows NT/2000/XP/2003 has been added.
- <span class="feature">[1.0.1]</span> </li>
+ <span class="feature">[1.0.1]</span></li>
<li>Microsoft IIS web server support has been added via an ISAPI filter and
- extension. <span class="feature">[1.0.1]</span> </li>
+ extension. <span class="feature">[1.0.1]</span></li>
</ol>
<h5>Miscellaneous</h5>
<ol>
<li>Origin sites can configure a value to describe the type of
authentication mechanism used at the origin site(e.g. password, Kerberos,
- PKI, etc.). This value is made available on the target side as Shib-Authentication-Method.
- <br>
- </li>
+ PKI, etc.). This value is made available on the target side as Shib-Authentication-Method.</li>
<li>Various improvements to error handling. Origin sites are now able to
- supply an "error URL" and contact information to a federation. When a target
- encounters an error, it can include this information in the error page. <br>
- </li>
- <li>Local time string values are now used in log files. <br>
- </li>
+ supply an error URL and contact information to a federation. When a target
+ encounters an error, it can include this information in the error page.</li>
+ <li>Local time string values are now used in log files.</li>
<li>Internationalization support has been extended.</li>
</ol>
<p>Before starting, please sign up for all applicable
Acceptance Policies</font></a></li>
<li><a href="#4.f."><font color="black">Using Attributes in Applications</font></a></li>
<li><a href="#4.g."><font color="black"><span class="fixed">siterefresh</span></font></a></li>
+ <li><a href="#4.h."><font color="black">MySQL Session Cache</font></a></li>
</ol>
</li>
<li>
</blockquote>
<h4><a name="1.d."></a>1.d. Federations</h4>
<blockquote>
- <p>A federation provides part of the underlying trust required for function
- of the Shibboleth architecture. A federation in the context of Shibboleth is
- a group of organizations(universities, corporations, content providers,
- etc.) who agree to exchange attributes using the SAML/Shibboleth protocols
- and abide by a common set of policies and practices. In so doing, they must
- implicitly or explicitly agree to a common set of guidelines. Joining a
- federation is not explicitly necessary for operation of Shibboleth, but it
- dramatically expands the number of targets and origins that can interact
- without defining bilateral agreements between all these parties.</p>
+ <p>A federation is one way to provide part of the underlying trust required
+ for function of the Shibboleth architecture. A federation in the context of
+ Shibboleth is a group of organizations(universities, corporations, content
+ providers, etc.) who agree to exchange attributes using the SAML/Shibboleth
+ protocols and abide by a common set of policies and practices. In so doing,
+ they must implicitly or explicitly agree to a common set of guidelines.
+ Joining a federation is not explicitly necessary for operation of
+ Shibboleth, but it dramatically expands the number of targets and origins
+ that can interact without defining bilateral agreements between all these
+ parties.</p>
<p>A federation can be created in a variety of formats and trust models, but
to support Shibboleth, it must provide a certain set of services to
federation members. It needs to supply a registry to process applications to
that must elapse between user accesses before that user's session is
destroyed, including the associated handle and all cached attributes.
Defaults to <span class="fixed">28800</span> seconds, or 8 hours. This
- should be longer than the associated server's settings for session
- lifetime and timeout.</dd>
+ should generally be longer than the associated server's settings for
+ session lifetime and timeout.</dd>
<dd class="attributeopt"><span class="fixed">logger = <pathname></span></dd>
<dd class="valueopt">Specifies the location of the <span class="fixed">
log4cpp</span> configuration file for Shibboleth events produced by the
settings, as well as the Apache <span class="fixed">ShibMapAttribute</span>
command.</b></dd>
</dl>
+ <p>The <span class="fixed">[extensions:saml]</span> section specifies a set
+ of extension libraries to load that add additional functionality to the
+ system. Examples include session cache implementations, such as the MySQL
+ cache, or advanced metadata providers.</p>
+ <p><span class="fixed">[extensions:saml]</span>:</p>
+ <dl>
+ <dd class="attribute"><span class="fixed"><name> = <library pathname></span>
+ </dd>
+ <dd class="value">The name of the extension is simply a unique key and
+ is not important. The path to the library to load must be absolute and
+ complete.</dd>
+ </dl>
<p>The <span class="fixed">[policies]</span> section contains the policy URI
values that control acceptance of assertions from origin sites. This may
eventually have multiple elements associated it for targets that are members
command could be run very often without impacting target operations,
providing a high degree of currency in case sites become compromised.</p>
</blockquote>
+<h4><a name="4.h."></a>4.h. MySQL Session Cache</h4>
+<blockquote>
+ <p>Shibboleth includes a useful plugin that extends the default memory cache
+ for storing session data in the SHAR with a backing cache using an embedded
+ MySQL database. In most distributions, it is enabled by default. The plugin
+ can be found in the <span class="fixed">/opt/shibboleth/libexec</span>
+ folder, and is loaded as an extension library using the <span class="fixed">
+ [extensions:saml]</span> section of <span class="fixed">shibboleth.ini</span>.
+ The following configuration options are available:</p>
+ <dl>
+ <dd class="attributeopt"><span class="fixed">mysql-cache-timeout =
+ <seconds> (in [shar] section)</span></dd>
+ <dd class="valueopt">Specifies the duration in <span class="fixed">
+ seconds</span> that must elapse between user accesses before that user's
+ session is purged from the persistent cache. Defaults to
+ <span class="fixed">28800</span> seconds, or 8 hours. This should
+ generally be longer than the associated server's settings for session
+ lifetime and timeout, and the memory cache's timeout.</dd>
+ <dd class="attributeopt"><span class="fixed"><MySQL Arguments>
+ (one per line in [mysql] section)</span></dd>
+ <dd class="valueopt">To pass arguments to the MySQL engine, create
+ argument lines in the <span class="fixed">[mysql]</span> section in the
+ form:
+ <blockquote class="fixed">
+ <p>arg1=<argument><br>
+ arg2=<argument><br>
+ etc... </p>
+ </blockquote>
+ <p>Important arguments you'll find by default include: </p>
+ <blockquote class="fixed">
+ <p>arg1 = --language=/opt/shibboleth/share/english<br>
+ arg2 = --datadir=/opt/shibboleth/data</p>
+ </blockquote>
+ <p>which set the message file path and the location of the cache's
+ database files respectively. Make sure the data directory exists before
+ starting the SHAR if you change this path.</dd>
+ </dl>
+</blockquote>
<p><br>
</p>
<hr>
<h4><a name="5.b."></a>5.b. Common Problems</h4>
<blockquote>
<p>A knowledge base is being developed in the
- <a href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.%20%20%20%20%20%20html">
+ <a href="http://www.columbia.edu/~wassa/shib.faq/shibboleth-faq.html">
Shibboleth Deployer's FAQ</a>. Please mail
- <a href="mailto:mace-shib-users@internet2.edu">mace-shib-users@
- internet2.edu</a> with any additional questions or problems encountered that
+ <a href="mailto:mace-shib-users@internet2.edu">mace-shib-users@internet2.edu</a>
+ with any additional questions or problems encountered that
are not answered by this basic guide.</p>
</blockquote>
projects / shibboleth / sp.git / blobdiff