<li>
<p>Local time string values are now used in log files.</p>
</li>
-
- <li>
- <p>Targets may now also be run under Apache on a W2K box.</p>
- </li>
</ul>
<p>Before starting, please sign up for all applicable <a href=
modified by adding:</p>
<blockquote>
- <span class="fixedwidth">/opt/shibboleth/bin/shar &</span>
+ <span class="fixedwidth">/opt/shibboleth/bin/shar -f &</span>
</blockquote>
<p>Sample <span class="fixedwidth">init.d</span> scripts may be included with
<p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
configuration file for most Shibboleth events. This
element may also be optionally specified for each of
- the components individually. Default logging settings
- should suffice. The <span class="fixedwidth">syslog</span> daemon must
- accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
- <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
- <span class="fixedwidth">enable logging from remote machines.</span> The
- logging levels are defined in the logger
- configuration. The configuration format is similar to
- that of the <a
- href="http://jakarta.apache.org/log4j/docs/
- documentation.html">Log4j</a> package's format.</p>
+ the components individually. Default logging settings (using local log files)
+ should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
+ daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
+ <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
+ to <span class="fixedwidth">enable logging from remote machines.</span> The
+ logging level is also defined in the logger configuration.
+ The configuration format and log levels are similar to that of the
+ <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
+ property format.</p>
</dd>
<dd class="attribute">
<dd class="value">
<p>Specifies the directory in which the XML schema
files are located; defaults to
- <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>. Note that
- the <span class="fixedwidth">pathname</span> <b>must</b> have a trailing
- <span class="fixedwidth">/</span>.</p>
+ <span class="fixedwidth">/opt/shibboleth/etc/shibboleth/</span>.</p>
</dd>
<dd class="attribute">
<dd class="value">
<p>Specifies the location of the socket the SHAR uses to
- form connections.</p>
+ form connections. Note that if you change this, the SHAR and Apache
+ should both be restarted immediately, since new Apache child processes will
+ use the changed value as soon as they start up.</p>
</dd>
</dl>
<p>Specifies the URL of the WAYF service the user is
redirected to. Federations will generally provide this URL
or provide information on how to locally host WAYF's with
- a distributed hosts file. Defaults to <span
- class="fixedwidth">https://wayf.internet2.edu/InQueue/WAYF</span>.</p>
+ a distributed hosts file.</p>
</dd>
<dd class="attribute">
</dd>
<dd class="value">
- <p>Specifies the location of a <span class="fixedwidth">log4cpp</span> which
- overrides the <span class="fixedwidth">[general]</span> log parameters for
- SHIRE events. Default logging settings should
- suffice. The <span class="fixedwidth">syslog</span> daemon must accept
- <span class="fixedwidth">UDP:514</span> messages, and on Linux,
- <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
- <span class="fixedwidth">enable logging from remote machines.</span> The
- logging levels are defined in the logger
- configuration. The configuration format is similar to
- that of the <a
- href="http://jakarta.apache.org/log4j/docs/
- documentation.html">Log4j</a> package's format.</p>
+ <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
+ configuration file for most Shibboleth events. This
+ element may also be optionally specified for each of
+ the components individually. Default logging settings (using local log files)
+ should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
+ daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
+ <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
+ to <span class="fixedwidth">enable logging from remote machines.</span> The
+ logging level is also defined in the logger configuration.
+ The configuration format and log levels are similar to that of the
+ <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
+ property format.</p>
</dd>
<dd class="attributeopt">
<p>Specifies the URI of an attribute acceptance policy XML
file. Attributes must be listed in the <span
class="fixedwidth">aap-uri</span> file if they are to be
- visible. For more information, refer to section <a
- href="#4.e.">4.e</a>.</p>
+ visible to the Apache server. Unlisted or rejected attributes are
+ filtered out and hidden from the web server (but also see the
+ <b>ShibExportAssertion</b> Apache command).
+ For more information, refer to section <a href="#4.e.">4.e</a>.</p>
</dd>
<dd class="attributeopt">
</dd>
<dd class="value">
- <p>Specifies the location of a <span class="fixedwidth">log4cpp</span> which
- overrides the <span class="fixedwidth">[general]</span> log parameters for
- SHAR events. Default logging settings should suffice.
- The <span class="fixedwidth">syslog</span> daemon must accept
- <span class="fixedwidth">UDP:514</span> messages, and on Linux,
- <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span> to
- <span class="fixedwidth">enable logging from remote machines.</span> The
- logging levels are defined in the logger
- configuration. The configuration format is similar to
- that of the <a
- href="http://jakarta.apache.org/log4j/docs/
- documentation.html">Log4j</a> package's format.</p>
+ <p>Specifies the location of the <span class="fixedwidth">log4cpp</span>
+ configuration file for most Shibboleth events. This
+ element may also be optionally specified for each of
+ the components individually. Default logging settings (using local log files)
+ should suffice. If using a remote syslogd instead, the <span class="fixedwidth">syslog</span>
+ daemon must accept <span class="fixedwidth">UDP:514</span> messages, and on Linux,
+ <span class="fixedwidth">SYSLOGD_OPTIONS</span> must include <span class="fixedwidth">-r</span>
+ to <span class="fixedwidth">enable logging from remote machines.</span> The
+ logging level is also defined in the logger configuration.
+ The configuration format and log levels are similar to that of the
+ <a href="http://jakarta.apache.org/log4j/docs/documentation.html">Log4j</a> package's
+ property format.</p>
</dd>
<dd class="attributeopt">
<dd class="valueopt">
<p>Specifies the tag that defines the section of <span
class="fixedwidth">shibboleth.ini</span> the SHAR should
- use to acquire its metadata.</p>
+ use to acquire its site and trust metadata.</p>
</dd>
<dd class="attributeopt">
</dd>
<dd class="valueopt">
- <p>Specifies the location of the PEM-format
- certificate used by the SHAR to communicate with
- AA's.</p>
+ <p>Specifies the location of the PEM-format certificate used by
+ the SHAR to communicate in authenticated fashion with
+ origin site Attribute Authorities.</p>
</dd>
<dd class="attributeopt">
</dd>
<dd class="valueopt">
- <p>Specifies the location of the PEM-format private
- key used by the SHAR to communicate with AA's.</p>
+ <p>Specifies the location of the PEM-format private key used by
+ the SHAR to communicate in authenticated fashion with
+ origin site Attribute Authorities.</p>
</dd>
<dd class="attributeopt">
<dd class="valueopt">
<p>Specifies the <span class="fixedwidth">password</span> used to access the
- <span class="fixedwidth">keyfile</span>.</p>
+ <span class="fixedwidth">keyFile</span>, if any.</p>
</dd>
<dd class="attribute">
</dd>
<dd class="value">
- <p>Specifies a single file of PEM-format
- certificates containing the certificates of root CA's
- the SHAR will consider valid signers of AA
- certificates.</p>
+ <p>Specifies a single file of PEM-format certificates containing
+ the root CAs the SHAR will consider to be valid signers of AA server
+ certificates. Currently applies globally to all communication with AAs.</p>
</dd>
<dd class="attribute">
<dd class="value">
<p>Specifies the number of seconds that the SHAR will wait
- for attributes to be sent from an AA. Defaults to <span
+ for attributes to be sent from an AA. Defaults to <span
class="fixedwidth">60</span>.</p>
</dd>
<dd class="value">
<p>Specifies the number of seconds that the SHAR will wait
- for a connection to be established with a remote AA.
+ for a connection to be established with an AA.
Defaults to <span class="fixedwidth">30</span>.</p>
</dd>
<p>Specifies the method used by the SHAR to cache received
attributes. The default is <span
class="fixedwidth">memory</span>, which indicates that
- Shibboleth should store received attributes in memory.
- Another option is <span
- class="fixedwidth">mysql</span>, which will use the MySQL
- Credential Cache. The steps to using this are described
+ the SHAR should store received attributes in its memory.
+ Another option is <span class="fixedwidth">mysql</span>,
+ which will use the MySQL Credential Cache. The steps to using this are described
in the MySQL Credential Cache guide.</p>
</dd>
<dd class="value">
<p>Specifies the duration in seconds between cleanups of
- the SHAR's cached attributes. Defaults to <span
+ the SHAR's cached but expired attributes. Defaults to <span
class="fixedwidth">300</span>, or 5 minutes.</p>
</dd>
be shared or defined for each component. Two providers are
supported by Shibboleth, but additional providers may be
specified with name/value pairs consisting of <span
- class="fixedwidth"><DEFANGED_metadata provider
- type>=<source></span>.</p>
+ class="fixedwidth"><metadata provider type>=<source></span>.</p>
<p><span class="fixedwidth">[<metadata>]</span>:</p>
<dd class="value">
<p>Specifies the location of the trust database of
certificates and/or CA roots used by the SHAR during
- session initiation. The SHIRE does not need trust
+ session initiation. The SHIRE module generally does not need trust
data.</p>
</dd>
</dl>
<dd class="value">A textual description of the error intended for human
consumption.</dd>
+
+ <dd class="attribute"><span class="fixedwidth">originContactName</span></dd>
+
+ <dd class="value">The contact name for the origin site provided by that
+ site's metadata.</dd>
+
+ <dd class="attribute"><span class="fixedwidth">originContactEmail</span></dd>
+
+ <dd class="value">The contact email address for the origin site provided by that
+ site's metadata.</dd>
+
+ <dd class="attribute"><span class="fixedwidth">originErrorURL</span></dd>
+
+ <dd class="value">The URL of an error handling page for the origin site
+ provided by that site's metadata.</dd>
</dl>
<p>This configuration is only for Apache servers, and is only
used by resources protected by Shibboleth. See section <a
href= "#4.d.">4.d</a>.</p>
- <p>A sample error template is included in the Shibboleth
- distribution, and can be triggered by anything that will cause
- Shibboleth to be unable to make an authorization decision,
- including a bad sites file, certificate chain, or skewed
- clock.</p>
+ <p>Sample error templates for different kinds of errors are
+ included in the Shibboleth distribution, and can be triggered
+ by anything that will cause Shibboleth to be unable to make an
+ authorization decision, including a bad sites file, certificate chain,
+ or skewed clock.</p>
+
+ <p><b>You should edit these templates, provide or remove style sheets and
+ images, and otherwise customize these templates to suit the user experience
+ you want your users to have when errors occur.</b></p>
</blockquote>
<span class="fixedwidth">shibboleth.ini</span> file.</p>
<p>The SHAR is assigned a key and a certificate using
- shibboleth.ini's <span class="fixedwidth">certfile</span>, <span class="fixedwidth">keyfile</span> and
- <span class="fixedwidth">keypass</span>, described in <a href="#4.a.">4.a</a>. These
+ shibboleth.ini's <span class="fixedwidth">certFile</span>,
+ <span class="fixedwidth">keyFile</span> and
+ <span class="fixedwidth">keyPass</span>, described in <a href="#4.a.">4.a</a>. These
files must currently be in PEM format. OpenSSL commands to
generate a new keypair and a certificate request are shown
here, assuming RSA keys are to be used:</p>
<blockquote>
- <span class="fixedwidth">$ openssl genrsa -des3 -out ssl.key 2048 $ openssl req
- -new -key ssl.key -out ssl.csr</span>
+ <span class="fixedwidth">$ openssl genrsa -des3 -out ssl.key 2048<br>
+ $ openssl req -new -key ssl.key -out ssl.csr</span>
</blockquote>
<p>The signed certificate file returned by the CA should be
<span class="fixedwidth">openssl x509</span> command.</p>
<p>The key and certificate files can be placed anywhere,
- though in or beneath <span class="fixedwidth">/usr/local/apache/conf
- directory</span> is a good choice. The Apache child processes,
+ though in or beneath the <span class="fixedwidth">/usr/local/apache/conf</span>
+ directory is a good choice. The Apache child processes,
often running as <span class="fixedwidth">nobody</span>, must be able to read them
while the server is running, which may require permission
changes.</p>
by default. The password, if any, must be placed in the conf
file, since the module cannot prompt for it as the initial
startup of mod_ssl can. The issues surrounding how to
- securely obtain a key while running as <span class="fixedwidth">nobody</span> will
- be addressed in a later release. Since the password will be
+ securely obtain a key while running as <span class="fixedwidth">nobody</span>
+ may be addressed in a later release. Since the password will be
stored in clear text in a frequently examined file, it is
- suggested to not reuse a password used elsewhere, or to place
- the <span class="fixedwidth">keypass</span> directive in a separate file that is
- <span class="fixedwidth">Included</span> in the main configuration file, so that its
- permissions can be further restricted.</p>
+ suggested to use a password not used elsewhere.</p>
<p>Finally, the <span class="fixedwidth">calist</span> command provides the SHAR
with a set of CA roots to trust when validating AA server
certificates. In all cases, the SHAR verifies that the
- certificate's CN equals the AA's hostname, but the CA root
- bundle restricts the accepdl signers to those permitted by
- the SHAR. The parameter can be omitted to skip such signer
- validation.</p>
+ certificate's Subject CN equals the AA's hostname, but the CA root
+ bundle restricts the accepted signers to those permitted by
+ the SHAR. The parameter can be omitted to skip such validation.</p>
</blockquote>
<h4><a name="4.d."></a>4.d. Protecting Webpages</h4>
</dd>
<dd class="attribute">
- <span class="fixedwidth">ShibAuthTimeout <seconds></span>
- </dd>
-
- <dd class="value">
- <p>Sets the maximum number of seconds without any
- user activity that a session will remain alive. After
- <span class="fixedwidth">seconds</span> seconds without activity, the
- session is considered dead. Omission or <span class="fixedwidth">0</span>
- results in an arbitrary session timeout.</p>
- </dd>
-
- <dd class="attribute">
<span class="fixedwidth">ShibExportAssertion <on/off></span>
</dd>
<p>Controls whether the SAML attribute assertion
provided by the AA is exported in a base64-encoded
HTTP header, <span class="fixedwidth">Shib-Attributes</span>. Defaults to
- <span class="fixedwidth">off</span>.</p>
+ <span class="fixedwidth">off</span>. While this does require parsing the
+ raw XML, it also permits an application to see attributes that may have
+ been filtered by an AAP, or to forward the SAML assertion to a third party.</p>
</dd>
<dd class="attribute">
</dd>
<dd class="attribute">
+ <span class="fixedwidth">ShibAuthTimeout <seconds></span>
+ </dd>
+
+ <dd class="value">
+ <p>Sets the maximum number of seconds without any
+ user activity that a session will remain alive. After
+ <span class="fixedwidth">seconds</span> seconds without activity, the
+ session is considered dead. Omission or <span class="fixedwidth">0</span>
+ results in an arbitrary session timeout.</p>
+ </dd>
+
+ <dd class="attribute">
<span class="fixedwidth">AuthGroupFile <pathname></span>
</dd>
</dd>
<dd class="value">
- <p>Enforce authorization using one of the following methods.
- <b>Please note that <span
- class="fixedwidth">valid-user</span> is not a valid access
- rule because there it is not clear what <span
- class="fixedwidth">valid-user</span> would signify in the
- context of Shibboleth</b>.</p>
+ <p>Enforce authorization using one of the following methods.</p>
<ul type="circle">
- <li>
<li>
<span class="fixedwidth">valid-user</span>
<blockquote>
- <p>Any Shibboleth user from a trusted origin site
- is accepted.</p>
+ <p>Any Shibboleth user from a trusted origin site is accepted,
+ even if no actual attributes are received. This is a very minimal
+ kind of policy, but is useful for testing or for deferring real
+ policy to an application.</p>
</blockquote>
</li>
<span class="fixedwidth">user</span>
<blockquote>
- <p>A space-delimited list of EPPN values,
- provided that the
- <span class="fixedwidth">urn:mace:eduPerson:1.0:eduPersonPrincipalName</span>
+ <p>A space-delimited list of EPPN values, provided that the
+ <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
attribute has been mapped to the
<span class="fixedwidth">REMOTE_USER</span> header (as per the earlier
- example configuration commands).</p>
+ example configuration commands). Actually, any attribute can be mapped to
+ REMOTE_USER, even if this doesn't always make sense.</p>
</blockquote>
</li>
<blockquote>
<p>A space-delimited list of group names defined
within <span class="fixedwidth">AuthGroupFile</span> files, again
- provided that the mapping to <span class="fixedwidth">REMOTE_USER</span>
+ provided that a mapping to <span class="fixedwidth">REMOTE_USER</span>
exists.</p>
</blockquote>
</li>
<blockquote>
<p>An arbitrary rule tag that matches an alias
defined in a <span class="fixedwidth">ShibMapAttribute</span> server
- command. The rule value is a space- delimited
+ command. The rule value is a space-delimited
list of attribute values, whose format depends on
the attribute in question (e.g. an affiliation
rule might look like <span class="fixedwidth">require affiliation
will not be passed to the CGI environment or used when
enforcing <span class="fixedwidth">.htaccess</span> rules.
Note that the attribute assertion exported to the
- <span class="fixedwidth">Shib-Attributes</span> header is pre-filtered.</p>
+ <span class="fixedwidth">Shib-Attributes</span> header is unfiltered.</p>
- <p>The Shibboleth distribution <span class="fixedwidth">scoped</span> and
+ <p>The Shibboleth distribution supports <span class="fixedwidth">scoped</span> and
<span class="fixedwidth">simple</span> filtering policies for different kinds of
attributes.</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
+ considered authoritative by the target. Typically, this means
that Brown University will be trusted to assert attributes only
- scoped to <span class="fixedwidth">*brown.edu</span>. Unless
+ scoped to <span class="fixedwidth">brown.edu</span>. Unless
there are very specific circumstances requiring this restriction
- be removed, it is strongly encouraged that it be included in any
- and all AAP's.</b></p>
+ be removed, it is strongly encouraged that such policies be in place.</b></p>
<h4>Scoped:</h4>
<blockquote>
regular expressions, and can be changed by a target to meet
its needs if a local version of the file is created. Thus,
attribute acceptance processing for <span class="fixedwidth">scoped</span>
- attributes is based on the sites file.</p>
+ attributes is based on the sites file, in addition to the mechanism described
+ below for <span class="fixedwidth">simple</span> attributes.</p>
</blockquote>
<h4>Simple:</h4>
Multiple values are permitted.
<span class="fixedwidth">eduPersonEntitlement</span>, in which the values are URIs,
is one example of a simple attribute.</p>
- <p>In this release, simple attribute acceptance is
+ <p>In this release, simple (and scoped) attribute acceptance is
controlled with an external policy file written in XML. The
schema for the file is described by the
- <span class="fixedwidth">eduPerson.xsd</span> schema, and an example file is
+ <span class="fixedwidth">shibboleth.xsd</span> schema, and an example file is
included, <span class="fixedwidth">AAP.xml</span>. If the <span class="fixedwidth">aap-uri</span>
parameter in the <span class="fixedwidth">shibboleth.ini</span> file is left out,
then no policy is applied, and no filtering is done.
URI"></span></p>
<blockquote>Specifies a rule for an attribute, named with
its URI.</blockquote>
+
<p><span class="fixedwidth"><AnySite></span></p>
<blockquote>Specifies a rule that always applies to the
attribute, regardless of the asserting AA.</blockquote>
<blockquote>A rule that applies to the origin site AA
corresponding to the domain name.</blockquote>
+ <p><span class="fixedwidth"><AnyValue></span></p>
+ <blockquote>Specifies a rule that always applies to the
+ attribute and site, regardless of the value(s).</blockquote>
+
<p><span class="fixedwidth"><Value Type="type"></span></p>
<blockquote>Specifies a value to permit, either directly
using <span class="fixedwidth">type</span> <span class="fixedwidth">literal</span>, or using a set of
<p>Note that the AAP rules described in this section are not
part of the Shibboleth architecture and are simply one
- possible set of approaches implemented in the
- <span class="fixedwidth">eduPerson</span> attribute plugin. The OpenSAML API permits
- attribute classes to derive from <span class="fixedwidth">SAMLAttribute</span> and
- override the accept() method to implement
- application-specific AAP requirements. The eduPerson source
- files can be used as an example of how to build highly
- customized rules.</p>
+ possible set of approaches provided by this implementation.</p>
</blockquote>
<h4><a name="4.f."></a>4.f. Using Attributes in
<span class="fixedwidth">username</span>. Unlike many authentication modules,
Shibboleth does not guarantee that <span class="fixedwidth">REMOTE_USER</span> will
have any value. If it does, it is set solely based on a
- <span class="fixedwidth">ShibMapAttribute</span> command. For most purposes, the
- <span class="fixedwidth">urn:mace:eduPerson:1.0:eduPersonPrincipalName</span>
+ <span class="fixedwidth">ShibMapAttribute</span> command. For many purposes, the
+ <span class="fixedwidth">urn:mace:dir:attribute-def:eduPersonPrincipalName</span>
attribute should be mapped to <span class="fixedwidth">REMOTE_USER</span>. Even so,
EPPN may not be provided by the AA, and <span class="fixedwidth">REMOTE_USER</span>
might still be empty.</p>
+
+ <p>The <span class="fixedwidth">Shib-Origin-Site</span> variable will contain the
+ unique name/identifier of the origin site of the user. Some applications may use this
+ to lookup additional policy or application data. It normally takes the form of a URI
+ but could be any string.</p>
<p>Finally, the <span class="fixedwidth">ShibExportAssertion</span> flag instructs
the module to place the entire XML message containing the
class="fixedwidth">siterefresh</span> would take the form:</p>
<blockquote><span class="fixedwidth">
- /opt/shibboleth/bin/siterefresh --url
- http://wayf.internet2.edu/InQueue/sites.xml --out sites.xml
- --cert internet2.pem
+ /opt/shibboleth/bin/siterefresh --out sites.xml --cert internet2.pem \<br>
+ --url http://wayf.internet2.edu/InQueue/sites.xml
</span></blockquote>
- <p>It is recommended that a similar command be added to a <span
- class="fixedwidth">crontab</span> to keep the file refreshed.</p>
+ <p>It is recommended that similar commands be added to a <span
+ class="fixedwidth">crontab</span> to keep the sites and trust files refreshed.</p>
</blockquote>
projects / java-idp.git / commitdiff