Shibboleth Developers

lots of small  diddly stuff...... I'm too tired to proofread this 
note... if something sounds stupid, then I may well  have mistyped, 
etc. Just ask.......

1) in the intro, this needs to be filled in

"Insert features here."

2) In the intro, para 5, is the "for your operating system" correct?

Please ensure that you have the appropriate .tarball for your operating 
system.

3) section 2.a., first bullet -- mention  SQL support

4) section 2.a, last bullet.. replace this

It is recommended that a web server must be deployed that can host 
Java servlets and Tomcat, although not explicitly necessary, as 
Tomcat can still host an origin without it.

with something like -- A Java servlet container. Shibboleth has been 
extensively tested with Tomcat.

new bullet - It is recommended that a web server such as apache be 
deployed in front of Tomcat, to provide authentication services and 
to control the flow of requests to Tomcat.

5) section 2.b.  - Federations -- should we mention the existence 
(and charter) of IQ?

6) section 2.d, first sentence  -- does the SHIRE use cert's?

7) section 2.e, 1st para, sentence 3 - " The SHAR provides its own 
name and the URL of the resource on behalf of which it is making the 
request." -- update for v1.2

8) section 2.f - contacts -- these are provided to the federation....

9) section 3.a  - mod_jk currently comes with a build glitch.... 
should we mention this?

10) section 3.a, enterprise directory -- could also be SQL....

11) section 3.b, point 6 ... add after the config example?

This would result in a url for the HS of http://hostname/shibboleth/HS

12) section 3.b, point 8 -- change optional to required?

        SSLVerifyClient optional

13) section 3.b, new point 9 -- TESTthe standalone config!

14) section 4.a  remove the 6666 ... we don't want to  encourage 
anything like that..

AAUrl="http://therock.cc.columbia.edu:6666/shibboleth/AA";

15) section 4.a -- I've got a question -- the only RelyingParty 
element in the sample is named urn:mace:inqueue, but would clearly 
seem  to be for localhost testing.... is the use of this name going 
to confuse people, when they move to step 2 (adding an IQ definition 
to this file....)?

16) section 4.a - changes to interop in a federation section

-- is the intent to leave localhost operation  intact?

-- there should be a few sentences at the front, providing an 
overview of what the steps listed in this section will result in.....

-- bullet 3 -- should we tell people they'll need to add 
FileResolver/KeyStore elements specifying the credentials they'll 
use within the federation they're joining?

-- at the end of section  4.a (and before 4.a.i), should we recommend 
testing against the federation sample target?

17) section 4.a.i -- might be useful to include at the end "Note: the 
default attribute resolver is configured to use echo -- NOT ldap!".

18) section 4.e , para 2  mentions $SHIB_HOME... which is defined 
somewhere in section 5...

19) section 5.a -- we might want to  include a short (1 para?) 
overview describing how the various elements interact.....

The AAUrl, defaultRelyingParty, and providerId attributes of the 
ShibbolethOriginConfig element provide default values that will be 
used 1) when interacting with a shib v1.1  or earlier target, or 2) 
when not overridden by attributes on a matching RelyingParty element. 
RelyingParty elements are used  to identify requesting targets, and 
to then customize values for AAUrl, providerId, NameFormat, and 
credentials.

20) section  5.a - this origi.xml example seems to be for a site 
that's in IQ, is no longer using localhost for testing, and is also a 
member of some sort of local federation (eg intra-campus). However, 
since some of the id values are the same as from section  4.a, it may 
not be clear to all readers that... behind the scenes ...  some tings 
have changed. Presumably, the foo FileResolver now points  to this 
site's credentials within the Fed... even tho the files have the same 
name as before...  and the FederationProvider references the same 
file (sites.xml), without mentioning that this is no longer the file 
in the distribution.....

I suspect that just by changing some of the values in this example, 
things might be clearer....

21) section 5.a, FileResolver, first sentence... possibly hange to 
"The element associates an identifier with a pair of files used to 
store a private key and certificate, and is contained...."

-- KeyStoreresolver  - 1st sentence... missing some words near "and  to"

-- Log4JConfig mentions log4j.properties file -- I don't think this 
is still in the distribution?

-- nameMapping, type  description -- "dictates how handles are passed 
FROM THE HS to the AA.

-- nameMaping, under principal, add NOTE: if this method  is used, 
Shibboleth will NOT be providing any privacy protection. The user's 
identify will  be  transferred to the target by the HS.

-- relyingParty, 1st sentence  -- missing word "that origin"

-- RP, 1st para, last sentence... let's be a bit blunter  -- targets 
cannot impersonate....

-- RP, point 4, 1st sentence, add "all the" before FederationProvider 
elements....

-- RP, point 4, 2nd sentence --  If the providerId value matches a 
DestinationSite entry in the metadata, and there is a RelyingParty 
element that has the same providerId as the URI of the the 
federation, that RelyingParty is used. If not, the default relying 
party handles the request. (make sure this sentence  is correct....)

-- RP -- undent the descriptions of name, AAsigningCredentials, etc

-- RP, AAUrl - change text? The URL for the AA to be used in 
conjunction with this Relying  Party.

-- RP, passthruErrors -- define "relay", and  describe the alernative.....

-- RP, current text -> signAttrResponses: If this boolean attribute 
has a value of true, the attribute response itself will be signed in 
addition to the security and authentication provided by the SSL 
session. SAML responses contain one or more assertions. Defaults to 
false; if true, an https:// AAUrl may be redundant.

is that  last part about https really true? isn't that how the AA 
validates the SHAR's credentials against what can be used with the 
supplied providerId?

22) ShibbolethOriginConfig

-- "AAUrl specifies the URL where the AA for this HS resides," -> 
specifies the url for the AA which is to be used by default, unless 
overridden  elsewhere.

-- maxHSThreads -- do we have a "best practice" recommendation value for this?

-- passThruErrors -- how would I decide on a reasonable setting for this?

23) section 5.b ...

-- mention that this text  applies to the file based ARP repository....

-- para 3,  sentence 2  - "Each ARP rule specifies a single release 
policy within the ARP container pertaining to a particular target 
application." ... I think you can  remove the phrase "within the ARP 
container".

24) 5.b.i, sentence 1, 2 - change to?  When a request arrives from a 
particular relying party, an effective ARP is constructed as follows:

25) section 5.c - title mentions java keystores -- but presumably 
applies to all methods of storing credentials.... altho the cookbook 
steps  included here only apply to  keystores.....

maybe mention that apache/mod_ssl typically store credentials in PEM 
and DER formats in files, and its easiest to just reference those 
from shib....

26) section  5.d

-- sentence 2 -- wich -> which

-- what's the name of that property? or rather attribute......

-- propety -> property

-- para 2, sentence 3, from -> form

-- para 4, 1st sentence, change to "Version 1.2 of Shibboleth comes 
with two attribute definitions:"

-- is  there any other reference to CustomAttributeDefinition?

-- provide a bit of structure within this section? (eg make 
JNDIDirectoryDataConnector  and SimpleAttributeDefinition numbered 
sub-sections?)

-- description of <search> "DN filter" -> search filter?

-- in the JNDIDirectoryDataConnector example...maybe include a couple 
of other properties, just to makeit  complete...?

<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" />

27) section 5.f - indent the numbered points

whew......