Shibboleth Developers

[Nathan Dors <>]

FWIW, here are some notes I took during my initial read through 
this overview.

[line 112] section 2.1.3 describes the inter-site transfer service and
says "its use will be de-emphasized" in the document. i don't know what
audiences will benefit from having any emphasis of this component, but you
might de-emphasize it even more than you have. the references to it on
lines 108-109 make sense; those in this section are obviously necessary; 
line 135 is OK, i suppose; lines 435-436 refer to the redirect URL prefix
used by "the inter-site transfer service". however, if you go look at
steps 3 and 4 of the corresponding profile (section 4.2) it refers to the
"SSO service"; lines 451-453 allow us to assume the functions of the SSO
service and inter-site transfer service are combined. maybe you could say
that up front in section 2.1.3 and refer to the SSO service throughtout
the rest of the document.

[line 111] "the latter" seems to refer to something (what?) and suggests
there's a former-something as well.

[line 135] "SSO exchange" ... is that a common phrase from SAML? it's used
just once in this document, so i wonder if there isn't a more common way
of expressing the same thing; on the other hand, it's analogous to
"attribute exchange", which is used several times (e.g., lines 681-682).

[line 144] "independently of" or "independent of"?

[line 152] "provided by SAML" or "defined by SAML"?

[line 217] "preceeding" is misspelled

[line 285] "the previous authentication statement" ... which statement is
that? it takes a bit of effort to follow this section's references (on
lines 210, 217, 250) to preceding and previous examples. i don't know what
to suggest other than labeling all of the examples for easier reference.

[line 360] does the parenthetic statement here serve a purpose?

[lines 418-420] this definition of the browser/post profile might be 
moved to the beginning of section 4.1.

[lines 420-421] this definition of the browser/artifact profile might be 
moved to the beginning of section 4.2

[lines 424-453] one wonders why this isn't a subsection on the shibboleth
authentication request.

[line 423] omit the comma. the document uses an "open" style except for
here.

[line 474] is the sentence beginning "in any event,..." necessary? if so,
the document should be consistent where it's repeated later (cf. lines
576-577 and 607-608)

[line 509] "the above profile" ... maybe the profile name can be used
rather than the location in the document (cf. line 690 where the profile
reference is named.)

[line 549] figure 4, step (5) should be labelled POST to match step 5,
line 568.

[line 611] "redirect URL" ... cf. line 435's "redirect URL prefix". you 
might use the same phrase for both.

[line 763] this note might be better placed within the profile's steps,
for example at the end of step 6 where the AA is being accessed. also, i
notice the format of this note ("note:" with a colon) is different from
most of the other notes within the document (lines 110, 115, 214, 252,
283, 927, 1047) which omit the colon and use a full sentence instead.
(well, looking at it again, lines 110 and 115 also use a colon.)

[783-786] i assume everyone knows that the order of the two artifacts in 
the URL doesn't matter.

[983-984] "section 4" and "sections 5.1 and 5.2" test our ability to
remember which profiles those sections describe. it may make sense to
spell them out.

[1052, 1054] here the profile names are spelled out. however, one almost
expects a reference to the section too. (can we have it both ways? maybe.
cf. lines 1056-1057 which provide both a profile name and section.)

[1060-1061] the use of a lead-in question stands out here. i have nothing
against stylistic variety, but it's inconsistent with the rest of the
document.

[1063] "relatively new" ... relatively new to what? in a year, the
metadata constructs will be relatively-something-else. i'll bet there's a
better way to express all this and to locate "[SAMLMeta]" closer to what
it references.

Cheers,
Nathan