<h2>Shibboleth Target Deployment Guide</h2>
</center>
<p>Shibboleth Target Deployment Guide<br>
-Shibboleth Version 1.0.1<br />
+Shibboleth Version 1.1<br />
July 25, 2003<br />
</p>
-<h3>This version of the deploy guide is for Shibboleth v1.0.1. For documentation
+<h3>This version of the deploy guide is for Shibboleth v1.1. For documentation
related to prior versions of Shibboleth, please consult the appropriate branch
in the Shibboleth CVS.</h3>
<h3>Federations have been abstracted out from the Shibboleth documentation. For
further information on using Shibboleth in a federation, refer to the federation
guide.</h3>
-<p>Shibboleth v1.0.1 is stable and secure enough to deploy in production
+<p>Shibboleth v1.1 is stable and secure enough to deploy in production
scenarios. It is backward compatible with 1.0 in all respects, including
configuration, but some older commands have been deprecated or replaced.</p>
-<p>Features and changes specific to 1.0.1 are marked with <span class="feature">
-[1.0.1]</span></p>
-<h4>Major New Features in 1.0 and 1.0.1</h4>
+<p>Features and changes specific to 1.1 are marked with <span class="feature">
+[1.1]</span></p>
+<h4>Major New Features in 1.0 and 1.1</h4>
<p>This new release contains several improvements and enhancements, including:
</p>
<h5>Federation Support</h5>
repositories, and computing the SAML attribute using business rules). This
should greatly simplify the process of configuring the AA to support
additional general attributes.</li>
+ <li>A sample resolver file for using standard LDAP person and inetOrgPerson
+ attributes is included. <span class="feature">[1.1]</span></li>
<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 deployments without privacy needs can configure identity-based
+ an attribute plugin. <span class="feature">[1.1]</span></li>
+ <li>Specialized sites without privacy needs can configure identity-based
handles interoperable with other SAML deployments. <span class="feature">
- [1.0.1]</span></li>
+ [1.1]</span></li>
</ol>
<h5>Target</h5>
<ol>
- <li>Significantly more flexibility in configuring targets to ensure
- robustness. Failover and redundant configurations are now supported.</li>
+ <li>Significantly more flexibility in configuring targets is provided to
+ ensure robustness. Failover and redundant configurations are now supported.</li>
<li>The SHAR may now optionally store its session and attribute cache in a
- back-end database in addition to the previously available in-memory option.
- This would allow a site to run an apache server farm, with multiple SHARs,
- supporting the same set of sessions.</li>
+ back-end database in addition to the previously available in-memory option.
+ </li>
+ <span class="feature">[1.1]</span> </li>
<li>Federation supplied files (sites.xml and trust.xml) are now refreshed in
- a much more robust manner.</li>
+ a much more robust manner. </li>
+ </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>
+ specialized deployment behind firewalls. <span class="feature">[1.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.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.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.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.</li>
+ 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>
<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.</li>
- <li>Local time string values are now used in log files.</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. <br>
+ </li>
+ <li>Local time string values are now used in log files. <br>
+ </li>
<li>Internationalization support has been extended.</li>
</ol>
<p>Before starting, please sign up for all applicable
<li><a href="#2.c."><font color="black">Security Considerations</font></a></li>
<li><a href="#2.d."><font color="black">Server Certificates</font></a></li>
<li><a href="#2.e."><font color="black">Attribute Release Policies</font></a></li>
- <li><a href="#2.f."><font color="black">Designate Contacts</font></a></li>
+ <li><a href="#2.f."><font color="#000000">Attribute Acceptance Policies</font></a></li>
<li><a href="#2.g."><font color="black">Browser Requirements</font></a></li>
<li><a href="#2.h."><font color="black">Clocks</font></a></li>
<li><a href="#2.i."><font color="black">Other Considerations</font></a></li>
the sets of attributes that both sites expect to correspond using are
congruent.</p>
</blockquote>
-<h4><a name="2.f."></a>2.f. Designate Contacts</h4>
+<h4><a name="2.f."></a>2.f. Attribute Acceptance Policies</h4>
<blockquote>
- <p>Since Shibboleth deals both with daily technical and operational issues
- and also with contractual issues, a set of contacts should be set up to
- support the user base and to facilitate interactions with other Shibboleth
- sites and federation members. It is recommended that at least technical and
- administrative contacts be designated. Names, titles, e-mail addresses, and
- phone numbers may all be useful information to provide.</p>
+ <p>When a target receives a set of attributes, it must evaluate them in the
+ context of the Attribute Authority that is providing them, to assess their
+ "reasonableness". For example, if the value of an attribute is expected to
+ be from a small set of enumerated choices, the value should be compared
+ against that list. If a particular attribute or value is only trusted when
+ asserted by specific origins, that too should be checked.</p>
+ <p>Targets are configured to accept specific attributes that they understand
+ and care about, and are also configured with the rules to apply before
+ accepting the attributes for use by the RM or an application. Attributes and
+ values that don't meet the target's requirements are filtered out. The set
+ of configuration rules to make these decisions is called an Attribute
+ Acceptance Policy (AAP).</p>
</blockquote>
<h4><a name="2.g."></a>2.g. Browser Requirements</h4>
<blockquote>
<blockquote>
<p><b>Operating System:</b> </p>
<ul type="circle">
+ <li>Windows NT/2000/XP/2003<ul type="disc">
+ <li><a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a> or
+ IIS 4.0+<blockquote>
+ <p>Apache must be compiled with mod_so for DSO module support,
+ and must include SSL support (preferably using
+ <span class="fixed">mod_ssl</span>), and EAPI support (which
+ <span class="fixed">mod_ssl</span> requires and provides).
+ Shibboleth can coexist with <span class="fixed">mod_auth</span>,
+ which may be compiled or loaded into the server for use
+ elsewhere, but Shibboleth does not need or use it.</p>
+ <p>Any Apache modules used, and Apache itself, must be compiled
+ with the Microsoft DLL-based runtime, selected by compiling with
+ the /MD switch.</p>
+ </blockquote>
+ </li>
+ <li>
+ <a href="http://shibboleth.internet2.edu/release/shib-download.html">
+ Shibboleth v1.1 Target for Windows</a><blockquote>
+ <p>Available in both self-installer and ZIP format, the
+ installer will prompt for an install path, change default
+ configuration files as appropriate for Windows, and set various
+ environment variables for you. A default SHAR service can also
+ be installed for you, 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
+ 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
+ compiler option). In most cases, you can safely ignore or even
+ delete the debug versions.</p>
+ </blockquote>
+ </li>
+ </ul>
+ </li>
+ <p> </li>
<li>RedHat 7.2-7.3:<ul type="disc">
<li><a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a><blockquote>
<p>Apache must be compiled with mod_so for DSO module support,
</li>
<li>
<a href="http://shibboleth.internet2.edu/release/shib-download.html">
- Shibboleth v1.0.1 Target for RedHat</a></li>
+ Shibboleth v1.1 Target for RedHat</a></li>
<li><a href="http://www.openssl.org/source/">openssl-0.9.6, revision
<span class="fixed">i</span> or newer</a></li>
<li>libstdc++3-3.0.4-1.i386.rpm and libgcc-3.0.4-1.i386.rpm<blockquote>
</li>
<li>Solaris 2.8:<ul type="disc">
<li><a HREF="ftp://ftp.openssl.org/source/openssl-0.9.7b.tar.gz">
- openssl-0.9.7b</a>
+ openssl-0.9.7</a>
<blockquote>
<p>The shared library version of OpenSSL is required by
Shibboleth. The static libraries may be installed as well if
necessary for other applications, but cannot be used within
- mod_ssl or any other Apache modules.</p>
+ mod_ssl or any other Apache modules. openssl-0.9.7b, the latest
+ security fix release, has been tested, but any 0.9.7 version
+ should work.</p>
</blockquote>
</li>
<li><a href="http://www.apache.org/dist/httpd/">Apache 1.3.27</a><blockquote>
</li>
<li>
<a href="http://shibboleth.internet2.edu/release/shib-download.html">
- Shibboleth v1.0.1 Target for Solaris</a></li>
+ Shibboleth v1.1 Target for Solaris</a></li>
<li><b>Portions of the <span class="fixed">libphp4</span> Apache
plugin are written in C++, as is Shibboleth. There is a known
conflict with the PHP extensions <span class="fixed">libpspell.so</span>
<ul type="disc">
<li>
<a href="http://shibboleth.internet2.edu/release/shib-download.html">
- Shibboleth 1.0.1 Target for RedHat</a></li>
+ Shibboleth 1.1 Target for RedHat</a></li>
<li><a href="http://www.openssl.org/source/">openssl-0.9.6, revision
<span class="fixed">i</span> or newer</a></li>
<li>libstdc++3-3.0.4-1.i386.rpm and libgcc-3.0.4-1.i386.rpm
<ol type="1">
<li>Ensure that you have obtained the proper
<a href="http://shibboleth.internet2.edu/release/shib-download.html">
- tarball</a> for your operating system.</li>
+ tarball</a> or installer for your operating system.</li>
<li>On Unix, the tarballs expand into <span class="fixed">
/opt/shibboleth</span>, and should be expanded as <span class="fixed">
root</span> from <span class="fixed">/</span>. If you use a different
notwithstanding):<blockquote>
<p><span class="fixed">$ ls -l<br>
drwxr-xr-x 2 root root 4096 Oct 24 03:54 bin<br>
+ drwxr-xr-x 2 root root 4096 Oct 24 03:54 data<br>
drwxr-xr-x 2 root root 4096 Oct 24 03:54 doc<br>
drwxr-xr-x 4 root root 4096 Oct 24 03:54 etc<br>
- drwxr-xr-x 13 root root 4096 Oct 24 03:54 include<br>
+ drwxr-xr-x 9 root root 4096 Oct 24 03:54 include<br>
drwxr-xr-x 4 root root 4096 Oct 24 03:55 lib<br>
drwxr-xr-x 2 root root 4096 Oct 24 03:55 libexec<br>
drwxr-xr-x 4 root root 4096 Oct 24 02:02 share</span></p>
</blockquote>
- <p>On Windows, until a real installer is available, the zip file should
- be unpacked beneath the root of the system drive, where it will create
- an <span class="fixed">\opt\shibboleth</span> tree that resembles the
- Unix layout above. This will allow the standard configuration options to
+ <p>On Windows, if the installer is not used, the zip file should be
+ unpacked beneath the root of the system drive, where it will create an
+ <span class="fixed">\opt\shibboleth</span> tree that resembles the Unix
+ layout above. This will allow the standard configuration options to
work. <b>The <span class="fixed">C:\opt\shibboleth\lib</span> directory
- MUST be added to the system path to enable proper operation.</b> </li>
+ MUST be added to the system path to enable proper operation.</b> If you
+ use a different location, changes to various configuration files must be
+ made by hand. The installer can do this for you, and is recommended in
+ such cases.</li>
</ol>
</blockquote>
<h4><a name="3.c."></a>3.c. Configure Apache 1.3.x</h4>
</dl>
</li>
<li><a name="3.c.2."></a>These modifications must be made to the Apache
- startup script:<p>Add the following environment variable:</p>
+ startup script
on Unix:<p>Add the following environment variable:</p>
<blockquote>
<p><span class="fixed">SHIBCONFIG=/opt/shibboleth/etc/shibboleth/shibboleth.ini<br>
export SHIBCONFIG</span></p>
</blockquote>
- <p>If the OpenSSL libraries are not in the system's search path, they
+ <p>If the SHIBCONFIG environment variable is not specified, Shibboleth
+ will use <span class="fixed">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>
+ by default.</p>
+ <p>On Windows, the installer will set the path and SHIBCONFIG variable
+ for you in the system path, enabling Apache or IIS to be used.</li>
+ <li>If the OpenSSL libraries are not in the system's search path, they
should be added to <span class="fixed">LD_LIBRARY_PATH</span>. Generally
libtool's linker options will insure that the modules can locate the
Shibboleth libraries, but if not, you may need to add
<span class="fixed">/opt/shibboleth/lib</span> to <span class="fixed">
- LD_LIBRARY_PATH</span> as well.</p>
- <p>If the SHIBCONFIG environment variable is not specified, Shibboleth
- will use <span class="fixed">/opt/shibboleth/etc/shibboleth/shibboleth.ini</span>
- by default.</li>
+ LD_LIBRARY_PATH</span> as well.</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">
</blockquote>
<p>Sample <span class="fixed">init.d</span> scripts may be included with
future releases. Ensure that the environment variable referenced in
- <a href="#3.c.2">3.c.2</a> are in place.</li>
+ <a href="#3.c.2">3.c.2</a> are in place.</p>
+ <p>On Windows, the SHAR is a service and is managed separately.</li>
<li>By default, the Shibboleth modules are configured to log information
on behalf of Apache to the file <span class="fixed">
/opt/shibboleth/etc/shibboleth/shire.log</span>, though this can be
applications, how to filter their values based on the source, and how to
make them available to applications and the RM. See <a href="#4.e.">
section 4.e.</a> for detailed information on this file.<p><b>This
- provider has been added as of version 1.0.1, and supersedes the old
+ provider has been added as of version 1.1, and supersedes the old
<span class="fixed">aap-uri</span> and <span class="fixed">attributes</span>
settings, as well as the Apache <span class="fixed">ShibMapAttribute</span>
command.</b></dd>
for users, it is mandatory for the SHAR to authenticate when contacting an
AA, and it must therefore be given a key and an SSL client certificate. It
is permissible for the SHAR to use the same keypair and certificate used by
- the target server itself, provided the certificate is signed by a CA
- accepted by the community of sites.</p>
+ the target web server itself, provided the certificate is signed by a CA
+ accepted by the origin sites that will be queried for attributes.</p>
+ <p>On Unix, we require that OpenSSL be installed to use Shibboleth. On
+ Windows, OpenSSL libraries and the command line tool are included in the
+ package and can be used directly, if not otherwise available.</p>
<p>The certificate and key file location should be based on whether they
will also be used for Apache. If they will be used as a server certificate
as well, they should probably be in the Apache tree in the usual
Shibboleth can share, and therefore the components must generally use
separate copies of the key and certificate if they are to be shared. Most
other servers can export and/or import keys to and from PEM format or other
- formats that OpenSSL can convert.</p>
+ formats that OpenSSL can convert. Refer to your server's documentation or
+ ask for assistance from others who use it.</p>
<p>The SHAR is assigned a key and a certificate using shibboleth.ini's
<span class="fixed">certFile</span>, <span class="fixed">keyFile</span> and
<span class="fixed">keyPass</span> settings, described in <a href="#4.a.">
filtering policies for different kinds of attributes, and is potentially
extensible to more complex attributes in the future. An attribute is
considered Scoped if the XML representation of its values contains a "Scope"
- attribute. As of 1.0.1, this is detected at runtime and requires no
- configuration work.</p>
+ attribute. As of 1.1, this is detected at runtime and requires no
+ configuration in advance.</p>
<p><b>An essential part of the Shibboleth trust fabric is ensuring that
sites only assert attributes for domains for which they are considered
authoritative by the target. Typically, this means that Brown University
the origin site's permitted domains. These domains are listed in the
site metadata that provides policy information to the system. Domains
can be explicit or regular expressions, and can be changed by a target
- to meet its needs. Thus, attribute acceptance processing for
- <span class="fixed">scoped</span> attributes is based on site metadata,
- in addition to the mechanism described below for <span class="fixed">
- simple</span> attributes.</p>
+ to meet its needs. Targets can also override the rules specified for the
+ site in their own AAPs, choosing to accept additional scopes or deny
+ scopes that would ordinarily be accepted based on metadata provided by a
+ federation. Thus, attribute acceptance processing for
+ <span class="fixed">scoped</span> attributes is based on site metadata
+ and target-specified overrides in addition to the mechanism described
+ below for <span class="fixed">simple</span> attributes.</p>
+ <p>Scope rules specified in an AAP are additive with any domains
+ permitted by site metadata, and the rules are applied by first looking
+ for an applicable denial rule, and then looking at site metadata and any
+ applicable site rules for an accept rule.</p>
</blockquote>
<h4>Simple:</h4>
<blockquote>
<p>A rule that applies to the origin site AA corresponding to the
hostname.</p>
</blockquote>
+ <p><span class="fixed"><Scope Accept="true|false" Type="type"></span></p>
+ <blockquote>
+ <p>Specifies a value to accept or deny, either directly using
+ <span class="fixed">type</span> <span class="fixed">literal</span>,
+ or using a set of matching expressions as <span class="fixed">type</span>
+ <span class="fixed">regexp</span>. <span class="fixed">literal</span>
+ is the default if <span class="fixed">Type</span> is not specified.
+ Accept defaults to "true">.</p>
+ </blockquote>
<p><span class="fixed"><AnyValue></span></p>
<blockquote>
<p>Specifies a rule that always applies to the attribute and site,
<p>A knowledge base is being developed in the
<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
- are not answered by this basic guide.</p>
+ <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>
</body>
projects / shibboleth / cpp-sp.git / blobdiff