From: cantor Date: Tue, 11 May 2004 02:15:14 +0000 (+0000) Subject: Copying over latest docs. X-Git-Tag: 2.4~1780 X-Git-Url: http://www.project-moonshot.org/gitweb/?p=shibboleth%2Fsp.git;a=commitdiff_plain;h=aa5685683b6c4a0220e4909b2f6a7ee897ab8696 Copying over latest docs. git-svn-id: https://svn.middleware.georgetown.edu/cpp-sp/trunk@1098 cb58f699-b61c-0410-a6fe-9272a202ed29 --- diff --git a/doc/DEPLOY-GUIDE-TARGET.html b/doc/DEPLOY-GUIDE-TARGET.html index 1045a48..7b9c556 100644 --- a/doc/DEPLOY-GUIDE-TARGET.html +++ b/doc/DEPLOY-GUIDE-TARGET.html @@ -135,7 +135,7 @@ color: #00FF00

Shibboleth Target Deployment Guide
Shibboleth Version 1.2
-April 30, 2004
+May 10, 2004

This version of the deploy guide is for Shibboleth v1.2. For documentation related to prior versions of Shibboleth, please consult the appropriate branch in the Shibboleth CVS.

@@ -219,6 +219,7 @@ that arises.

  • Using Attributes in Applications
  • siterefresh
  • MySQL Session Cache
    • +
  • Using Lazy Sessions
  • @@ -616,7 +617,7 @@ most minor "letter" updates should be usable.

    and libsablot.so which will manifest itself as segmentation faults when starting Apache. If a site wants to use libphp4.so and Shibboleth at the same time, - then one of the following may be done: + then one of the following may be done:

    1. Remove the options --with-pspell and --with-xslt-sablot from PHP's @@ -624,7 +625,7 @@ most minor "letter" updates should be usable.

    2. Rebuild these two modules using the same version of GCC that was used to compile Shibboleth.
    -

    +
  • Apache 2.0.x
    @@ -649,13 +650,13 @@ most minor "letter" updates should be usable.

    configuration using the threads and shared options.

    • -

    Most other required libraries are either easy to update or not found - on typical systems. See the INSTALL.txt 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.

    - + +

    Most other required libraries are either easy to update or not found on + typical systems. See the INSTALL.txt 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.

    Operating System Specific Notes:

    -
    <Applications id="default" providerId="identifier" signRequest="true/false" signedResponse="true/false" signedAssertions="true/false">
    +
    <Applications id="default" providerId="identifier" signRequest="true/false" signedResponse="true/false" signedAssertions="true/false">

    The Applications element must appear once and contains default settings for requests handled by the target. It must contain at least one each of the Sessions, @@ -1215,14 +1216,14 @@ most minor "letter" updates should be usable.

    shireURL so that new sessions can be unambiguously mapped to a particular application.

    -
    <Argument>value</Argument>
    +
    <Argument>value</Argument>

    The Argument element is used in the MySQLSessionCache element to specify one or more arguments to pass to the MySQL database engine.

    -
    <saml:AttributeDesignator AttributeName="name" AttributeNamespace="namespace">
    +
    <saml:AttributeDesignator AttributeName="name" AttributeNamespace="namespace">

    The AttributeDesignator element is used in the Applications and @@ -1239,7 +1240,7 @@ most minor "letter" updates should be usable.

    it isn't possible to "remove" them and revert to none within a particular application.

    -
    <saml:Audience>value</saml:Audience>
    +
    <saml:Audience>value</saml:Audience>

    The Audience element is used in the Applications and @@ -1252,7 +1253,7 @@ most minor "letter" updates should be usable.

    desired must be specified. In most cases, this element can be omitted.

    -
    <CAPath>pathname</CAPath>
    +
    <CAPath>pathname</CAPath>

    Paired with a Path element within a FileResolver element, it allows for the specification @@ -1261,7 +1262,7 @@ most minor "letter" updates should be usable.

    chain already.

    -
    <Certificate format="type">
    +
    <Certificate format="type">

    This specifies the certificate corresponding to this set of credentials. The certificate itself must be specified by a Path element contained by this element. If the certificate @@ -1272,7 +1273,7 @@ most minor "letter" updates should be usable.

    paired with the corresponding private key using the Key element.

    -
    <Credentials xmlns="urn:mace:shibboleth:credentials:1.0">
    +
    <Credentials xmlns="urn:mace:shibboleth:credentials:1.0">

    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 @@ -1280,7 +1281,7 @@ most minor "letter" updates should be usable.

    one or more FileResolver elements.

    -
    <CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials">
    +
    <CredentialsProvider type="edu.internet2.middleware.shibboleth.common.Credentials">

    This element is the container for providers of credentials used by the target and is placed inside the ShibbolethTargetConfig element. The supplied @@ -1289,7 +1290,7 @@ most minor "letter" updates should be usable.

    to be used by the target. Other provider types might require different content.

    -
    <CredentialUse TLS="string" Signing="string">
    +
    <CredentialUse TLS="string" Signing="string">

    Used in the Applications or Application elements to specify the credentials used by @@ -1300,7 +1301,7 @@ most minor "letter" updates should be usable.

    to use for specific origins or federations.

    -
    <Errors shire="pathname" rm="pathname" access="pathname" supportContact="e-mail" logoLocation="URL"/>
    +
    <Errors shire="pathname" rm="pathname" access="pathname" supportContact="e-mail" logoLocation="URL"/>

    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. @@ -1324,7 +1325,7 @@ most minor "letter" updates should be usable.

    will insert the value of that attribute.

    -
    <Extensions>
    +
    <Extensions>
    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 @@ -1333,7 +1334,7 @@ most minor "letter" updates should be usable.

    It must contain one or more Library elements.
    -
    <FederationProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLMetadata" uri="pathname">
    +
    <FederationProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLMetadata" uri="pathname">

    This element, when specified within an Applications or Application element, points to operational metadata either @@ -1343,7 +1344,7 @@ most minor "letter" updates should be usable.

    element can be replaced within individual Application elements.

    -
    <FileResolver Id="string">
    +
    <FileResolver Id="string">

    This element defines files used to store a private key, certificate, and certificate authorities and associates the set with an identifier. Placed inside the Credentials @@ -1355,7 +1356,7 @@ most minor "letter" updates should be usable.

    Certificate element.

    -
    <Host scheme="protocol" name="fqdn" port="integer" applicationId="id" requireSession="true/false" exportAssertion="true/false">
    +
    <Host scheme="protocol" name="fqdn" port="integer" applicationId="id" requireSession="true/false" exportAssertion="true/false">

    Individual (real or virtual) hosts that this target protects are enumerated by Host elements inside the RequestMap element. If a request is processed by @@ -1387,7 +1388,7 @@ most minor "letter" updates should be usable.

    -
    <Implementation>
    +
    <Implementation>

    A container element placed inside the SHIRE element, the contents of this element will vary depending on the web server or environment that this Shibboleth deployment serves. @@ -1395,7 +1396,7 @@ most minor "letter" updates should be usable.

    ISAPI element.

    -
    <ISAPI normalizeRequest="true/false">
    +
    <ISAPI normalizeRequest="true/false">

    The configuration information for Shibboleth targets deployed on Microsoft IIS is stored inside this container element. This element must contain one or more Site elements, each of which @@ -1406,7 +1407,7 @@ most minor "letter" updates should be usable.

    Implementation element.

    -
    <Key format="type">
    +
    <Key format="type">

    Specifies a file containing a private key to be used within a set of credentials. Valid formats are PEM (the default), DER, and PKCS12. @@ -1415,7 +1416,7 @@ most minor "letter" updates should be usable.

    Path element.

    -
    <Library path="pathname" fatal="true/false"/>
    +
    <Library path="pathname" fatal="true/false"/>

    This element defines an extension library for one of Shibboleth's components and is placed within an Extensions element.

    @@ -1426,7 +1427,7 @@ most minor "letter" updates should be usable.

    -
    <Listener type="string">
    +
    <Listener type="string">

    Specifies a pluggable implementation of a mechanism for communication between the web server and SHAR, specified in the type attribute. This element is placed within the @@ -1435,7 +1436,7 @@ most minor "letter" updates should be usable.

    UnixListener elements.

    -
    <MemorySessionCache AAConnectTimeout="seconds" AATimeout="seconds" cacheTimeout="seconds" cleanupInterval="seconds" defaultLifetime="seconds" propagateErrors="true/false" retryInterval="seconds" strictValidity="true/false"/>
    +
    <MemorySessionCache AAConnectTimeout="seconds" AATimeout="seconds" cacheTimeout="seconds" cleanupInterval="seconds" defaultLifetime="seconds" propagateErrors="true/false" retryInterval="seconds" strictValidity="true/false"/>

    Shibboleth will cache sessions and received attributes in memory if this element is found in the SHAR element. This element is mutually exclusive with the @@ -1464,7 +1465,7 @@ most minor "letter" updates should be usable.

    -
    <MySQLSessionCache mysqlTimeout="seconds"/>
    +
    <MySQLSessionCache mysqlTimeout="seconds"/>

    Shibboleth will back the memory cache of sessions using an embedded MySQL database if this element is found in the SHAR element. Arguments may be passed directly to @@ -1478,7 +1479,7 @@ most minor "letter" updates should be usable.

    -
    (RequestMap) <Path name="pathname" applicationId="id" requireSession="true/false" exportAssertion="true/false">
    +
    (RequestMap) <Path name="pathname" applicationId="id" requireSession="true/false" exportAssertion="true/false">

    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 @@ -1501,21 +1502,21 @@ most minor "letter" updates should be usable.

    -
    (Credential) <Path>pathname</Path>
    +
    (Credential) <Path>pathname</Path>

    Placed inside the Key and Certificate elements to specify the pathname of the file containing the credential.

    -
    <RelyingParty name="string" TLS="string" Signing="string">
    +
    <RelyingParty name="string" TLS="string" Signing="string">

    One or more RelyingParty elements may be contained by a CredentialUse element to enumerate relying parties for which a distinct set of credentials should be used. The TLS and Signing attribute values reference the identifiers of credential resolvers defined in CredentialsProvider elements.

    -
    <RequestMap applicationId="default" requireSession="true/false" exportAssertion="true/false">
    +
    <RequestMap applicationId="default" requireSession="true/false" exportAssertion="true/false">

    The RequestMap element is a container holding Host and Path @@ -1539,7 +1540,7 @@ most minor "letter" updates should be usable.

    -
    <RequestMapProvider type="edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap" uri="pathname">
    +
    <RequestMapProvider type="edu.internet2.middleware.shibboleth.target.provider.XMLRequestMap" uri="pathname">

    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", @@ -1547,7 +1548,7 @@ most minor "letter" updates should be usable.

    the uri attribute must contain the local pathname of an XML file containing one.

    -
    <RevocationProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLRevocation" uri="pathname">
    +
    <RevocationProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLRevocation" uri="pathname">

    This element, when specified within an Applications or Application element, points to revocation information either @@ -1557,7 +1558,7 @@ most minor "letter" updates should be usable.

    element can be replaced within individual Application elements.

    -
    <SessionCache type="string">
    +
    <SessionCache type="string">

    Specifies a pluggable session cache implementation of the specified type. This element is placed within the SHAR element and is mutually exclusive with @@ -1575,7 +1576,7 @@ lifetime="seconds" timeout="seconds" checkAddress="true/false" cookieName="URL" -cookieProps="URL">

    +cookieProps="URL">

    Configuration parameters that affect the way Shibboleth handles sessions for an individual application are bundled in this element, which must be included in each Application @@ -1621,7 +1622,7 @@ cookieProps="URL">

    -
    <SHAR logger="pathname">
    +
    <SHAR logger="pathname">

    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, logger, points to a @@ -1636,7 +1637,7 @@ cookieProps="URL">

    information into a MySQL database.

    -
    <ShibbolethTargetConfig clockSkew="integer">
    +
    <ShibbolethTargetConfig clockSkew="integer">

    This is the root element for target configuration and must be present once and only once. It must always contain a SHAR element, a @@ -1650,7 +1651,7 @@ cookieProps="URL">

    -
    <SHIRE logger="pathname">
    +
    <SHIRE logger="pathname">

    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, logger, points to a @@ -1663,13 +1664,13 @@ cookieProps="URL">

    which provides fine-grained control over aspects of target behavior at a host, path, or document level.

    -
    <Site id="INSTANCE_ID" host="fqdn" scheme="http/https" port="integer">
    +
    <Site id="INSTANCE_ID" host="fqdn" scheme="http/https" port="integer">

    This element is placed in the ISAPI element to specify a mapping from individual instance ID's to the corresponding host, port, and scheme.

    -
    <TCPListener address="pathname" port="integer" acl="ip">
    +
    <TCPListener address="pathname" port="integer" acl="ip">

    This element is placed within the SHAR element and is mutually exclusive with the UnixListener and @@ -1683,7 +1684,7 @@ cookieProps="URL">

    -
    <TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLTrust" uri="pathname">
    +
    <TrustProvider type="edu.internet2.middleware.shibboleth.common.provider.XMLTrust" uri="pathname">

    This element, when specified within an Applications or Application element, points to trust metadata either @@ -1693,7 +1694,7 @@ cookieProps="URL">

    element can be replaced within individual Application elements.

    -
    <UnixListener address="pathname">
    +
    <UnixListener address="pathname">

    Use this element to specify a UNIX domain socket located at the pathname specified in the address attribute at which the SHAR should listen for requests. This element must be @@ -1859,9 +1860,9 @@ cookieProps="URL">

    are used.

    To require a session, either the Apache command, ShibRequireSession On, or the requireSession boolean XML attribute on the - RequestMap, - Host, or - Path elements in + RequestMap, + Host, or + Path elements in shibboleth.xml 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.

    As an example, the following commands will require Shibboleth authentication for a resource:

    @@ -1928,8 +1929,7 @@ cookieProps="URL"> deferring real policy to an application.

    -

    user

    -
    +
  • user

    A space-delimited list of values, such as from the urn:mace:dir:attribute-def:eduPersonPrincipalName attribute. Actually, any attribute can be mapped to REMOTE_USER, @@ -2299,11 +2299,45 @@ cookieProps="URL">

    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. - + starting the SHAR if you change this path.

    +
    • +

    4.i. Using Lazy Sessions

    +
    +

    For a background on sessions in Shibboleth, and a description of what + a lazy session is and why it would be useful, consult section + 1.g.

    +

    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 RequireSession + attribute of the Path or + Host element protecting + it is set to false. This application must be + aware of two pieces of information:

    + +

    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, target, 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: https://shireURL?target=applicationURL.

    +

    For example, if an application located at https://foo.com/portal presents a page with an option + to login, it could respond to the login button by redirecting the browser to + https://foo.com/Shibboleth.shire?target=https%3A%2F%2Ffoo.com%2Fportal.

    +
    -


    -

    5. Troubleshooting

    This section provides basic information about testing Shibboleth targets.