From edf8ce553990d2254aa321cad13d6363ac79e099 Mon Sep 17 00:00:00 2001 From: ndk Date: Mon, 3 May 2004 03:04:04 +0000 Subject: [PATCH] Great suggestions from Steven and Walter. git-svn-id: https://subversion.switch.ch/svn/shibboleth/java-idp/trunk@1045 ab3bd59b-922f-494d-bb5f-6f0a3c29deca --- doc/DEPLOY-GUIDE-ORIGIN.html | 201 ++++++++++++++++++++++++++---------------- 1 file changed, 124 insertions(+), 77 deletions(-) diff --git a/doc/DEPLOY-GUIDE-ORIGIN.html b/doc/DEPLOY-GUIDE-ORIGIN.html index b0e71f7..beef0d8 100644 --- a/doc/DEPLOY-GUIDE-ORIGIN.html +++ b/doc/DEPLOY-GUIDE-ORIGIN.html @@ -158,9 +158,8 @@ and resources for deployment assistance can be found here.

shibboleth-users@internet2.edu. This should include, but not be limited to, questions about the documentation, undocumented problems, installation or operational issues, and anything else -that arises. Please ensure that you have the -appropriate -.tarball for your operating system.

+that arises. If you have not already obtained it, please +download the Shibboleth origin tarball.


@@ -467,7 +466,7 @@ requirements for a successful implementation of a Shibboleth origin.

2.a. Requirements

2.b. Join a Federation

@@ -537,7 +539,7 @@ requirements for a successful implementation of a Shibboleth origin.

2.d. Server Certs

-

In the Shibboleth architecture, the SHIRE, SHAR, HS, and AA must all have +

In the Shibboleth architecture, the origin and target must each have various client and/or server certificates for use in signing assertions and creating SSL channels. These should be issued by a commonly accepted CA, which may be stipulated by some Federation rules. Different federations may @@ -550,21 +552,22 @@ requirements for a successful implementation of a Shibboleth origin.

Shibboleth target sites. When a user attempts to access a Shibboleth-protected resource, that resource's SHAR queries the user's AA for all attributes to which it is entitled. The SHAR provides its own name - and the URL of the resource on behalf of which it is making the request. The + and the URI of the requesting application. The AA finds the attributes associated with the browser user, determines an "Effective ARP" for this user, and then sends to the SHAR only the - attributes/values allowed in this policy.

+ attribute-value pairs allowed in this policy.

An ARP may be thought of as a sort of filter for outbound attributes; it cannot create attributes or data that aren't originally present, but it can limit the attributes released and the values those attributes may have when released. It does not change the information in the data sources in any way.

-

Each ARP is comprised of one or more rules that specify which attributes - and values may be released to a target or set of targets. The assignment of - rules to various targets is quite flexible and includes mechanisms for - specifying: that a rule should affect all targets (default rule), exact SHAR - names for which a rule is applicable, regular expressions against which SHAR - names should be matched to determine if a rule is applicable, URL trees for - which a rule is applicable.

+

Each ARP is comprised of one or more rules that specify which attributes + and values may be released to a given application and that SHAR. The + assignment of rules to various targets is quite flexible and includes + mechanisms for specifying: that a rule should affect all targets (default + rule), exact SHAR names for which a rule is applicable, regular expressions + against which SHAR names should be matched to determine if a rule is + applicable, and individual applications that may span hosts and URL's as + necessary.

For each request, an Effective ARP is determined by locating all ARP's applicable to the designated user and extracting each rule that matches the querying SHAR and resource. Attributes and values that are specified for @@ -579,11 +582,13 @@ requirements for a successful implementation of a Shibboleth origin.

2.f. Designate Contacts

-

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.

+

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. These contacts are then supplied to + the federation and optionally to relying parties individually to facilitate + communications and troubleshooting.

2.g. Browser Requirements

@@ -595,7 +600,7 @@ requirements for a successful implementation of a Shibboleth origin.

2.h. Clocks

-

NTP should be run on all +

NTP should be run on all web servers. Shibboleth employs a short handle issuance time to protect against replay attacks. Because of this, any significant degree of clock skew can hinder the ability of users to access sites successfully.

@@ -650,12 +655,13 @@ and JSP specification 1.2.

users and supply their identity to the Handle Server.

-
  • An enterprise directory service +
  • An enterprise attribute store
    -

    Shibboleth currently supports retrieving user attribute - information from an LDAP - directory. For testing purposes, Shibboleth also supports a minimal - echo responder which will always return pre-defined attributes.

    +

    Shibboleth currently supports retrieving user attribute + information from an LDAP + directory or a SQL database. For testing purposes, Shibboleth also + supports a minimal echo responder which will always return + pre-defined attributes.

    • @@ -708,6 +714,7 @@ and JSP specification 1.2.


    --------- end ---------

    + This will result in a HS URL of http://hostname/shibboleth/HS/.
  • Tomcat's /conf/server.xml ships by default with the Coyote/JK2 connector enabled, which fails with @@ -733,6 +740,12 @@ and JSP specification 1.2.


    </Location>

    • +
  • The origin's default configuration is designed to be tested against + a target located on localhost, eliminating + the need to join InQueue before being able to test an installation. It + is recommended that the origin be tested now by constructing accessing a + carefully formed URL using any web-browser and verifying that everything + is functioning properly.


    • @@ -766,8 +779,9 @@ and JSP specification 1.2.

    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 + followed by a list of elements and attributes that must be modified as a + first step to interoperation with production targets. Click on any + attribute or element for more information on its population and definition.

    @@ -779,7 +793,7 @@ and JSP specification 1.2.

       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.xsd"
    -   AAUrl="http://therock.cc.columbia.edu:6666/shibboleth/AA"
    +   AAUrl="http://example.edu/shibboleth/AA"
       defaultRelyingParty="urn:mace:inqueue"
       providerId="urn:mace:inqueue:shibdev.edu">

    @@ -905,9 +919,11 @@ configuration eduPersonPrincipalName.

    2. The comment indicators should be removed from around the definitions of those two elements ( <!-- and --> ).

    +

    The default configuration of the attribute resolver utilizes the sample + echo responder, which always responds with fixed, dummy values. The AA must + be configured to use LDAP or SQL, depending on your primary attribute + store.

    -


    -

    4.b. Key Generation and Certificate Installation

    The SAML messages generated by the HS must be digitally signed, which @@ -1095,7 +1111,15 @@ when updating:  -i <uri> [-k <keystore> -a <alias> O cross-references in the definitions and the examples presented in section 4.a, below, and through the examples - in CVS. The following is an example .

    +

    The AAUrl, + defaultRelyingParty, and providerId attributes of the ShibbolethOriginConfig element provide default values that + will be used either when interacting with a target version 1.1 or lower or + when not overridden by attributes on a RelyingParty element matching this request.

    +

    The following is an example origin.xml file which contains all possible configuration parameters and values. The configuration must be consistent with values elsewhere in the deployment or access errors may occur. For a @@ -1112,7 +1136,7 @@ when updating:  -i <uri> [-k <keystore> -a <alias> O     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.xsd"
    -    AAUrl="http://therock.cc.columbia.edu:6666/shibboleth/AA"
    +    AAUrl="http://example.edu/shibboleth/AA"
        defaultRelyingParty="urn:mace:inqueue"
        providerId="urn:mace:inqueue:shibdev.edu">

    @@ -1356,7 +1380,7 @@ when updating:  -i <uri> [-k <keystore> -a <alias> O

    <KeyStoreResolver Id="string" storeType="type">
    This element is contained by the Credentials - element and to specify a keystore that contains both the certificate and + element to specify a keystore that contains both the certificate and private key for a given set of credentials. Typically, this will be a Java keystore, with a corresponding type of JKS.
  • id is used by HSNameFormat elements to refer to this element and must be unique.
    • -
  • type dictates how handles are passed to the AA. +
  • type dictates how subject names such as handles are passed internally from the HS to the AA. The valid types are:
    • CryptoHandleGenerator: Shibboleth handles will be passed using symmetric encryption. If this is specified, keystore information @@ -1471,8 +1495,8 @@ signingCredential="string">
    • href="#confHSNameMapping">HSNameMapping element to specify a naming mechanism for assertions sent to this relying party. The HS and AA both perform validation against federation - metadata to ensure that targets cannot construct requests that cause - another target's relying party information to be used.

    + metadata to ensure that targets cannot construct requests that would be + used to impersonate another target or other malicious behavior.

    The proper RelyingParty element to handle a given attribute request is selected by the following algorithm. If at any point a match is found, processing is complete; only one relying @@ -1488,13 +1512,13 @@ signingCredential="string"> class="fixed">providerId attribute matches the name sent by the target, then that element is used.

  • A metadata lookup is performed using the sites.xml files supplied by sites.xml files supplied by all 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 URI of the the federation, it is used. If not, the - default relying party handles the request.
    • + name as the URI of the the federation, it + is used. If not, the default relying party handles the request. @@ -1631,10 +1668,11 @@ resolverConfig="pathname">

    5.b. ARP Overview

    -
    This section applies primarily to the syntactic and technical details of - ARP's. For basic information on and explanation of what an ARP is and how it - should be managed, please refer to sections 2.e and - 4.d.
    +
    This section applies primarily to the syntactic and technical details of + ARP's as defined by the standard, file-based repository implementation. + For basic information on and explanation of what an ARP is and how it should + be managed, please refer to sections 2.e and 4.d.

    Every ARP file contains one ARP. ARP's may be specified either as the site ARP or user ARP's. The site ARP pertains to every principal for whom the AA retrieves information; a user ARP applies only to the individual user @@ -1646,14 +1684,14 @@ resolverConfig="pathname"> principal.

    Each ARP acts as a container that holds a set of ARP rules that are applicable to the principals that ARP is effective for. Each ARP rule - specifies a single release policy within the ARP container pertaining to a - particular target application. For 1.2 targets, this is a single URI - matching a providerId. Prior to 1.2, URI's for - targets were not registered; this means that the SHAR name must be used in - release policies for 1.1 targets accessed by users from this origin. Each - ARP rule may contain specifications regarding the release of any number of - attribute values to requests matching that ARP rule for that user. ARP rules - may be flagged as default, implying that they are always applied to any user + specifies a single release policy pertaining to a particular target + application. For 1.2 targets, this is a single URI matching a providerId. Prior to 1.2, URI's for targets were not + registered; this means that the SHAR name must be used in release policies + for 1.1 targets accessed by users from this origin. Each ARP rule may + contain specifications regarding the release of any number of attribute + values to requests matching that ARP rule for that user. ARP rules may be + flagged as default, implying that they are always applied to any user matched by the ARP container. Note that ARP's may also be used to restrict specific attribute/value pairs in addition to restricting or releasing individual attributes.

    @@ -1667,7 +1705,7 @@ resolverConfig="pathname">

    5.b.i. ARP Processing

    -

    When a request arrives from a particular relying party, the applicable set of +

    When a request arrives from a particular application, the applicable set of ARP rules are parsed into an effective ARP. This parsing is done as follows:

      @@ -1868,6 +1906,12 @@ resolverConfig="pathname">

      5.c. Sharing certificate/key pairs between Apache and Java keystores (optional)

      +

      Credentials stored in PEM and DER files, as is standard for Apache, are +supported by Shibboleth 1.2 and later. In most deployments, it will be easiest +to simply reference those using a FileResolver element. The information in this chapter +is still relevant if there is a need to share keys between PEM/DER flatfiles and +a Java keystore.

      The JDK includes the command line program keytool for managing Java keystores. This utility cannot import @@ -2010,10 +2054,10 @@ Java keystores (optional)

      Shibboleth provides a powerful attribute resolver that allows origins to quickly configure the retrieval of simple attributes from standard types of - attribute stores. The resolver is configured using an xml file wich should + attribute stores. The resolver is configured using an xml file which should be pointed to with the edu.internet2.middleware.shibboleth.aa. - attrresolv.AttributeResolver.ResolverConfig propety in + attrresolv.AttributeResolver.ResolverConfig property in origin.xml as described in section 4.a. For more complex attributes or those that require processing before release, customized Java classes will need to be written. @@ -2021,7 +2065,7 @@ Java keystores (optional)

      The resolver is essentially a directed graph from attribute definitions to data connectors. The data connectors pull data, in the form of attributes, from external data sources. The attribute definitions then - process this data into a from suitable for use by Shibboleth. This procedure + process this data into a form suitable for use by Shibboleth. This procedure can be as simple as taking an unmodified string value from a data connector and tagging it with a name or can include arbitrarily complex business rules.

      @@ -2033,7 +2077,7 @@ Java keystores (optional) depends. Each data connector consists of a string identifier which is used by attribute definitions that refer to it, and one or more elements specific to the configuration of that data connector.

      -

      Shibboleth comes with two attribute definitions provided in version 1.2: +

      Version 1.2 of Shibboleth comes with two attribute definitions: the SimpleAttributeDefinition, which acts as a basic proxy for attributes supplied by data connectors with some name conversion and attribute scoping added, and a @@ -2065,8 +2109,8 @@ Java keystores (optional) an LDAP directory.

      <Search>
      An element of the element - JNDIDirectoryDataConnector. This element defines the DN filter - used to perform the LDAP search. The search string must return no more + JNDIDirectoryDataConnector. This element defines the search filter + used to perform the LDAP query. The search string must return no more than one result.
      <Controls>
      An element of the element @@ -2087,6 +2131,9 @@ Java keystores (optional)     <Controls searchScope="SUBTREE_SCOPE" returningObjects="false" />
        </Search>
        <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory" +  <Property name="java.naming.provider.url" value="ldap://directory.cis-qas.brown.edu:636/dc=brown,dc=edu" /> +  <Property name="java.naming.security.principal" value="cn=stc_query,ou=Special Users,dc=brown,dc=edu" /> +  <Property name="java.naming.security.credentials" value="password" /> />
        <cacheTime="2400"/>
      </JNDIDirectoryDataConnector>

      -- 1.7.10.4