<h2>Shibboleth Target Deployment Guide</h2>
</center>
<p>Shibboleth Target Deployment Guide<br>
-Shibboleth Version 1.2<br />
-April 30, 2004<br />
-<h3>This version of the deploy guide is for Shibboleth v1.2. For documentation
+Shibboleth Version 1.2.1<br />
+November 15, 2004<br />
+<h3>This version of the deploy guide is for Shibboleth v1.2.1. For documentation
related to prior versions of Shibboleth, please consult the appropriate branch
in the Shibboleth CVS.</h3>
<h3>The default configuration of Shibboleth is <b>not</b> secure and should not be
Shibboleth should only be used to protect sensitive content when deployed carefully
in conjunction with proper trust settings and policies.</h3>
-<p>The Shibboleth target implementation has been substantially redesigned for this release. Most of the
-configuration process has changed to accomodate more complex deployments but many of the defaults work
-fine for testing and simpler applications. For a list of new features, please refer to the NEWS.txt
-file in the doc/ folder of the distribution.</p>
+<p>The Shibboleth target implementation was substantially redesigned in version 1.2.
+1.2.1 is a bug-fix release intended to address stability, major bugs, and small issues
+that have arisen in the last 6 months. For a list of new features and fixes, please
+refer to the NEWS.txt file in the doc/ folder of the distribution.</p>
<p>Before starting, please sign up for all applicable
<a href="http://shibboleth.internet2.edu/shib-misc.html#mailinglist">mailing
<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>
+ <li><a href="#4.i."><font color="black">Using Lazy Sessions</font></a></li>
</ol>
</li>
<li>
and requirements for a successful implementation of a Shibboleth target.</p>
<h4><a name="2.a."></a>2.a. Requirements</h4>
<blockquote>
- <p>Shibboleth currently supports Windows NT/2000/XP/2003, Linux, and
- Solaris. At present, Shibboleth consists of Apache (or IIS) plugins and a
- separate SHAR process. The plugins use the Sun/ONC RPC mechanism to communicate
+ <p>Shibboleth currently supports Windows NT/2000/XP/2003, Linux, Solaris,
+ and Mac OS X. At present, Shibboleth consists of Apache/IIS plugins and a
+ separate SHAR process. The plugins use the Sun-RPC mechanism to communicate
with the SHAR over Unix domain or TCP sockets. The target's web servers must
be running <a href="http://http://www.apache.org/dist/httpd/">Apache</a>
1.3+, 2.0+, or Microsoft IIS 4.0+ More precise technical
<h4><a name="2.b."></a>2.b. Join a Federation</h4>
<blockquote>
<p>While it is not necessary for a target or origin to join a federation,
- doing so greatly facilitates the implementation of multilateral trust
- relationships. Each federation will have a different application process.</p>
- <p>For more information on federations, refer to <a href="#1.d.">1.d</a> or
- the Shibboleth v1.0 architectural document.</p>
+ doing so can facilitate the implementation of multilateral trust
+ relationships. Each federation will have a different application process.
+ For more information on federations, refer to <a href="#1.d.">1.d</a>.</p>
<p>For testing in a private environment, Shibboleth comes with a default
configuration that demonstrates how to implement a local peered agreement
and supports testing both origin and target on the same box using localhost
Shibboleth is as secure as possible, there are several recommended security
precautions which should be in place at local sites.</p>
<ol type="i">
- <li>SSL use is optional for target sites, but should be used if at all
+ <li>While SSL use is optional for target sites,it should be used if at all
possible, at least in the processing of incoming sessions (called the
SHIRE URL or assertion consumer service). Federation guidelines should
be considered when determining whether to implement SSL, and, in
<hr>
<h3><a name="3."></a>3. Installation</h3>
<h4><a name="3.a."></a>3.a. Software Requirements</h4>
-<p>The Shibboleth project makes binary packages available only for Windows,
-that are precompiled against recent releases of various required libraries such
-as OpenSSL. Binaries for other platforms may be available on a limited or ad hoc
-basis. It is highly advisable to build from source when using Shibboleth in
+<p>The Shibboleth project makes official binary packages available only for
+Windows, precompiled against recent releases of various required libraries such
+as OpenSSL. Binaries or RPMs for other platforms may be available on a limited or
+ad hoc basis. It is highly advisable to build from source when using Shibboleth in
a production environment in order to permit patching or updating of packages as
security holes and bugs are fixed. Building from source is necessary to give you
complete control over your deployment platform. The binary packages represent a
<p>The software requirements listed correspond to the binary distribution. In
general, source builds should work against all recent versions of the operating
systems and software dependencies listed below. For specific questions, inquire
-to the support mailing list, or give it a try. Note that OpenSSL releases
+or search the support mailing list, or give it a try. Note that OpenSSL releases
frequent security updates; the version listed may not be the most current, but
most minor "letter" updates should be usable.</p>
<blockquote>
and <span class="fixed">libsablot.so</span> which will manifest
itself as segmentation faults when starting Apache. If a site wants
to use <span class="fixed">libphp4.so</span> and Shibboleth at the same time,
- then one of the following may be done:</b>
+ then one of the following may be done:</b></p>
<ol>
<li>Remove the options <span class="fixed">--with-pspell</span>
and <span class="fixed">--with-xslt-sablot</span> from PHP's
<li>Rebuild these two modules using the same version of GCC that
was used to compile Shibboleth.</li>
</ol>
- </p>
+ </blockquote>
</li>
<li><a href="http://www.apache.org/dist/httpd/">Apache 2.0.x</a>
<blockquote>
configuration using the <i>threads</i> and <i>shared</i> options.</p>
</blockquote>
</li>
- <p>Most other required libraries are either easy to update or not found
- on typical systems. See the <span class="fixed">INSTALL.txt</span> files
- in the OpenSAML and Shibboleth source distributions for specific requirements
- of a given release. The important requirements are for pthreads support and
- shared libraries on Unix platforms. Without both, building will be hard and
- stability unlikely.</p>
- </ul>
+ </ul>
+ <p>Most other required libraries are either easy to update or not found on
+ typical systems. See the <span class="fixed">INSTALL.txt</span> files in the
+ OpenSAML and Shibboleth source distributions for specific requirements of a
+ given release. The important requirements are for pthreads support and
+ shared libraries on Unix platforms. Without both, building will be hard and
+ stability unlikely.</p>
<p><b>Operating System Specific Notes:</b></p>
<ul type="circle">
<li>Windows NT/2000/XP/2003
environment variables for you. A default SHAR service can also
be installed, or you can install it manually using the
instructions in this guide.</p>
- <p>Note that debug/symbol versions of the libraries and software
- are included, and may be used by appending "debug" to the
+ <p>Note that debug versions of the libraries and software are
+ included, and may be used by appending "debug" to the
Shibboleth library path and using the corresponding modules and
binaries. If you do so, be aware that Apache and other modules
must also be compiled with Microsoft's debug runtime (via the /MDd
</li>
</ul>
</li>
- <li>RedHat Linux 9 / Fedora
- <ul type="disc">
- <li>
- <p>Apache 2.0 is included as the default Apache version in this release.</p>
- </li>
- </ul>
- </li>
- <li>RedHat Enterprise Linux
+ <li>RedHat Linux 9 / Fedora / RH Enterprise
<ul type="disc">
<li>
<p>Apache 2.0 is included as the default Apache version in this release.</p>
</li>
</ul>
</li>
- <li>Solaris 2.6+:
+ <li>Macintosh OS X 10.3
+ <ul type="disc">
+ <li>
+ <p>Apache 1.3 is included as the default Apache version in this release.</p>
+ </li>
+ </ul>
+ </li>
+ <li>Solaris 2.8+:
<ul type="disc">
<li>
<p>The shared library version of OpenSSL is required by
<li>If the OpenSSL libraries are not in the system's search path, they
should be added to the <span class="fixed">LD_LIBRARY_PATH</span> used by
Apache. You will also usually need to add <span class="fixed">/opt/shibboleth/lib</span>
- to <span class="fixed">LD_LIBRARY_PATH</span> as well.</li>
+ to <span class="fixed">LD_LIBRARY_PATH</span> as well. Note that on Mac OS X, the
+ environment variable used for this purpose is named
+ <span class="fixed">DYLD_LIBRARY_PATH</span></li>
<li>The SHAR must be started along with Apache. Among other methods on
Unix, this can be done either by creating a separate SHAR startup script
or by modifying Apache's RC script to start/stop the <span class="fixed">
the configuration file and schemas, but the SHIBCONFIG and SHIBSCHEMAS
environment variables may be used as well. Command line options can also
be used to specify them.</p>
- <p>On Windows, the SHAR is a service and is managed separately.</li>
+ <p>On Windows, the SHAR is a service and is managed separately. Newer versions
+ of Windows support automatic restart of failed services. We suggest using this
+ feature to restart the SHAR when it fails. Although stability is good,
+ maximum reliability will be achieved by monitoring the process.</li>
<li>By default, the Shibboleth modules are configured to log information
on behalf of Apache to the file <span class="fixed">
/opt/shibboleth/var/log/shibboleth/shire.log</span>, though this can be
may require that the file be manually created and permissions assigned
to whatever user Apache is configured to run under. If the file does not
appear when Apache runs with the modules loaded, check for permission
- problems.</li>
+ problems or change the location used.</li>
<li>The options in <span class="fixed">shibboleth.xml</span> must be
configured as documented in <a href="#4.a.">4.a</a>. Apache content may
then need to be modified for Shibboleth authentication. This is
above. The priority should be High, and once the filter is loaded,
make sure it appears in the list <b>below</b> the "sspifilt" entry.
Restart IIS and make sure the filter shows up with a green arrow.
- Check the Windows event log if it fails to load.</li>
+ Check the Windows event log and/or shire.log if it fails to load.</li>
<li type="a">Secondly, map a special, distinct file extension, such as
<span class="fixed">.shire</span>, to the ISAPI library so that
virtual URLs can be specified to invoke the extension handler for each
versions of IIS, checking the "Script Engine" box is suggested,
as it will permit the extension to handle requests in directories with only
script permissions assigned.</li>
- <li type="a"><font color=#444499>(IIS 6 Only)</font> A new Web
+ <li type="a"><font color="#444499">(IIS 6 Only)</font> A new Web
Service Extension must be defined for Shibboleth; without this, the
mapping from <span class="fixed">*.shire</span> to <span
class="fixed">isapi_shib.dll</span> won't occur and a file error
- will appear Add this extension with an arbitrary name and associate
+ will appear. Add this extension with an arbitrary name and associate
it with <span class="fixed">isapi_shib.dll</span>.</li>
</ol>
</li>
<li>All other aspects of configuration are handled via the
<span class="fixed">shibboleth.xml</span> file and associated XML
files described in subsequent sections. Particular use is made of
- the <span class="fixed">/SHIRE/Implementation/ISAPI</span> element that allows
- IIS sites to be mapped to scheme, hostname, and port for proper request
- mapping and generation of redirects.</li>
+ the <span class="fixed">/SHIRE/Implementation/ISAPI</span> element
+ that allows IIS sites to be mapped to a hostname for proper request
+ mapping and generation of redirects.</li>
<li>Instance IDs are used in the IIS metabase to identify web sites. In older versions,
they are applied starting with 1(one) and number the web sites in order in the
Internet Services Manager from top to bottom. Newer versions appear to assign
some IID values with strange ASCII formulas applied to the site name. A simple
- ASP or CGI script can be run within a site to dump the INSTANCE_ID header.</li>
+ ASP or CGI script can be run within a site to dump the INSTANCE_ID header.
+ Newer versions actually list the site ID in the GUI console.</li>
<li>See the following section for information on running the SHAR
service on Windows.</li>
<li>The options in <span class="fixed">shibboleth.xml</span> must be
<h4><a name="4.a."></a>4.a. Configuring <span class="fixed">shibboleth.xml</span></h4>
<blockquote>
<p>The configuration for the target is mostly contained within <span class="fixed">shibboleth.xml</span>,
- located by default at <span class="fixed">\opt\shibboleth\etc\shibboleth\shibboleth.xml</span>.
+ located by default at <span class="fixed">/opt/shibboleth/etc/shibboleth/shibboleth.xml</span>.
The target comes pre-configured with certificates and settings that will work against a test origin
running on the same server; however, there are several values that must later be changed to interoperate
with other sites securely and effectively.</p>
<a class="fixedlink" href="#confRequestMapProvider"><RequestMapProvider type="edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap"></a>
<a class="fixedlink" href="#confRequestMap"><RequestMap applicationId="default"></a>
- <a class="fixedlink" href="#confHost"><Host name="localhost" scheme="https"></a>
+ <a class="fixedlink" href="#confHost"><Host name="localhost"></a>
<a class="fixedlink" href="#confPath"><Path name="secure" requireSession="true" exportAssertion="true">
- <!-- Example shows a subfolder on the SSL port assigned to a separate <Application> -->
+ <!-- Example shows a subfolder on the default ports assigned to a separate <Application> -->
<Path name="admin" applicationId="foo-admin"/>
</Path></a>
<a class="fixedlink" href="#confHost"></Host></a>
- <a class="fixedlink" href="#confHost"><Host name="localhost" scheme="http"></a>
- <a class="fixedlink" href="#confPath"><Path name="secure" requireSession="true" exportAssertion="true"/></a>
- <a class="fixedlink" href="#confHost"></Host></a>
<a class="fixedlink" href="#confRequestMap"></RequestMap></a>
<a class="fixedlink" href="#confRequestMapProvider"></RequestMapProvider></a>
<!-- IIS only:
<a class="fixedlink" href="#confImplementation"><Implementation></a>
<a class="fixedlink" href="#confISAPI"><ISAPI normalizeRequest="true"></a>
- <a class="fixedlink" href="#confSite"><Site id="1" scheme="https" host="localhost" port="443"/></a>
+ <a class="fixedlink" href="#confSite"><Site id="1" name="localhost" /></a>
<a class="fixedlink" href="#confISAPI"></ISAPI></a>
<a class="fixedlink" href="#confImplementation"></Implementation></a>
-->
<li>
<p>The main <a href="#confApplications"><span class="fixed">Applications</span></a> element's
<span class="fixed">providerId</span> attribute must be changed to reflect the URI this target will
- use to identify itself to origins by default. This will often be approved or supplied by a federation.</p>
+ use to identify itself to origins by default. This will often be submitted to a federation for
+ approval, but is generally a URI chosen by the deployer to uniquely identify his/her service.
+ For example, if Amazon.com were running Shibboleth (stop laughing), its identifier might be
+ <span class="fixed">https://amazon.com/shibboleth</span></p>
</li>
<li>
<p>The <span class="fixed">supportContact</span> and error templates for the target found in the
<p>All elements are optional unless otherwise specified. All attributes of an element are optional unless
designated <span class="mandatory">mandatory</span> by a purple background.</p>
<dl>
- <dd class="attribute"><a name="confAAPProvider"><span class="fixed"><AAPProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.target.provider.XMLAAP"</span> uri="<i>pathname</i>"/></span></dd>
+ <dd class="attribute"><a name="confAAPProvider"><span class="fixed"><AAPProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.target.provider.XMLAAP"</span> uri="<i>pathname</i>"/></span></a></dd>
<dd class="value">
<p>This element is used to specify individual attribute acceptance policies that will apply to an application
and may appear zero or more times within the <a href="#confApplications"><span class="fixed">Applications</span></a>
element can be replaced within individual <a href="#confApplication"><span class="fixed">Application</span></a> elements.</p>
</dd>
- <dd class="attribute"><a name="confApplication"><span class="fixed"><Application <span class="mandatory">id="<i>identifier</i>"</span> providerId="<i>identifier</i>" signRequest="<i>true/false</i>" signedResponse="<i>true/false</i>" signedAssertions="<i>true/false</i>"></span></dd>
+ <dd class="attribute"><a name="confApplication"><span class="fixed"><Application <span class="mandatory">id="<i>identifier</i>"</span> providerId="<i>identifier</i>" signRequest="<i>true/false</i>" signedResponse="<i>true/false</i>" signedAssertions="<i>true/false</i>"></span></a></dd>
<dd class="value">
<p>Individual applications that require different attributes, session settings, metadata, etc. can be differentiated
from the default configuration as specified in the <a href="#confApplications"><span class="fixed">Applications</span></a>
that will be used when communicating with origin sites to request authentication or attributes.
This value is referenced by origins when creating rules for the release of attributes to targets and will
often be provided to federations to facilitate origin configuration. If none is specified, the default
- <a href="#confApplications><span class="fixed">Applications</span></a> element's
+ <a href="#confApplications"><span class="fixed">Applications</span></a> element's
<span class="fixed">providerId</span> applies.</li>
<li><span class="fixed">signRequest</span>: If <span class="fixed">true</span>, the target will sign attribute
requests that it sends to origins on behalf of this application. This is usually unnecessary, as the
</ul>
</dd>
- <dd class="attribute"><a name="confApplications"><span class="fixed"><Applications <span class="mandatory">id="<i>default</i>" providerId="<i>identifier</i>"</span> signRequest="<i>true/false</i>" signedResponse="<i>true/false</i>" signedAssertions="<i>true/false</i>"></span></dd>
+ <dd class="attribute"><a name="confApplications"><span class="fixed"><Applications <span class="mandatory">id="<i>default</i>" providerId="<i>identifier</i>"</span> signRequest="<i>true/false</i>" signedResponse="<i>true/false</i>" signedAssertions="<i>true/false</i>"></span></a></dd>
<dd class="value">
<p>The <span class="fixed">Applications</span> element must appear once and contains default settings for requests
handled by the target. It must contain at least one each of the <a href="#confSessions"><span class="fixed">Sessions</span></a>,
<span class="fixed">shireURL</span> so that new sessions can be unambiguously mapped to a particular application.</p>
</dd>
- <dd class="attribute"><a name="confArgument"><span class="fixed"><Argument><i>value</i></Argument></span></dd>
+ <dd class="attribute"><a name="confArgument"><span class="fixed"><Argument><i>value</i></Argument></span></a></dd>
<dd class="value">
<p>The <span class="fixed">Argument</span> element is used in the
<a href="#confMySQLSessionCache"><span class="fixed">MySQLSessionCache</span></a> element to specify one or more
arguments to pass to the MySQL database engine.</p>
</dd>
- <dd class="attribute"><a name="confAttributeDesignator"><span class="fixed"><saml:AttributeDesignator <span class="mandatory">AttributeName="<i>name</i>" AttributeNamespace="<i>namespace</i>"</span>></span></dd>
+ <dd class="attribute"><a name="confAttributeDesignator"><span class="fixed"><saml:AttributeDesignator <span class="mandatory">AttributeName="<i>name</i>" AttributeNamespace="<i>namespace</i>"</span>></span></a></dd>
<dd class="value">
<p>The <span class="fixed">AttributeDesignator</span> element is used in the
<a href="#confApplications"><span class="fixed">Applications</span></a> and
it isn't possible to "remove" them and revert to none within a particular application.</p>
</dd>
- <dd class="attribute"><a name="confAudience"><span class="fixed"><saml:Audience><i>value</i></saml:Audience></span></dd>
+ <dd class="attribute"><a name="confAudience"><span class="fixed"><saml:Audience><i>value</i></saml:Audience></span></a></dd>
<dd class="value">
<p>The <span class="fixed">Audience</span> element is used in the
<a href="#confApplications"><span class="fixed">Applications</span></a> and
as an audience value.</p>
<p>Within an <a href="#confApplication"><span class="fixed">Application</span></a> element, this setting is not
inherited from the <a href="#confApplications"><span class="fixed">Applications</span></a> element. Any values
- desired must be specified. In most cases, this element can be omitted.</p>
+ desired must be specified. In most cases, this element can be omitted unless required for supporting legacy
+ origins running older Shibboleth versions.</p>
</dd>
- <dd class="attribute"><a name="confCAPath"><span class="fixed"><CAPath><i>pathname</i></CAPath></span></dd>
+ <dd class="attribute"><a name="confCAPath"><span class="fixed"><CAPath><i>pathname</i></CAPath></span></a></dd>
<dd class="value">
<p>Paired with a <a href="#confCredPath"><span class="fixed">Path</span></a> element within a
<a href="#confFileResolver"><span class="fixed">FileResolver</span></a> element, it allows for the specification
chain already.</p>
</dd>
- <dd class="attribute"><a name="confCertificate"><span class="fixed"><Certificate format="<i>type</i>"></span></dd>
+ <dd class="attribute"><a name="confCertificate"><span class="fixed"><Certificate format="<i>type</i>"></span></a></dd>
<dd class="value">
<p>This specifies the certificate corresponding to this set of credentials. The certificate itself must be specified
by a <a href="#confCredPath"><span class="fixed">Path</span></a> element contained by this element. If the certificate
paired with the corresponding private key using the <a href="#confKey"><span class="fixed">Key</span></a> element.</p>
</dd>
- <dd class="attribute"><a name="confCredentials"><span class="fixed"><Credentials xmlns="urn:mace:shibboleth:credentials:1.0"></span></dd>
+ <dd class="attribute"><a name="confCredentials"><span class="fixed"><Credentials xmlns="urn:mace:shibboleth:credentials:1.0"></span></a></dd>
<dd class="value">
<p>This element is the container for credentials used by the XML-based credentials provider with type
"edu.internet2.middleware.shibboleth.common.Credentials". These credentials are used by the target to
one or more <a href="#confFileResolver"><span class="fixed">FileResolver</span></a> elements.</p>
</dd>
- <dd class="attribute"><a name="confCredentialsProvider"><span class="fixed"><CredentialsProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.Credentials"</span>></span></dd>
+ <dd class="attribute"><a name="confCredentialsProvider"><span class="fixed"><CredentialsProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.Credentials"</span>></span></a></dd>
<dd class="value">
<p>This element is the container for providers of credentials used by the target and is placed inside the
<a href="#confShibbolethTargetConfig"><span class="fixed">ShibbolethTargetConfig</span></a> element. The supplied
to be used by the target. Other provider types might require different content.</p>
</dd>
- <dd class="attribute"><a name="confCredentialUse"><span class="fixed"><CredentialUse <span class="mandatory">TLS="<i>string</i>" Signing="<i>string</i>"</span>></span></dd>
+ <dd class="attribute"><a name="confCredentialUse"><span class="fixed"><CredentialUse <span class="mandatory">TLS="<i>string</i>" Signing="<i>string</i>"</span>></span></a></dd>
<dd class="value">
<p>Used in the <a href="#confApplications"><span class="fixed">Applications</span></a> or
<a href="#confApplication"><span class="fixed">Application</span></a> elements to specify the credentials used by
to use for specific origins or federations.</p>
</dd>
- <dd class="attribute"><a name="confErrors"><span class="fixed"><Errors <span class="mandatory">shire="<i>pathname</i>" rm="<i>pathname</i>" access="<i>pathname</i>"</span> supportContact="<i>e-mail</i>" logoLocation="<i>URL</i>"/></span></dd>
+ <dd class="attribute"><a name="confErrors"><span class="fixed"><Errors <span class="mandatory">shire="<i>pathname</i>" rm="<i>pathname</i>" access="<i>pathname</i>"</span> supportContact="<i>e-mail</i>" logoLocation="<i>URL</i>"/></span></a></dd>
<dd class="value">
<p>Shibboleth is capable of displaying customized error pages based on templates and information provided by
additional attributes in this element. These should all be customized to fit the requirements of the target application.
will insert the value of that attribute.</p>
</dd>
- <dd class="attribute"><a name="confExtensions"><span class="fixed"><Extensions></span></dd>
+ <dd class="attribute"><a name="confExtensions"><span class="fixed"><Extensions></span></a></dd>
<dd class="value">
Extension libraries for one of the Shibboleth components or the entire target can be specified using this element
depending on where it's present. It may be contained by any of the
It must contain one or more <a href="#confLibrary"><span class="fixed">Library</span></a> elements.
</dd>
- <dd class="attribute"><a name="confFederationProvider"><span class="fixed"><FederationProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.provider.XMLMetadata"</span> uri="<i>pathname</i>"></span></dd>
+ <dd class="attribute"><a name="confFederationProvider"><span class="fixed"><FederationProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.provider.XMLMetadata"</span> uri="<i>pathname</i>"></span></a></dd>
<dd class="value">
<p>This element, when specified within an <a href="#confApplications"><span class="fixed">Applications</span></a>
or <a href="#confApplication"><span class="fixed">Application</span></a> element, points to operational metadata either
element can be replaced within individual <a href="#confApplication"><span class="fixed">Application</span></a> elements.</p>
</dd>
- <dd class="attribute"><a name="confFileResolver"><span class="fixed"><FileResolver <span class="mandatory">Id="<i>string</i>"</span>></span></dd>
+ <dd class="attribute"><a name="confFileResolver"><span class="fixed"><FileResolver <span class="mandatory">Id="<i>string</i>"</span>></span></a></dd>
<dd class="value">
<p>This element defines files used to store a private key, certificate, and certificate authorities and associates
the set with an identifier. Placed inside the <a href="#confCredentials"><span class="fixed">Credentials</span></a>
<a href="#confCertificate"><span class="fixed">Certificate</span></a> element.</p>
</dd>
- <dd class="attribute"><a name="confHost"><span class="fixed"><Host scheme="<i>protocol</i>" <span class="mandatory">name="<i>fqdn</i>"</span> port="<i>integer</i>" applicationId="<i>id</i>" requireSession="<i>true/false</i>" exportAssertion="<i>true/false</i>"></span></dd>
+ <dd class="attribute"><a name="confHost"><span class="fixed"><Host scheme="<i>protocol</i>" <span class="mandatory">name="<i>fqdn</i>"</span> port="<i>integer</i>" applicationId="<i>id</i>" requireSession="<i>true/false</i>" exportAssertion="<i>true/false</i>"></span></a></dd>
<dd class="value">
<p>Individual (real or virtual) hosts that this target protects are enumerated by <span class="fixed">Host</span> elements
inside the <a href="#confRequestMap"><span class="fixed">RequestMap</span></a> element. If a request is processed by
<ul>
<li><span class="fixed">scheme</span>: This specifies the protocol on which this host responds.
Valid choices are <span class="fixed">http</span>, <span class="fixed">https</span>, <span class="fixed">ftp</span>,
- <span class="fixed">ldap</span>, and <span class="fixed">ldaps</span>.</li>
+ <span class="fixed">ldap</span>, and <span class="fixed">ldaps</span>. If omitted, both <span class="fixed">http</span>
+ and <span class="fixed">https</span> are in effect.</li>
<li class="mandatory"><span class="fixed">name</span>: This is the fully-qualified domain name of the host.
This appended to the <span class="fixed">scheme</span> must match what is contained in the URL for the element's
settings to apply to the request.</li>
</ul>
</dd>
- <dd class="attribute"><a name="confImplementation"><span class="fixed"><Implementation></span></dd>
+ <dd class="attribute"><a name="confImplementation"><span class="fixed"><Implementation></span></a></dd>
<dd class="value">
<p>A container element placed inside the <a href="#confSHIRE"><span class="fixed">SHIRE</span></a> element,
the contents of this element will vary depending on the web server or environment that this Shibboleth deployment serves.
<a href="#confISAPI"><span class="fixed">ISAPI</span></a> element.</p>
</dd>
- <dd class="attribute"><a name="confISAPI"><span class="fixed"><ISAPI normalizeRequest="<i>true/false</i>"></span></dd>
+ <dd class="attribute"><a name="confISAPI"><span class="fixed"><ISAPI normalizeRequest="<i>true/false</i>"></span></a></dd>
<dd class="value">
<p>The configuration information for Shibboleth targets deployed on Microsoft IIS is stored inside this container element.
This element must contain one or more <a href="#confSite"><span class="fixed">Site</span></a> elements, each of which
- maps an INSTANCE ID value to a hostname. If <span class="fixed">normalizeRequest</span> is
+ maps an INSTANCE ID value to a default hostname. If <span class="fixed">normalizeRequest</span> is
<span class="fixed">true</span> (the default), all redirects and computed request URLs generated by Shibboleth will
be created using the hostname assigned to the site instance handling the request. If <span class="fixed">false</span>,
the browser's supplied URL is sometimes used to compute the information. Placed inside the
<a href="#confImplementation"><span class="fixed">Implementation</span></a> element.</p>
</dd>
- <dd class="attribute"><a name="confKey"><span class="fixed"><Key format="<i>type</i>"></span></dd>
+ <dd class="attribute"><a name="confKey"><span class="fixed"><Key format="<i>type</i>"></span></a></dd>
<dd class="value">
<p>Specifies a file containing a private key to be used within a set of credentials. Valid formats are
<span class="fixed">PEM</span> (the default), <span class="fixed">DER</span>, and <span class="fixed">PKCS12</span>.
<a href="#confCredPath"><span class="fixed">Path</span></a> element.</p>
</dd>
- <dd class="attribute"><a name="confLibrary"><span class="fixed"><Library <span class="mandatory">path="<i>pathname</i>"</span> fatal="<i>true/false</i>"/></span></dd>
+ <dd class="attribute"><a name="confLibrary"><span class="fixed"><Library <span class="mandatory">path="<i>pathname</i>"</span> fatal="<i>true/false</i>"/></span></a></dd>
<dd class="value">
<p>This element defines an extension library for one of Shibboleth's components and is placed within an
<a href="#confExtensions"><span class="fixed">Extensions</span></a> element.</p>
</ul>
</dd>
- <dd class="attribute"><a name="confListener"><span class="fixed"><Listener <span class="mandatory">type="<i>string</i>"</span>></span></dd>
+ <dd class="attribute"><a name="confListener"><span class="fixed"><Listener <span class="mandatory">type="<i>string</i>"</span>></span></a></dd>
<dd class="value">
<p>Specifies a pluggable implementation of a mechanism for communication between the web server and SHAR,
specified in the <span class="fixed">type</span> attribute. This element is placed within the
<a href="#confUnixListener"><span class="fixed">UnixListener</span></a> elements.</p>
</dd>
- <dd class="attribute"><a name="confMemorySessionCache"><span class="fixed"><MemorySessionCache AAConnectTimeout="<i>seconds</i>" AATimeout="<i>seconds</i>" cacheTimeout="<i>seconds</i>" cleanupInterval="<i>seconds</i>" defaultLifetime="<i>seconds</i>" propagateErrors="<i>true/false</i>" retryInterval="<i>seconds</i>" strictValidity="<i>true/false</i>"/></span></dd>
+ <dd class="attribute"><a name="confMemorySessionCache"><span class="fixed"><MemorySessionCache AAConnectTimeout="<i>seconds</i>" AATimeout="<i>seconds</i>" cacheTimeout="<i>seconds</i>" cleanupInterval="<i>seconds</i>" defaultLifetime="<i>seconds</i>" propagateErrors="<i>true/false</i>" retryInterval="<i>seconds</i>" strictValidity="<i>true/false</i>"/></span></a></dd>
<dd class="value">
<p>Shibboleth will cache sessions and received attributes in memory if this element is found in the
<a href="#confSHAR"><span class="fixed">SHAR</span></a> element. This element is mutually exclusive with the
</ul>
</dd>
- <dd class="attribute"><a name="confMySQLSessionCache"><span class="fixed"><MySQLSessionCache mysqlTimeout="<i>seconds</i>"/></span></dd>
+ <dd class="attribute"><a name="confMySQLSessionCache"><span class="fixed"><MySQLSessionCache mysqlTimeout="<i>seconds</i>"/></span></a></dd>
<dd class="value">
<p>Shibboleth will back the memory cache of sessions using an embedded MySQL database if this element is found
in the <a href="#confSHAR"><span class="fixed">SHAR</span></a> element. Arguments may be passed directly to
</ul>
</dd>
- <dd class="attribute">(RequestMap) <a name="confPath"><span class="fixed"><Path <span class="mandatory">name="<i>pathname</i>"</span> applicationId="<i>id</i>" requireSession="<i>true/false</i>" exportAssertion="<i>true/false</i>"></span></dd>
+ <dd class="attribute">(RequestMap) <a name="confPath"><span class="fixed"><Path <span class="mandatory">name="<i>pathname</i>"</span> applicationId="<i>id</i>" requireSession="<i>true/false</i>" exportAssertion="<i>true/false</i>"></span></a></dd>
<dd class="value">
<p>This element allows for different application identifiers and session handling to be defined iteratively for
subdirectories or documents within a host. Requests are processed on a best-match basis, with the innermost
</ul>
</dd>
- <dd class="attribute">(Credential) <a name="confCredPath"><span class="fixed"><Path><i>pathname</i></Path></span></dd>
+ <dd class="attribute">(Credential) <a name="confCredPath"><span class="fixed"><Path><i>pathname</i></Path></span></a></dd>
<dd class="value">
<p>Placed inside the <a href="#confKey"><span class="fixed">Key</span></a> and
<a href="#confCertificate"><span class="fixed">Certificate</span></a> elements to specify the pathname of the file
containing the credential.</p>
</dd>
- <dd class="attribute"><a name="confRelyingParty"><span class="fixed"><RelyingParty <span class="mandatory">name="<i>string</i>" TLS="<i>string</i>" Signing="<i>string</i>"</span></span>></dd>
+ <dd class="attribute"><a name="confRelyingParty"><span class="fixed"><RelyingParty <span class="mandatory">name="<i>string</i>" TLS="<i>string</i>" Signing="<i>string</i>"</span>></span></a></dd>
<dd class="value"><p>One or more <span class="fixed">RelyingParty</span> elements may be contained by a <a href="#confCredentialUse"><span class="fixed">CredentialUse</span></a> element to enumerate relying parties for which a distinct set of credentials should be used. The <span class="fixed">TLS</span> and <span class="fixed">Signing</span> attribute values reference the identifiers of credential resolvers defined in <a href="#confCredentialsProvider"><span class="fixed">CredentialsProvider</span></a> elements.</p>
<ul>
<li class="mandatory"><span class="fixed">name</span>: Identifies the origin site or group of sites to which the credentials specified in the element apply. This is used to match the providerId sent within attribute assertions from origin sites against a set of "groups" based on metadata.</li>
</ul>
</dd>
- <dd class="attribute"><a name="confRequestMap"><span class="fixed"><RequestMap <span class="mandatory">applicationId="<i>default</i>"</span> requireSession="<i>true/false</i>" exportAssertion="<i>true/false</i>"></span></dd>
+ <dd class="attribute"><a name="confRequestMap"><span class="fixed"><RequestMap <span class="mandatory">applicationId="<i>default</i>"</span> requireSession="<i>true/false</i>" exportAssertion="<i>true/false</i>"></span></a></dd>
<dd class="value">
<p>The <span class="fixed">RequestMap</span> element is a container holding
<a href="#confHost"><span class="fixed">Host</span></a> and <a href="#confPath"><span class="fixed">Path</span></a>
</ul>
</dd>
- <dd class="attribute"><a name="confRequestMapProvider"><span class="fixed"><RequestMapProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap"</span> uri="<i>pathname</i>"></span></dd>
+ <dd class="attribute"><a name="confRequestMapProvider"><span class="fixed"><RequestMapProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap"</span> uri="<i>pathname</i>"></span></a></dd>
<dd class="value">
<p>This element specifies a request mapper that defines how Shibboleth will handle sessions and other behavior
for a given request. For the built-in type "edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap",
the <span class="fixed">uri</span> attribute must contain the local pathname of an XML file containing one.</p>
</dd>
- <dd class="attribute"><a name="confRevocationProvider"><span class="fixed"><RevocationProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.provider.XMLRevocation"</span> uri="<i>pathname</i>"></span></dd>
+ <dd class="attribute"><a name="confRevocationProvider"><span class="fixed"><RevocationProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.provider.XMLRevocation"</span> uri="<i>pathname</i>"></span></a></dd>
<dd class="value">
<p>This element, when specified within an <a href="#confApplications"><span class="fixed">Applications</span></a>
or <a href="#confApplication"><span class="fixed">Application</span></a> element, points to revocation information either
element can be replaced within individual <a href="#confApplication"><span class="fixed">Application</span></a> elements.</p>
</dd>
- <dd class="attribute"><a name="confSessionCache"><span class="fixed"><SessionCache <span class="mandatory">type="<i>string</i>"</span>></span></dd>
+ <dd class="attribute"><a name="confSessionCache"><span class="fixed"><SessionCache <span class="mandatory">type="<i>string</i>"</span>></span></a></dd>
<dd class="value">
<p>Specifies a pluggable session cache implementation of the specified <span class="fixed">type</span>. This element
is placed within the <a href="#confSHAR"><span class="fixed">SHAR</span></a> element and is mutually exclusive with
timeout="<i>seconds</i>"
checkAddress="<i>true/false</i>"
cookieName="<i>URL</i>"
-cookieProps="<i>URL</i>"></span></dd>
+cookieProps="<i>URL</i>"></span></a></dd>
<dd class="value">
<p>Configuration parameters that affect the way Shibboleth handles sessions for an individual application are bundled
in this element, which must be included in each <a href="#confApplication"><span class="fixed">Application</span></a>
</ul>
</dd>
- <dd class="attribute"><a name="confSHAR"><span class="fixed"><SHAR logger="<i>pathname</i>"></span></dd>
+ <dd class="attribute"><a name="confSHAR"><span class="fixed"><SHAR logger="<i>pathname</i>"></span></a></dd>
<dd class="value">
<p>This is the container element for configuration information pertaining to the SHAR, the target component responsible
for most attribute and session processing. Its single attribute, <span class="fixed">logger</span>, points to a
information into a MySQL database.</p>
</dd>
- <dd class="attribute"><a name="confShibbolethTargetConfig"><span class="fixed"><ShibbolethTargetConfig clockSkew="integer"></span></dd>
+ <dd class="attribute"><a name="confShibbolethTargetConfig"><span class="fixed"><ShibbolethTargetConfig clockSkew="integer"></span></a></dd>
<dd class="value">
<p>This is the root element for target configuration and must be present once and only once. It must always contain a
<a href="#confSHAR"><span class="fixed">SHAR</span></a> element, a
</ul>
</dd>
- <dd class="attribute"><a name="confSHIRE"><span class="fixed"><SHIRE logger="<i>pathname</i>"></span></dd>
+ <dd class="attribute"><a name="confSHIRE"><span class="fixed"><SHIRE logger="<i>pathname</i>"></span></a></dd>
<dd class="value">
<p>This is the container element for configuration information pertaining to the SHIRE, the part of the target that
integrates into the web server environment. Its single attribute, <span class="fixed">logger</span>, points to a
which provides fine-grained control over aspects of target behavior at a host, path, or document level.</p>
</dd>
- <dd class="attribute"><a name="confSite"><span class="fixed"><Site <span class="mandatory">id="<i>INSTANCE_ID</i>" host="<i>fqdn</i>"</span> scheme="<i>http/https</i>" port="<i>integer</i>"></span></dd>
+ <dd class="attribute"><a name="confSite"><span class="fixed"><Site <span class="mandatory">id="<i>INSTANCE_ID</i>" name="<i>fqdn</i>"</span> scheme="<i>http/https</i>" port="<i>integer</i>"></span></a></dd>
<dd class="value">
<p>This element is placed in the <a href="#confISAPI"><span class="fixed">ISAPI</span></a> element to specify a
- mapping from individual instance ID's to the corresponding host, port, and scheme.</p>
+ mapping from individual instance ID's to a corresponding hostname. The port and scheme can also be specified, but
+ should normally be left out, enabling them to be determined from the browser request. Note that while IIS permits
+ multiple hostnames to be assigned to a web site, only one can be specified here. If you really need to allow for
+ multiple names (unusual), you should set the <span class="fixed">>normalizeRequest</span> attribute to false.</p>
</dd>
- <dd class="attribute"><a name="confTCPListener"><span class="fixed"><TCPListener <span class="mandatory">address="<i>pathname</i>" port="<i>integer</i>"</span> acl="<i>ip</i>"></span></dd>
+ <dd class="attribute"><a name="confTCPListener"><span class="fixed"><TCPListener <span class="mandatory">address="<i>pathname</i>" port="<i>integer</i>"</span> acl="<i>ip</i>"></span></a></dd>
<dd class="value">
<p>This element is placed within the <a href="#confSHAR"><span class="fixed">SHAR</span></a> element and is mutually
exclusive with the <a href="#confUnixListener"><span class="fixed">UnixListener</span></a> and
</ul>
</dd>
- <dd class="attribute"><a name="confTrustProvider"><span class="fixed"><TrustProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.provider.XMLTrust"</span> uri="<i>pathname</i>"></span></dd>
+ <dd class="attribute"><a name="confTrustProvider"><span class="fixed"><TrustProvider <span class="mandatory">type="edu.internet2.middleware.shibboleth.common.provider.XMLTrust"</span> uri="<i>pathname</i>"></span></a></dd>
<dd class="value">
<p>This element, when specified within an <a href="#confApplications"><span class="fixed">Applications</span></a>
or <a href="#confApplication"><span class="fixed">Application</span></a> element, points to trust metadata either
element can be replaced within individual <a href="#confApplication"><span class="fixed">Application</span></a> elements.</p>
</dd>
- <dd class="attribute"><a name="confUnixListener"><span class="fixed"><UnixListener address="<i>pathname</i>"></span></dd>
+ <dd class="attribute"><a name="confUnixListener"><span class="fixed"><UnixListener address="<i>pathname</i>"></span></a></dd>
<dd class="value">
<p>Use this element to specify a UNIX domain socket located at the <span class="fixed">pathname</span> specified in
the <span class="fixed">address</span> attribute at which the SHAR should listen for requests. This element must be
are used.</p>
<p>To require a session, either the Apache command, <span class="fixed">ShibRequireSession On</span>,
or the <span class="fixed">requireSession</span> boolean XML attribute on the
- <a href="#confRequestMap><span class="fixed">RequestMap</span></a>,
- <a href="#confHost><span class="fixed">Host</span></a>, or
- <a href="#confPath><span class="fixed">Path</span></a> elements in
+ <a href="#confRequestMap"><span class="fixed">RequestMap</span></a>,
+ <a href="#confHost"><span class="fixed">Host</span></a>, or
+ <a href="#confPath"><span class="fixed">Path</span></a> elements in
<span class="fixed">shibboleth.xml</span> can be used. Both approaches are equivalent, and
using either one to require a session will supersede a false or absent setting of the other type.</p>
<p>As an example, the following commands will require Shibboleth authentication for a resource:</p>
deferring real policy to an application.</p>
</blockquote>
</li>
- <p><span class="fixed">user</span></p>
- <blockquote>
+ <li><span class="fixed">user</span><blockquote>
<p>A space-delimited list of values, such as from the
<span class="fixed">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
attribute. Actually, any attribute can be mapped to REMOTE_USER,
<p>A complete command issued to <span class="fixed">siterefresh</span> might
take the form:</p>
<blockquote>
- <p><span class="fixed">/opt/shibboleth/bin/siterefresh --out IQ-sites.xml --cert internet2.pem \<br>
+ <p><span class="fixed">/opt/shibboleth/bin/siterefresh --out IQ-sites.xml --cert inqueue.pem \<br>
--url http://wayf.internet2.edu/InQueue/IQ-sites.xml </span></p>
</blockquote>
<p>It is recommended that such commands be added to a <span class="fixed">
</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.
- </dl>
+ starting the SHAR if you change this path.</p>
+</blockquote>
+<h4><a name="4.i."></a>4.i. Using Lazy Sessions</h4>
+<blockquote>
+ <p><b>For a background on sessions in Shibboleth, and a description of what
+ a lazy session is and why it would be useful, consult <a href="#1.g">section
+ 1.g</a>.</b></p>
+ <p>This section describes how an application can trigger the establishment
+ of a Shibboleth session and optionally receive attributes once its internal
+ logic decides this is necessary. It assumes the application is protected
+ using lazy sessions because the <span class="fixed">RequireSession</span>
+ attribute of the <a href="#confPath"><span class="fixed">Path</span></a> or
+ <a href="#confPath"><span class="fixed">Host</span></a> element protecting
+ it is set to <span class="fixed">false</span>. This application must be
+ aware of two pieces of information:</p>
+ <ul>
+ <li>The URL that should be accessed after the session is established;
+ frequently, this will be the application's own URL; and</li>
+ <li>The URL of the SHIRE associated with the <a
+ href="#confApplication"><span class="fixed">Application</span></a>
+ containing the URL to be accessed(contained within the corresponding <a
+ href="#confSessions"><span class="fixed">Sessions</span></a>
+ element).</li>
+ </ul>
+ <p>These two pieces of information must be combined by the application to an
+ appropriately formed URL to trigger session initiation as follows. To
+ request a session, the application returns an HTTP redirect that sends the
+ browser to the SHIRE URL with a parameter, <span
+ class="fixed">target</span>, containing the URL of the resource to return to
+ with a session. This will often be the URL that's triggering the redirect.
+ The SHIRE will generate the redirect to the WAYF and the rest proceeds as a
+ standard Shibboleth flow. This combined URL takes the form: <span class="fixed">https://<i>shireURL</i>?target=<i>applicationURL</i></span>.</p>
+ <p>For example, if an application located at <span
+ class="fixed">https://foo.com/portal</span> presents a page with an option
+ to login, it could respond to the login button by redirecting the browser to
+ <span
+ class="fixed">https://foo.com/Shibboleth.shire?target=https%3A%2F%2Ffoo.com%2Fportal</span>.</p>
+
</blockquote>
-<p><br>
-</p>
<hr>
<h3><a name="5."></a>5. Troubleshooting</h3>
<p>This section provides basic information about testing Shibboleth targets.
</blockquote>
</body>
-
</html>
projects / shibboleth / sp.git / blobdiff