GridShib for GT Design

From Globus

This page includes design notes for all versions of GridShib for GT since v0.5.0.

Contents 1 GridShib for GT v0.5.x 1.1 GridShib for GT v0.5.0 1.2 GridShib for GT v0.5.1 1.3 Security Context 2 GridShib for GT v0.6.x 2.1 Standalone Interceptors 2.1.1 Internal classnames 2.2 Combined Interceptors 2.3 Change Summary 2.3.1 New Interceptors 2.3.2 Renamed Interceptors 2.3.3 Deprecated Interceptors 2.3.4 Refactored Interceptors 2.3.5 Config Parameters 2.3.6 Renamed Service 2.4 Security Context 2.5 GridShib for GT v0.6.0 2.6 GridShib for GT v0.6.1 2.7 Implementation Issues

GridShib for GT v0.5.x

As of GridShib for GT v0.5.1, the design of the v0.5.x development stream is frozen. No new functionality or API changes will be made to GridShib for GT v0.5.x.

GridShib for GT v0.5.0

Interceptors implemented by GridShib for GT v0.5.0:

SAMLAuthnAssertionPIP

Updates the security context with a SAML NameIdentifier element taken from an authentication assertion embedded in the user's identity certificate (EEC or proxy). The NameIdentifier may be used to query for attributes later in the chain.

ShibbolethPIP

A PIP that queries a Shib AA using either the DN from the user's identity certificate or a NameIdentifier from the user's security context. The PIP validates the attribute response, parses the attribute assertion, and updates the security context with the resulting SAML attributes.

SAMLMapPIP

A PIP that maps attributes from the user's security context into one or more local accounts. The security context is updated with this mapping information.

ShibbolethPDP

A master PDP that consults GridMap, ShibbolethPIP, and SAMLMapPIP (in that order) before making an access control decision based on attributes from the user's security context.

1. If configured, invoke GridMap short-circuiting
   • This would result in returning PERMIT or continuing (NOT APPLICABLE)
2. Invoke ShibbolethPIP
3. Make an access control decision
   • If PERMIT:
     1. If configured, invoke SAMLMapPIP

     Returns PERMIT

   • If no PERMIT:

     Returns DENY (NOT APPLICABLE in GT4.1+)

 GridMapPDP ==> ShibbolethPIP ==> SAMLMapPIP

GridShib for GT v0.5.0 exposes the following interceptors to users and developers:

org.globus.gridshib.SAMLAuthnPIP

A wrapper around SAMLAuthnAssertionPIP

org.globus.gridshib.PIP

A wrapper around ShibbolethPIP

org.globus.gridshib.MapPIP

A wrapper around SAMLMapPIP

org.globus.gridshib.PDP

A wrapper around ShibbolethPDP, the master PDP

GridShib for GT v0.5.1

In GridShib for GT v0.5.1, support was added for the VOMS PIP and PDP:

VomsPIP

A PIP that parses an attribute certificate embedded in a proxy certificate and then updates the user's security context with the resulting attributes.

VomsPDP

A PDP that makes an access control decision based on the attributes collected by the VomsPIP.

In addition to the interceptors exposed by v0.5.0, GridShib for GT v0.5.1 exposes the following VOMS interceptors:

org.globus.voms.PIP

A wrapper around VomsPIP

org.globus.voms.PDP

A wrapper around VomsPDP

In GridShib for GT v0.5.1, the GridShib Master PDP was modified to incorporate the VomsPIP and the VomsPDP:

1. If configured, invoke GridMap short-circuiting
   • This would result in returning PERMIT or continuing (NOT APPLICABLE)
2. If configured, invoke VOMS short-circuiting
   • This would result in returning PERMIT or continuing (NOT APPLICABLE)
3. Invoke ShibbolethPIP
4. Make an access control decision
   • If PERMIT:
     1. If configured, invoke SAMLMapPIP

     Returns PERMIT

   • If no PERMIT:

     Returns DENY (NOT APPLICABLE in GT4.1+)

 GridMapPDP ==> VomsPIP ==> VomsPDP ==> ShibbolethPIP ==> SAMLMapPIP

Security Context

The v0.5.x security context consists of two objects:

• SAMLAuthenticationInformation
• SAMLAttributeInformation

An attribute in the latter consists of the following fields:

 private String name;  // SAML AttributeName
 private String namespace; // SAML AttributeNamespace
 private String[] values; // SAML AttributeValues (+Scope)
 private AttributeAuthority issuer;
 private Calendar notBefore;
 private Calendar notOnOrAfter;

GridShib for GT v0.6.x

GridShib for GT v0.6.x will support attribute push via X.509-bound SAML assertions. The following is a proposed design plan for the v0.6.x development stream.

Standalone Interceptors

SAMLAssertionPushPIP

This PIP walks the certificate chain presented by the requester, extracts any SAML assertions bound to the certificates in the chain, and updates the security context with the security information extracted from the bound assertions.

AttributeAcceptancePIP

Iterates over the attributes in the security context and filters those attributes that do not satisfy Attribute Acceptance Policy.

SAMLAttributePDP

Makes an access control decision based on attributes from the user's security context. Renders either a PERMIT decision or NOT APPLICABLE decision (never DENY). (Note: In GT4.0.x, NOT APPLICABLE equals DENY.)

SAMLBlacklistPDP

Makes an access control decision based on authentication context and attributes from the user's security context. Renders either a DENY decision or NOT APPLICABLE decision (never PERMIT). (Note: In GT4.0.x, NOT APPLICABLE equals PERMIT.)

SAMLQueryPIP

Queries a SAML Attribute Authority and updates the security context with the resulting attributes.

SAMLMapPIP

Maps attributes from the user's security context into one or more local accounts (similar to grid-mapfile but based on SAML attributes instead of DNs). Updates the security context with this mapping information.

Internal classnames

The above interceptors will be exposed to users and developers. The internal implementation classes (which are agnostic to Globus container version differences) will be named similarly, adding "Impl" on the end:

• SAMLAssertionPushPIPImpl
• AttributeAcceptancePIPImpl
• SAMLAttributePDPImpl
• SAMLBlacklistPDPImpl
• SAMLQueryPIPImpl
• SAMLMapPIPImpl

Combined Interceptors

Like earlier versions of GridShib for GT, only one combined interceptor will be exposed in v0.6.x. This interceptor is called GridShibPDP, a thin wrapper around GridShibPushPullPDPImpl described below.

GridShibPushPDPImpl

1. Invoke SAMLAssertionPushPIPImpl
2. Invoke AttributeAcceptancePIPImpl
3. Invoke SAMLBlacklistPDPImpl short-circuiting
   • If DENY, return DENY; otherwise, continue
4. Invoke SAMLMapPIPImpl
5. Invoke GridMap short-circuiting
   • If PERMIT, return PERMIT; otherwise, continue
6. Invoke VOMS short-circuiting
   • If PERMIT, return PERMIT; otherwise, continue
7. Invoke SAMLAttributePDPImpl
   • Return SAMLAttributePDPImpl decision

GridShibPullPDPImpl

1. For each identity in the security context, do the following:
   • Invoke SAMLQueryPIPImpl
   • Invoke AttributeAcceptancePIPImpl
   • Invoke SAMLBlacklistPDPImpl short-circuiting
     • If DENY, return DENY; otherwise, continue iterating
   • Invoke SAMLAttributePDPImpl
     • If PERMIT, break; otherwise, continue iterating
2. Invoke SAMLMapPIPImpl
3. Return SAMLAttributePDPImpl decision

GridShibPushPullPDPImpl

1. Invoke GridShibPushPDPImpl
   • If PERMIT, return PERMIT
   • If DENY, return DENY
   • Otherwise, continue
2. Invoke GridShibPullPDPImpl
   • Return GridShibPullPDPImpl decision

ClassicGridShibPDPImpl

This combined interceptor was previously called ShibbolethPDP in GridShib for GT v0.5.x.

1. If configured, invoke GridMap short-circuit
   • This would result in returning PERMIT or continuing (NOT APPLICABLE)
2. If configured, invoke VOMS short-circuit
   • This would result in returning PERMIT or continuing (NOT APPLICABLE)
3. Invoke SAMLQueryPIPImpl
4. Invoke AttributeAcceptancePIPImpl
5. Invoke SAMLBlacklistPDPImpl short-circuit
   • This would result in returning DENY or continuing (NOT APPLICABLE)
6. Invoke SAMLAttributePDPImpl
   • If PERMIT:
     1. If configured, invoke SAMLMapPIPImpl

     Return PERMIT

   • If no PERMIT:

     Return DENY (NOT APPLICABLE in GT4.1+)

Change Summary

The following is a summary of changes between v0.5.x and v0.6.x.

New Interceptors

For users:

• org.globus.gridshib.SAMLAssertionPushPIP
• org.globus.gridshib.AttributeAcceptancePIP
• org.globus.gridshib.SAMLAttributePDP
• org.globus.gridshib.SAMLBlacklistPDP
• org.globus.gridshib.SAMLQueryPIP (previously exposed as org.globus.gridshib.PIP)
• org.globus.gridshib.SAMLMapPIP (previously exposed as org.globus.gridshib.MapPIP)
• org.globus.gridshib.GridShibPDP

For developers:

• SAMLAssertionPushPIPImpl
• AttributeAcceptancePIPImpl
• SAMLAttributePDPImpl (includes functionality that was previously hardcoded in ShibbolethPDP)
• SAMLBlacklistPDPImpl
• GridShibPushPDPImpl
• GridShibPullPDPImpl
• GridShibPushPullPDPImpl
• ClassicGridShibPDPImpl (previously exposed to users as org.globus.gridshib.PDP)

Renamed Interceptors

The following exposed interceptors in GridShib for GT v0.5.x will be renamed:

• org.globus.gridshib.PIP (previously implemented as ShibbolethPIP) will be renamed to org.globus.gridshib.SAMLQueryPIP (implemented as SAMLQueryPIPImpl)
• org.globus.gridshib.PDP (previously implemented as ShibbolethPDP) will not be exposed in v0.6.x but will be implemented as ClassicGridShibPDPImpl
• org.globus.gridshib.MapPIP (previously implemented as SAMLMapPIP) will be renamed to org.globus.gridshib.SAMLMapPIP (implemented as SAMLMapPIPImpl)

Deprecated Interceptors

The following exposed interceptor in GridShib for GT v0.5.x is deprecated and will be removed in v0.6.0:

• org.globus.gridshib.SAMLAuthnPIP (previously implemented as SAMLAuthnAssertionPIP)

Refactored Interceptors

• Class ShibbolethPDPPolicy previously used in ShibbolethPDP will be refactored and exposed as a pair of standalone PDPs (SAMLAttributePDP and SAMLBlacklistPDP)

• SAMLQueryPIP will handle attribute caching internally (by relocating logic previously in ShibbolethPDP)

NOTE: This means pushed attributes will never be cached!

Config Parameters

Each configuration parameter is listed exactly once below. Interceptors that depend on the parameter are listed in parentheses. Implementations that are not yet complete are shown in red. Italicized parameters are for developers only.

Existing Config Parameters

These configuration parameters were introduced in GridShib for GT v0.5.x and will remain as-is in v0.6.x:

• samlMapPolicy (SAMLMapPIPImpl)
• consultDefaultGridmap (GridShibPushPDPImpl, unit tests)
• useVOMS (GridShibPushPDPImpl)

New Config Parameters

• enableBlacklisting (SAMLBlacklistPDPImpl)
• blacklistIPAddressesFile (SAMLBlacklistPDPImpl)
• blacklistNameIdentifiersFile (SAMLBlacklistPDPImpl)
• enableAttributeQuery (SAMLQueryPIPImpl)
• AAInstance (SAMLQueryPIPImpl)

Removed Config Parameters

• AAHostAuthz (SAMLQueryPIPImpl)
• AAIdentity (SAMLQueryPIPImpl)
• AAUrl (SAMLQueryPIPImpl, unit tests)
• authzMap ==> requireAuthzMap (GridShibPullPDPImpl, GridShibPushPullPDPImpl, unit tests)
• trusted-authn-authorities-file ==> trustedSAMLAuthoritiesFile (AttributeAcceptancePIPImpl)

Modified Config Parameters

• cacheAttr ==> cacheAttributes (SAMLQueryPIPImpl, SAMLMapPIPImpl)
• IdPproviderId ==> defaultIDPEntityID (SAMLQueryPIPImpl, unit tests)
• shibAuthzAttrFile ==> gridshibAuthzPolicyFile (SAMLAttributePDPImpl, SAMLMapPIPImpl)
• shibAuthzMapFile ==> gridshibAuthzMapFile (SAMLMapPIPImpl)
• shibPDPPolicy ==> gridshibPDPPolicy (SAMLAttributePDPImpl, SAMLMapPIPImpl, unit tests)
• shibDefaultGridmap ==> defaultGridmap (GridShibPushPDPImpl, unit tests)
• respect-md-attributes ==> respectMDAttributes (GridShibPullPDPImpl, GridShibPushPullPDPImpl)
• metadata-dir ==> metadataPath (SAMLQueryPIPImpl, SAMLAssertionPushPIPImpl)
• SPproviderId ==> gridSPEntityID (SAMLQueryPIPImpl, unit tests)

Renamed Service

• ShibEchoService --> GridShibEchoService

Security Context

The security context in v0.6.x consists of the following information:

• an ordered list of SAML Identity objects, derived from SAMLSubject
• a set of SAML AuthnContext objects, derived from SAMLAuthenticationStatement
• a set of SAML Attribute objects, derived from SAMLAttributeStatement
• a set of SAML AuthzDecision objects, derived from SAMLAuthorizationDecisionStatement

The Identity objects are used for IdP discovery whereas the AuthnContext objects are used strictly for access control. The Attribute objects are used for access control as well as whitelisting and blacklisting. The AuthzDecision class (not yet implemented) will allow restricted delegation of rights and may facilitate the merging of CAS and GridShib.

GridShib for GT v0.6.0

See GridShib for GT v0.6.0 Worksheet for a progress report on the current state of the implementation.

The following interceptors have been implemented in GridShib for GT v0.6.0:

• SAMLAssertionPushPIP
• AttributeAcceptancePIP
• SAMLAttributePDP
• SAMLBlacklistPDP
• SAMLQueryPIP
• SAMLMapPIP
• GridShibPDP

SAMLAssertionPushPIP

This PIP consumes all the embedded SAML in the presented certificate chain (see SAML in X.509 Validation for details). It does no policy enforcement.

Required functionality:

• push NameIdentifier into the GT runtime (as an attribute) [DONE]
• parse a single SAML assertion (per certificate) containing an AuthenticationStatement and/or an AttributeStatement [DONE]
• parse AuthenticationStatement [DONE]
  • log AuthenticationMethod, AuthenticationInstant, IPAddress, and DNSAddress [DONE]
• parse AttributeStatement [DONE]
  • log all SAML attributes and push them into the GT runtime [DONE]

Desired functionality (prioritized):

1. push IPAddress into the GT runtime [DONE]
2. parse nested SSO assertion in embedded SAML assertion
   • log proxied attributes but don't push them into the runtime
3. push AuthenticationMethod, AuthenticationInstant, and DNSAddress into the GT runtime [DONE]
4. parse SAML AuthorizationDecisionStatement
   • push AuthzDecision objects into the security context

AttributeAcceptancePIP

In GridShib for GT&nbspv0.6.0, this PIP implements the Trusted SAML Authorities logic currently in the deprecated SAMLAuthnAssertionPIP. It uses the list of trusted issuers to filter out any attributes from untrusted issuers.

SAMLAttributePDP

Required functionality:

• consult attribute-based authorization policy file [DONE]

Desired functionality (prioritized):

1. Allow for wildcarding in attribute policies
   • example: "*@example.edu"
   • wildcarding handles IP address ranges
     • example: "141.142.*"
     • a more sophisticated IP address range match function might be based on CIDR
2. consult blacklist of IdP identifiers

SAMLBlacklistPDP

Required functionality:

• consult blacklist of IP addresses [DONE]

Desired functionality (prioritized):

1. consult blacklist of user identifiers (NameIdentifier)
2. consult blacklist of user attributes

SAMLQueryPIP

In GridShib for GT v0.6.0, this PIP will only support the Shibboleth Attribute Authority and the internal unit test attribute authority. Support for other SAML AAs will be added in later versions of GridShib for GT.

SAMLMapPIP

This implementation of SAMLMapPIP is equivalent to the PIP included in v0.5.2 (with the exception of a major bug fix).

GridShibPDP

This implementation of GridShibPDP does not provide GridMap or VOMS short-circuiting.

Required functionality:

• invoke GridShibPushPDPImpl [DONE]
  • invoke SAMLAssertionPushPIP and AttributeAcceptancePIP in sequence
  • provide blacklisting based on pushed IP address(es)
  • provide SAML attribute mapping capability
• implement attribute aggregation algorithm [DONE]
  • invoke attribute query, perhaps multiple times [DONE]

Desired functionality (prioritized):

1. provide GridMap short-circuiting [DONE]
2. provide VOMS short-circuiting
3. provide blacklisting based on identity attributes

GridShib for GT v0.6.1

The following features are planned for GridShib for GT v0.6.1:

• implement a more general Attribute class
• implement true Attribute Acceptance Policy
• port Quick Start to docbook
• implement blacklist of identities and attributes
• implement DN mapping extension to Classic GridShib
• create Grid SP metadata template
• create IdP metadata for GridShib CA
• create IdP metadata for GridShib SAML Tools
• distribute IdP metadata
• add metadata check to SAMLAssertionPushPIP
• remove all traces of trusted authorities file
• parse nested assertions
• parse SAMLAuthorizationDecisionStatement
• implement object equivalence in SAMLAttribute class
• log security context to a database

Implementation Issues

1. Is a Trusted SAML Authorities file needed for GS4GT v0.6.x? Answer: Yes, but eventually it will be replaced with an attribute acceptance policy implementation and/or SAML metadata.
2. Where should the SAML Assertion OID (1.3.6.1.4.1.3536.1.1.1.10) be defined? (Currently, it is defined twice, in GridShib SAML Tools and GridShib for GT.)
3. Do we distribute SAMLAuthnAssertionPIP with GS4GT v0.6.0? Answer: No, the functionality of SAMLAuthnAssertionPIP has been incorporated into SAMLAssertionPushPIP for backward compatibility.
4. GS4GT does not fully support eduPersonTargetedID. Currently, the MACE-Dir SAML Attribute Profiles specifies the ePTID attribute as follows:

     <saml:Attribute
       AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"
       AttributeName="urn:mace:dir:attribute-def:eduPersonTargetedID">
       <saml:AttributeValue
         Scope="https://idp.example.org/shibboleth">1234567890</saml:AttributeValue>
     </saml:Attribute>

   However, the above legacy form of ePTID is deprecated in favor of a newer name-value syntax:

     <saml:Attribute
       AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri"
       AttributeName="urn:oid:1.3.6.1.4.1.5923.1.1.1.10">
       <saml:AttributeValue>
         <saml2:NameID
           Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
           NameQualifier="https://idp.example.org/shibboleth"
           SPNameQualifier="https://sp.example.org/shibboleth"
           >1234567890</saml2:NameID>
       </saml:AttributeValue>
     </saml:Attribute>

   The latter (which is used exclusively in SAML2 by the way) is not supported by GS4GT.
5. How do we map a SAML NameIdentifier to a GridShib attribute? (The wire format of ePTID above suggests one possibility.) Answer: Map a NameIdentifier to a GridShib attribute as follows:

     SAMLAttribute {
       name='urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'
       namespace='urn:mace:shibboleth:1.0:attributeNamespace:uri'
       value #1='
       <NameIdentifier 
         xmlns="urn:oasis:names:tc:SAML:1.0:assertion" 
         xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion" 
         xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol" 
         xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
         Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
         >trscavo</NameIdentifier>'
       issuer='CN=trscavo@idp.protectnetwork.org,
       OU=https://idp.protectnetwork.org/protectnetwork-idp,
       O=Shibboleth User,DC=computer,DC=ncsa,DC=uiuc,DC=edu'
       notBefore='null'
       notOnOrAfter='null'
     }

6. How do we distinguish between identity attributes and non-identity attributes?
7. The SAMLAttributeInformation class needs to be redesigned:
   • hide implementation details (such as the use of Vector)
   • implement NameIdentifier mapping (see above)
   • prevent duplicate attributes, that is, implement attribute equivalence (which is required to merge attributes)
   • replace AttributeAuthority with Issuer (details about the Issuer are stored in metadata)
   • introduce the notion of an ordered list of proxy issuer IDs (to handle nested assertions)

   Answer: A new class called SecurityContext has been implemented. This class addresses all of the above items except proxy issuer, which has been deferred until later.

8. The SAMLAuthenticationInformation class needs to be totally redesigned. Answer: A new class called AuthnContext has been implemented.
9. What support for country code will be provided in v0.6.0?
10. Suppose the client authenticates to the service with a proxy certificate containing a self-issued assertion. Suppose further the proxy certificate is signed by an EEC that itself contains a self-issued assertion. Should both assertions be processed? Answer: Yes, but the problem is understated. All certificates in the chain up to and including the first non-impersonation proxy should be processed.
11. In the client tools, what should be the format of the DN used to populate the Issuer attribute of the assertion? (This is the same issue we encountered when implementing the X509SubjectName name identifier in Classic GridShib.) Answer: The Issuer attribute MUST be an RFC 2253-conformant DN.
12. What information from the assertion should be logged at the INFO level? Answer: For one thing, all attributes (name, value, issuer) should be logged at the INFO level. Eventually, the entire security context should be so logged.
13. Should raw SAML assertions be dumped to a directory? Answer: No, that's not necessary.
14. What is the precise definition of an impersonation proxy? (The GSI library says one thing while the GridShib code says another.) Answer: Use the GSI library definition of impersonation proxy.
15. What should SAMLAssertionPushPIP do if it can't parse a bound SAML assertion?
16. More generally, under what conditions should SAMLAssertionPushPIP throw an exception, as opposed to silently aborting the attribute collection process?
17. In the case of a level n proxy certificate (n > 1), is the SAML issuer equal to the assertion issuer or the subject of the EEC? Answer: For an impersonation proxy containing a self-issed SAML assertion, the SAML issuer is the subject of the EEC. In all other cases, the SAML issuer is the actual assertion issuer (given by the Issuer XML attribute in the assertion).
18. Does it make sense to require an X.509 certificate containing a self-issued assertion to have an Issuer Alt Name extension containing the unique identifier of the SAML IdP that issued the assertion? This solves at least three problems:
    1. Strengthens the test for self-issued assertions by replacing DN string matching with URI equivalence.
    2. Allows an AuthenticationStatement in a self-issued assertion to be used for IdP discovery (think: nanoHUB).
    3. Paves the way for using SAML metadata in lieu of trusted SAML authorities files.
19. Is SAMLDiscoveryPIP really necessary? Answer: No, the information needed for IdP Discovery can be obtained with a single pass of SAMLAssertionPushPIP.
20. Is GridShibPullPDP really necessary? In other words, does it make sense to pull without push? Answer: It may make sense to pull without push in some deployment scenarios, but GridShib for GT v0.6.x will not expose such functionality to users (although an implementation will be provided for developers).
21. In what sense is SAMLBlacklistPDP a SAMLBlacklistPDP? In other words, is the "SAML" prefix justified? Answer: Yes, the "SAML" prefix is justified since a blacklist is an XML document containing <saml:NameIdentifier> elements and/or <saml:Attribute> elements.