This wiki page may contain some content that could go into the new admin guide:

http://dev.globus.org/wiki/GridShib_for_GT_Design

These docs appear at:
http://www.globus.org/toolkit/docs/development/4.2-drafts/security/gridshib/

One thing to make sure we're in sync on is what components will be represented
in the GT documentation. My take is it will be GS4GT and GS-ST. So, GS4Shib and
GSCA will not be included in GT and not documented in the GT documentation,
just on the gridshib site as they are currently. We'll continue to release them
separately, but I don't see any real advantage in bundling either with GT.

(In reply to comment #3)
> One thing to make sure we're in sync on is what components will be represented
> in the GT documentation. My take is it will be GS4GT and GS-ST.

No, sorry, GS-ST does not deploy into $GLOBUS_LOCATION and is therefore totally
separate.  GS-ST does not (and should not) be documented in the GS4GT
documentation.  The current HTML documentation for GS-ST is comprehensive and
nearly complete.

To emphasize this point, I've set the Component field to "GT plugin" above
since this documentation bug refers to GS4GT only.

Just capturing state with regards to prefixing of class names.

Here is a quote from
http://www.globus.org/toolkit/docs/development/4.2-drafts/security/wsaajava/wsaajava-secdesc.html

"Each interceptor name is scoped and the format is prefix:FQDN of the
interceptor. For example,
self:org.globus.wsrf.impl.security.authorization.SelfAuthorization. The prefix
is used to allow multiple instances of the same intercepor to exist in the same
PDP chain."

> > So as I understand this, since the parameters follow directly, the 
> > prefix appears once and only once (unlike in 4.0, where it appeared 
> > in each parameter name associated with the interceptor).

(In reply to comment #5)
> 
> "Each interceptor name is scoped and the format is prefix:FQDN of the
> interceptor... The prefix
> is used to allow multiple instances of the same intercepor to exist in the same
> PDP chain."
> 
> > > So as I understand this, since the parameters follow directly, the 
> > > prefix appears once and only once (unlike in 4.0, where it appeared 
> > > in each parameter name associated with the interceptor).

No, I don't think so.  As suggested above, the scope prefix exists primarily
"to allow multiple instances of the same intercepor to exist in the same PDP
chain."    In 4.0, I understand how to do this (see the GS4GT Quick Start for
an example).  In 4.1+, however, I'm confused.  If the same interceptor with an
identical scope prefix is listed in the authz chain twice, how are the
parameters defined?  Are the parameters redundantly defined in the second
interceptor instance?  What if the parameters are not identical in two
instances?  That seems to imply a contradiction since internally these two
instances are reduced to a single instantiation of the interceptor.

See Bug 5549 for background information on this issue.

(In reply to comment #6)
Look at the examples in the document Tim pointed out, e.g.
http://www.globus.org/toolkit/docs/development/4.2-drafts/security/wsaajava/wsaajava-secdesc.html#wsaajava-secdesc-other-defaultGridMap

Essentially as I understand it, each interceptor now has its own set of
parameter elements as children of its element.

I don't understand the relevance of Bug 5549. Scope is used in that context to
control (re-)initialization - not what we're talking about here. We're talking
here about scope to bind the interceptor to its parameters, which is now done
explicitly via the schema. 

(In reply to comment #7)
> (In reply to comment #6)
> Look at the examples in the document Tim pointed out...

I looked at that document but I don't see any example of an authz chain where
the same interceptor with an identical scope is listed twice.

> Essentially as I understand it, each interceptor now has its own set of
> parameter elements as children of its element.

I understand that.  I claim that practice leads to problems in the case where
the same interceptor (with the same scope) is listed twice (see the Quick Start
for an example).

> I don't understand the relevance of Bug 5549. Scope is used in that context to
> control (re-)initialization - not what we're talking about here.

In that case, scope is used to *suppress* reinitialization since a single
instantiation of the interceptor is required.  That's my point.  Why would I
bother listing the parameters in the second instance since they should be
identical to the parameter list in the first instance?  More importantly, what
does it mean to list a different set of parameters in the two instances (which
actually refer to a single instantiation of the interceptor).

> We're talking
> here about scope to bind the interceptor to its parameters, which is now done
> explicitly via the schema. 

There's implicit and explicit scoping rules being applied here.  In 4.0, there
was no implicit scope since the parameters were defined in a separate file.  In
4.1+, the parameters are implicitly scoped to an interceptor by the XML schema
(as you mentioned).  So what is the purpose of the explicit scope prefix? 
Answer: Two instances of the same interceptor in a single authz chain.

Now consider the special case where there are two instances of the same
interceptor in a single authz chain such that the scopes are identical.  Is a
parameter list required for the second instance?  Doesn't seem like there
should be since the two instances refer to the same instantiation of the
interceptor.

I should add that the use case discussed in Comment #5 though Comment #8 above
is typical (maybe even essential) in GS4GT.  An immediate example involves the
AttributeAcceptancePIP, which is invoked twice: once on pushed attributes and
then later on pulled attributes.

Another example involves the SAMLAttributePDP.  As you know, the GS4GT policy
file exhibits an "OR" semantic, that is, if there are multiple attributes in a
policy file, policy is satisfied if any one of the attributes is satisfied.  To
specify more complicated (i.e., realistic) policy exhibiting an "AND" semantic,
a deployer chains together multiple policy files, which leads to multiple
instances of the SAMLAttributePDP in the authz chain.

(In reply to comment #9)
Quoting from framework web page:
Each interceptor can specify a parameter value and the schema defines it as
xsd:any to allow for any user defined parameters. The parser extracts the
elements in <parameter>  element and returns them as DOM Element. It is left up
to the Interceptor to parse the Element. The DOM object created is placed in
the ChainConfig object passed to the authorization engine as a parameter called
"parameterObject". The prefix will be the scope specified in the interceptor
name.
End quote.

As I understand this, the scope is used as a prefix for the parameters in the
ChainConfig object. If you want two interceptors to share parameters, you use
the same scope for both. If you want them to use different parameters, you
change the scope.

So this example would result in the interceptor bar being called twice with the
same parameters:
<interceptor name="scope1:bar">
  <parameter>some param</parameter>
</interceptor>
<interceptor name="scope1:bar"/>

And this example would result in the the interceptor bar being called twice
with different parameters:
<interceptor name="scope1:bar">
  <parameter>some param</parameter>
</interceptor>
<interceptor name="scope2:bar">
  <parameter>some other param</parameter>
</interceptor>

An invaluable link for GT4 documentation writing:
http://www.globus.org/toolkit/docs/development/4.2-drafts/docbook/primer/

(In reply to comment #10)
> 
> So this example would result in the interceptor bar being called twice with the
> same parameters:
> <interceptor name="scope1:bar">
>   <parameter>some param</parameter>
> </interceptor>
> <interceptor name="scope1:bar"/>

That's the example I was looking for, thanks.  (Did you find this in the GT4.2
docs?)  So is it an error to re-specify the parameter in the second
<interceptor> element?

Note that interceptor bar is being called twice, but the interceptor should
only be *initialized* once (see Bug 5549).  So it doesn't make sense to specify
the parameters twice.  That's the issue I'm trying to come to grips with. 
Sorry if this isn't the place to discuss this issue.

(In reply to comment #12)
The examples are my own creation based on my understanding from reading the web
page.

Let's ping Rachana on this.

Status of the documentation is being tracked on the wiki:
http://dev.globus.org/wiki/GridShib_for_GT_0_6_0_documentation#Status_of_GS4GT4.2_Documentation

For completeness, here is a link to a thread on GS4GT config parameters:

http://www.globus.org/mail_archive/gridshib-dev/2008/03/msg00045.html

For the record, I've put work on this on hold since it does not appear GS4GT
will be included in GT4.2. Instead I'm working on docbook for GS4GT focused on
a 4.0.x release which can be found in the gt/docs/ subdirectory in CVS.

(In reply to comment #16)
> I'm working on docbook for GS4GT focused on
> a 4.0.x release which can be found in the gt/docs/ subdirectory in CVS.

Two things to note about this:

1. You are working in trunk while the rest of GS4GTv0.6.0 development is
occurring on gridshib_gt_0_6_0_branch.

2. There already is a directory gt/doc containing readme.html, the CHANGES
file, and the software license.

The only consequence of all that I can think of is that the source will not be
distributed with GS4GTv0.6.0 unless its committed to the branch.  Do we want
the source to be distributed with GS4GTv0.6.0?

I've copied these files into the gridshib_gt_0_6_0_branch under doc/admin

I'll move the directory in the trunk to match this path.

This bug is relevant to GT 4.2.x which our current release of GS4GT_0_6_0 does
not support.  Thus we are removing the dependency on bug 5568 and will resolve
it at a later date.