The goal is to bind a SAML token to a proxy certificate signed by the gateway's
community credential.  As I understand the requirements, the X.509-bound SAML
token should contain the following information:

* entityID: a globally unique identifier for the SAML issuer (i.e., the
gateway)
* name identifier: a globally unique identifier for the authenticated user
* authentication statement: a description of the act of authentication at the
gateway
** authentication method: an identifier specifying the method of authentication
(e.g., password)
** authentication instant: a dateTime stamp indicating the exact time the
authentication took place
** IP address: the IP address of the user agent involved in the authentication
event
* attribute statement: a collection of user attributes
** isMemberOf attribute: an attribute declaring the user's membership in a
virtual organization (VO)
** mail attribute: the user's e-mail address

Notes:

- All of the above information is required except as noted below.
- An authentication statement is required if and only if the gateway is NOT
shib-enabled.  If the gateway is shib-enabled, the IdP will provide the
authentication context.
- The authentication instant is optional.  If it is omitted, the software will
default to NOW.
- The IP address is optional, if only because it is difficult to obtain the
authenticated user's IP address in some gateway environments (e.g., in a
portlet environment).

A gateway configuration file ($GRIDSHIB_HOME/etc/tg-gateway-config.properties)
has been written and will be distributed with GS-ST v0.3.0 RC.

(In reply to comment #1)
> 
> - The authentication instant is optional.  If it is omitted, the software will
> default to NOW.

So there's an interesting trade-off here.  Technically, setting AuthnInstant to
NOW is incorrect.  If the RP had policy with respect to AuthnInstant, it is
likely a value of NOW would lead to a false positive.

On the other hand, a correct value of AuthnInstant is difficult to compute.  It
requires that state be maintained from the time the user authenticates to the
time the user makes the request.  This could be done (using cookies and
sessions) but this raises the bar considerably, I think.

So which approach do we take?

(In reply to comment #2)
> A gateway configuration file ($GRIDSHIB_HOME/etc/tg-gateway-config.properties)
> has been written and will be distributed with GS-ST v0.3.0 RC.

Committed to CVS HEAD.

(In reply to comment #1)
> 
> - The IP address is optional, if only because it is difficult to obtain the
> authenticated user's IP address in some gateway environments (e.g., in a
> portlet environment).

I'm not sure what to do about this.  The RP could definitely make use of the IP
address of the authenticated user, but there is no known workaround in the case
of a portlet environment.  I want to require the gateway to provide an IP
address but you know that old saying "you can't squeeze blood from a turnip."

Using code that Terry Fleury and Jim Basney had written, implemented
toGSSCredential and toGlobusCredential methods in GSIUtil.  Committed the
latter to CVS HEAD.

Write a class called GatewayCredential such that the following is possible:

GatewayCredential cred = new GatewayCredential("trscavo");
cred.addEmailAddress("trscavo@gmail.com");
String authnMethod = 
  SAMLAuthenticationStatement.AuthenticationMethod_Password;
// wholly contrived authnInstant, 5 mins in the past:
Date authnInstant = new Date(new Date().getTime() - 1000*60*5);
String ipAddress = "255.255.255.255";
cred.addAuthnStatement(authnMethod, authnInstant, ipAddress);
GSIUtil.printCredential(cred.issue());

The untested code in Comment #7 turned out to be fairly close...see the
GatewayCredential and GatewayCredentialTest classes.  GatewayCredential is a
subclass of GlobusSAMLCredential where most of the heavy lifting is done.  All
code has been committed to CVS HEAD. 

Committed the SAMLCredential class to CVS HEAD.  SAMLCredential is the
precursor (i.e., proof of concept) to GatewayCredential.  Since the latter has
now been committed to CVS, SAMLCredential has been moved to the attic:

http://viewcvs.globus.org/viewcvs.cgi/gridshib/saml/teragrid/java/tests/org/teragrid/ncsa/gridshib/security/SAMLCredential.java?hideattic=0&view=log

(In reply to comment #3)
> (In reply to comment #1)
> > 
> > - The authentication instant is optional.  If it is omitted, the software will
> > default to NOW.
> 
> So there's an interesting trade-off here.  Technically, setting AuthnInstant to
> NOW is incorrect.  If the RP had policy with respect to AuthnInstant, it is
> likely a value of NOW would lead to a false positive.
> 
> On the other hand, a correct value of AuthnInstant is difficult to compute.  

The code implements the following compromise solution.  In
GlobusSAMLCredential, there's the following method:

public void setAuthnContext(
        String authnMethod, Date authnInstant, String ipAddress);

An exception is thrown if either authnMethod or authnInstant is null.  Thus it
is up the gateway developer to 1) call the method, and 2) provide correct
values for authnMethod and authnInstant.  Either the RP trusts the gateway to
do this or not.

The software does NOT default authnInstant to NOW.  In fact, the software
includes an AuthenticationStatement in the SAML token if and only if the
developer calls the setAuthnContext method.  In the end, it is up to the RP to
implement policy with respect to AuthnContext.

(In reply to comment #5)
> (In reply to comment #1)
> > 
> > - The IP address is optional, if only because it is difficult to obtain the
> > authenticated user's IP address in some gateway environments (e.g., in a
> > portlet environment).
> 
> I'm not sure what to do about this.

SAML does not require every AuthenticationStatement to have an IP address,
therefore the software does not either.  The developer may call the method in
Comment #10 with a null value for argument ipAddress.  In that case, the
software will simply not include an IP address in the AuthenticationStatement. 
In the end, it is up to the RP to implement policy with respect to IP address.

Here are links to the new software components for convenience:

http://viewcvs.globus.org/viewcvs.cgi/gridshib/saml/teragrid/java/tests/org/teragrid/ncsa/gridshib/security/GatewayCredentialTest.java?hideattic=0&view=log
http://viewcvs.globus.org/viewcvs.cgi/gridshib/saml/teragrid/java/src/org/teragrid/ncsa/gridshib/security/x509/GatewayCredential.java?hideattic=0&view=log
http://viewcvs.globus.org/viewcvs.cgi/gridshib/saml/teragrid/java/src/org/teragrid/ncsa/gridshib/security/saml/GatewayException.java?hideattic=0&view=log
http://viewcvs.globus.org/viewcvs.cgi/gridshib/saml/common/java/src/org/globus/gridshib/security/x509/GlobusSAMLCredential.java?hideattic=0&view=log
http://viewcvs.globus.org/viewcvs.cgi/gridshib/saml/common/java/src/org/globus/gridshib/security/saml/GlobusSAMLException.java?hideattic=0&view=log

Except for code cleanups and bug fixes, all code has been committed to CVS. 
This bug will remain open until the documentation has been written.

The primary document resides in the TeraGrid wiki:

http://www.teragridforum.org/mediawiki/index.php?title=Science_Gateway_Credential_with_Attributes

There is also a readme file that is mostly a link to the above wiki document:

http://gridshib.globus.org/docs/gridshib-saml-tools-0.3.0-rc/teragrid/readme.html

There is a separate CHANGES document as well:

http://gridshib.globus.org/docs/gridshib-saml-tools-0.3.0-rc/teragrid/CHANGES.txt

This issue is fully resolved.