From d7c19a8101c2ea2d73165e2b9c31ff625257acf5 Mon Sep 17 00:00:00 2001 From: ndk Date: Mon, 26 Apr 2004 16:40:59 +0000 Subject: [PATCH] Hopefully nearly final for 1.2; many fixes, corrections, and compliance changes. One compliance problem I can't fix. git-svn-id: https://subversion.switch.ch/svn/shibboleth/java-idp/trunk@1011 ab3bd59b-922f-494d-bb5f-6f0a3c29deca --- doc/DEPLOY-GUIDE-ORIGIN.html | 178 ++++++++++++++++++++++-------------------- 1 file changed, 92 insertions(+), 86 deletions(-) diff --git a/doc/DEPLOY-GUIDE-ORIGIN.html b/doc/DEPLOY-GUIDE-ORIGIN.html index 96b802d..125d0f8 100644 --- a/doc/DEPLOY-GUIDE-ORIGIN.html +++ b/doc/DEPLOY-GUIDE-ORIGIN.html @@ -378,59 +378,60 @@ requesting attributes.

1.e. Relying Parties and Applications

-

A Shibboleth relying party represents a target or set of targets that - operate under one trust agreement and share common key, certificate, and - certificate authority guidelines. This could include any number of - individual SHAR's and applications. Frequently, an entire federation will - be viewed by an origin or target as a single relying party; however, there - is no necessary binding between these. An individual site with which an - origin or target exchanges information may sometimes be part of multiple - relying parties if there are multiple trust agreements under which these - transactions are performed.

+

A Shibboleth relying party allows a deployment to select a particular + configuration to use when processing a request. Certificates, policies, and + other aspects of an interaction are specified on a relying party basis, and + may or may not vary between relying parties depending on the deployment's + needs. Each relying party may support a number of different + applications.

+

Frequently, an entire federation will be viewed by an origin or target as + a single relying party; however, there is no necessary binding between + these. An individual origin or target with which this deployment exchanges + information may sometimes be part of multiple relying parties if there are + multiple trust agreements under which these transactions are performed.

Applications as viewed from Shibboleth are not necessarily defined by the same metrics as in other contexts. An individual application represents a service or set of services that operates using the same attribute and trust - features and shares common Shibboleth sessions. - Attributes are released to targets on the basis of individual applications - within the context of its containing relying party. An application may span - multiple URL trees, servers, or SHAR's, depending on the architecture of the - service. However, every application must be contained within a single - relying party; applications cannot span relying parties. Each application - is assigned an individual application identifier URN which must be - recognized by both the origin and the target.

+ features and shares common Shibboleth sessions. + Attributes are released to targets on the basis of individual applications, + while other transactional details such as certificates and timeouts will be + specified by relying party. An application may span multiple URL trees and + servers depending on the architecture of the service. Each application is + assigned an individual application identifier URN which must be recognized + by both the origin and the target. In any individual request, both the + relying party and application are consulted to acquire a complete set of + configuration to ensure proper release.

1.f. Sessions

There are many different types of sessions that can be established within - the context of the access of a Shibboleth-protected resource. It is - important to note that these are all independent and distinct: any session - can exist with or without any other session, and the expiration of any one - session does not imply the expiration of any other session. Shibboleth does - not support any logout functionality.

+ the context of the access of Shibboleth-protected webspace. This webspace + is subdivided by the target into individual applications, each of which maintains separate sessions + with the user's browser using cookies. However, the HS never interacts with + these applications; it views the webspace partitioned by providerId. It is + important to note that all sessions in this section are all independent and + distinct: any session can exist with or without any other session, and the + expiration of any one session does not imply the expiration of any other + session. Shibboleth does not support any logout functionality beyond the + termination of individual application sessions by deletion of respective + cookies; there is no way for the target to cause origin-side sessions, such + as a user's SSO login, to expire.

The successful access of a Shibboleth-protected resource by a browser - user may have two outcomes. The standard session establishment mechanism in - which Shibboleth protects the resource in all circumstances results in the - establishment of two sessions. Shibboleth 1.2 also supports so-called lazy - session establishment, in which the resource may be accessed without first - providing a home institution or obtaining attributes. This means the - application must be intelligent enough to determine whether an attribute - request or any other aspect of Shibboleth functionality is necessary, and - then construct proper URL's to initiate these flows; if the application - determines none is necessary or uses other authorization mechanisms, then an - attribute request does not need to be triggered. This complex functionality - is mostly useful to protect a single URL with different access mechanisms, - or to require attribute requests only in the instance where the application - deems it necessary.

-

In either situation, before the resource is presented, a Shibboleth - session is established between the browser and the Shibboleth module, - represented by a cookie. A separate session for the attribute release - interaction with the origin results in the caching of a set of attributes - pertaining to that browser user. The expiration of either session implies - the need to re-initiate only that session and does not imply the - re-initiation of the other; for example, although a browser user's - Shibboleth session has expired, if there is a valid set of cached - attributes, there need not be another attribute query when they next access - this resource.

+ user may have two outcomes: standard session establishment, and lazy session + establishment. The standard session establishment mechanism in which + Shibboleth protects the resource in all circumstances results in the + establishment of a cookie-based browser session and a set of attributes + cached for that application. Shibboleth 1.2 also supports so-called lazy + session establishment, in which the resource may be accessed without prior + authentication. This means the application must be intelligent enough to + determine whether authentication necessary, and then construct proper URL's + to initiate the browser redirect to request authentication; if the + application determines none is necessary or uses other authorization + mechanisms, then an attribute request does not need to be triggered. This + complex functionality is mostly useful to protect a single URL with + different access mechanisms, or to require attribute requests only in the + instance where the application deems it necessary.

Independently of this, a web-based application protected by Shibboleth may have a need to establish its own session with the user. This session may persist well beyond either Shibboleth session, and logouts from this @@ -469,16 +470,13 @@ requirements for a successful implementation of a Shibboleth origin.

relationships. Each federation will have a different application process. When an origin is accepted into a federation, its information is added to the sites file used by the WAYF and target sites.

-

It may be necessary to join multiple federations depending on the - sites with whom you wish to exchange attributes and the terms under which - these interactions will take place. An origin site exists within the context - of a single federation, while a single target may accept assertions issued - by multiple federations if they are all recognized by the SHAR.

-

Attribute release and acceptance policies, the use and caching of - attributes, and definition of commonly traded attributes are examples of - specifications a federation may make. For more information on federations, - please refer to the Deployer's Guide to Federations and the Shibboleth v1.0 - architectural document.

+

Attribute release and acceptance policies, the use and caching of + attributes, and definition of commonly traded attributes are examples of + specifications a federation may make. The default configuration that + ships with Shibboleth is intended for use in testing against a localhost target. In order to interoperate with other + relying parties, such as a federation, consult the steps provided by the + guidelines of that relying party.

2.c. Security Considerations

@@ -727,23 +725,28 @@ and JSP specification 1.2.

4. Getting Running

4.a. Basic Configuration

-

This section of the deploy guide describes only the default This section of the deploy guide describes only the default origin.xml file and enumerates the essential changes that need to be made to the configuration defaults for the origin to function successfully in a federated environment. More complex configuration will likely be required for many applications and federations; for a fully defined example origin.xml and definition of every element and attribute that may be used, please refer to section 5.a.

-

The main configuration file for Shibboleth's origin side is located in - /webapps/shibboleth/WEB-INF/classes/conf/origin.xml. - The configuration must be consistent with values elsewhere in the - deployment, such as the HS' certificate and with - directory access bindings, etc., or access errors may occur.

-

All pathnames are relative, and have an effective root path of - $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/. - To specify files outside of the webapp, specify a full URI, such as - file:///usr/local/shibboleth/.

+ href="#5.a.">section 5.a.

+

The default configuration that ships with Shibboleth is intended for + use in testing against a localhost target. In + order to interoperate with other relying parties, such as a federation, + consult the steps provided by the guidelines of that relying party.

+

The main configuration file for Shibboleth's origin side is located + in /webapps/shibboleth/WEB-INF/classes/conf/origin.xml. + The configuration must be consistent with values elsewhere in the + deployment, such as the HS' certificate and with + directory access bindings, etc., or access errors may occur. All pathnames + are relative, and have an effective root path of $TOMCAT_HOME/webapps/shibboleth/WEB-INF/classes/. To + specify files outside of the webapp, specify a full URI, such as file:///usr/local/shibboleth/.

The following is a hyperlinked version of the basic configuration file, followed by a list of elements and attributes that must be modified. Click on any attribute or element for more information on its population and @@ -819,15 +822,15 @@ origin will interoperate in a federation.

authenticate the requesting SHAR.

-
  • providerID=URN +
  • providerID=URI
    -

    This will be the URN assigned to this origin by the +

    This will be the URI assigned to this origin by the federation.

    • -
  • defaultRelyingParty=URN +
  • defaultRelyingParty=URI
    -

    This is the URN of the primary federation that the origin +

    This is the URI of the primary federation that the origin operates within.

    • @@ -1033,11 +1036,15 @@ configuration

    The Shibboleth origin leverages metadata distributed by relying parties and federations to validate the identity of requesters and the resource providers on whose behalf the request is being made. This metadata is cached locally in the form of sites.xml files. Shibboleth includes a simple utility called metadatatool which can be used to refresh a sites.xml file. These files are then pointed to by FederationProvider elements in shibboleth.xml.

    The following command is appropriate for most deployments and is run from the $SHIB_HOME directory. This should be frequently run by adding it to a crontab to ensure that the data is fresh.

    -
    bin/metadatatool -i https://wayf.internet2.edu/InQueue/sites.xml -k conf/internet2.jks -p shib123 -a sitesigner -o /your_path_here/sites.xml
    + +
    bin/metadatatool -i https://wayf.internet2.edu/InQueue/sites.xml -k conf/internet2.jks -p shib123 -a sitesigner -o /your_path_here/sites.xml
    +

    This is a list of all the command-line parameters that may be specified:

    -
    when signing: -i <uri> -s -k <keystore> -a <alias> -p <pass> [-o + +
    when signing:    -i <uri> -s -k <keystore> -a <alias> -p <pass> [-o <outfile>]
    -when updating: -i <uri> [-k <keystore> -a <alias> OR -N ] [-o <outfile>]
    +when updating:  -i <uri> [-k <keystore> -a <alias> OR -N ] [-o <outfile>]
    + @@ -1219,7 +1226,7 @@ when updating: -i <uri> [-k <keystore> -a <alias> OR -N ] [-o href="#confPath">CAPath elements. Valid encodings are PEM and DER. It resides within the FileResolver element + href="#confFileResolver">FileResolver element and must be paired with the corresponding private key using the Key element. @@ -1227,8 +1234,7 @@ when updating: -i <uri> [-k <keystore> -a <alias> OR -N ] [-o
    This element is the container for credentials used by the credential mechanism specified by the ShibbolethOriginConfig element. For most - deployments, the URN should be . It must + class="fixed">ShibbolethOriginConfig element. It must contain one FileResolver element for flat key and certificate files or one Logging element.
    -
    <FederationProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadataLoadWrapper" uri="pathname"/>
    +
    <FederationProvider type="edu.internet2.middleware.shibboleth.metadata.provider.XMLMetadataLoadWrapper" uri="pathname"/>
    Individual sets of targets in the form of a sites.xml file that this origin will trust to make requests may be specified by adding PEM and DER. Keys are supported in a variety of formats: DER, PEM, encrypted PEM, PKCS8, and encrypted PKCS8. It resides within the FileResolver + href="#confFileResolver">FileResolver element, should be paired with a Certificate element, and contain a Path element.
    @@ -1415,19 +1421,19 @@ shared in-memory repository. -
    <Path>pathname</Path>
    +
    <Path>pathname</Path>
    This mandatory element specifies the path to a file or directory utilized by other elements of the configuration. It may be contained by various elements to point to different types of files required by the origin.
    -
    <ReleasePolicyEngine>
    +
    <ReleasePolicyEngine>
    The ReleasePolicyEngine element is used to specify a class of release policy processing. This should contain one ArpRepository element.
    -
    <RelyingParty name="URN"
    +
    <RelyingParty name="URI"
    AAsigningCredential="string"
    AAUrl="URL"
    defaultAuthMethod="URN"
    @@ -1469,15 +1475,15 @@ signingCredential="string">
    class="fixed">FederationProvider elements to determine whether the target is a member of a common federation. If there is a RelyingParty element that has the same - providerId as the URN of the the federation, it is used. If not, the + providerId as the URI of the the federation, it is used. If not, the default relying party handles the request.
    • name: Each RelyingParty element is differentiated by a URN + class="fixed">RelyingParty element is differentiated by a URI specified in the name attribute. A target will send a value for this attribute with the attribute request; if - the URN sent matches the name, this element + the URI sent matches the name, this element will be used in the transaction. If there is no direct match, the origin uses metadata to try to find a federation that the service provider is a member of.
      • @@ -1555,7 +1561,7 @@ xmlns:name="urn:mace:shibboleth:namemapper:1.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="urn:mace:shibboleth:origin:1.0 origin.xml"
      defaultRelyingParty="URI"
      -providerID="URN"
      +providerID="URI"
      AAUrl="URL"
      authHeaderName="string"
      defaultAuthMethod="URN"
      @@ -1564,7 +1570,7 @@ passThruErrors="true/false"
      resolverConfig="pathname">

      This is the primary element that defines an origin.xml file and is the container for every other element and must appear once and only once. For most deployments, all the xmlns attributes, which specify the handlers for different aspects of origin operation, should remain unchanged. The mandatory attributes must be changed before operating the origin.

        -
      • defaultRelyingParty: This specifies the relying party to use for a request when no RelyingParty element's name attribute matches the policy URN of an incoming request. Typically, this will be populated with the URN of a federation.
        • +
      • defaultRelyingParty: This specifies the relying party to use for a request when no RelyingParty element's name attribute matches the policy URI of an incoming request. Typically, this will be populated with the URI of a federation.
      • providerID: The origin uses this unique name to identify assertions it issues. This will usually be assigned by a federation.
      • AAUrl specifies the URL where the AA for this HS resides, which must be consistent with how it is defined in Tomcat. Note that this must be an https:// URL in order for the AA to know which SHAR is requesting attributes for ARP purposes.
      • authHeaderName: If authentication methods are passed to the HS using an HTTP header variable other than the default, SAMLAuthenticationMethod, the name of the variable may be specified here.
        • -- 1.7.10.4
    -i,--ininput file or url
    -k,--keystorepathname of Java keystore file