As of GridShib for GT 0.4.0, the ShibbolethPIP attribute requester can be configured by supplying SAML2 metadata instead of explicitly configuring an IdP's URL, providerId, and certificate information. An optional service WSDD configuration of a directory of metadata files will cause the ShibbolethPIP to scan this directory for valid metadata files, configuring itself with an array of Attribute Authorities that are considered valid to contact. Further, we've supplied a commandline utility (gridshib-cert-setup) for configuring your Globus installation with the proper trusted certificates for the attribute query made to the IdP(s).

Note: In future releases of the Globus toolkit, we will be able to dynamically adjust the trusted certificates to use per exchange with the IdP (meaning that an administrator will be able to just configure the PIP with SAML2 metadata and be done). This is not technically possible now and the container's trusted certificate directory needs to be updated out-of-band. The commandline utility mentioned above attempts to make this step as automatic as possible.

If the metadata configuration is given, the ShibbolethPIP inspects a configured directory of metadata files at initializaton time (only at initialization, restarting the container is required to refresh the information). Processing considers files with root elements of EntityDescriptor or EntitiesDescriptor. Only AttributeAuthorityDescriptor and KeyAuthority elements are inspected. For each AA found in the metadata files, an entry is created that the PIP can reference.

To configure your ShibbolethPIP instance to look for and use metadata, use the metadata-dir configuration in your service's WSDD file and put metadata files in this directory that contain either a EntityDescriptor or EntitiesDescriptor root element.

After the Echo Service is installed to your Globus installation (for more information, see the testing section, in particular: Testing the installation with an existing Shibboleth AA using the EchoService), you can view a sample metadata file at $GLOBUS_LOCATION/etc/gridshib-gt-echo-0_5_1/idp-metadata/metadata.xml

Trusted authority credentials are a component of metadata files, but the current 4.0.x Globus Toolkit does not allow trusted certificates to be configured programmatically (it will in the next version). Thus, one needs to create certificate files to place in the Globus trusted certificate directory in order for the SSL exchange to work correctly. We have made this as automatic as possible by writing a commandline utility program called gridshib-cert-setup.

After the interceptors are installed to your Globus installation, $GLOBUS_LOCATION/bin/gridshib-cert-setup can be invoked at any time as long as the $GLOBUS_LOCATION environment variable is set. It is recommended that you do not run this untested while a production container is processing requests since it could affect GT operation.

IMPORTANT: Run this utility with the "status" subcommand (which is also the default subcommand so it is not necessary to specify it). This will provide you with information about exactly what it would have done for both of the other main subcommands: "install" and "remove." It is highly recommended you run this first so that nothing unexpected happens.

To view a list of all options, run the help subcommand:

cd $GLOBUS_LOCATION
./bin/gridshib-cert-setup -h

Output:

Set either metadata file or metadata directory to read in the AA certificates:
    Either file:      [-f <path>]
    Or directory:     [-d <directory>]

Pick an action:
    Either status [-s], install [-i], or remove [-r <dir>]
__

Options:
 -d,--mdDir <directory>      A directory with many metadata files in it
 -f,--mdFile <file>          A metadata file
 -h,--help                   Displays help
 -i,--install                Install certificates
 -o,--override <directory>   Manually set trusted certificate directory
 -r,--remove <directory>     Remove certificates, moving them to specified
                             directory
 -s,--status                 Print status and exit (default action)
 -z,--debug                  Enables debug mode

Below we will run some test commands to get a feel for the tool and the metadata files you are working with.

If you are using metadata and receive an updated metadata file from the federation: to update both the authorization module and the certificates in the trusted certificate directory, take the following steps:

In the following we assume you are dealing with just one metadata file, but you could easily replace the file with a directory of metadata files and the same concepts will apply.

SAML2 metadata <AttributeAuthorityDescriptor> elements can contain a list of samle:<Attribute> elements that advertise the set of attributes and attribute values the IdP may return.

If you wish, in your GridShib for GT deployment you can turn on an optimization (it is off by default) where this list will be respected. Respecting this list means that the PDP (the module that makes the authorization decision) will assume that these are the ONLY attributes that can be returned by a query to that attribute authority.

If we assume that those are the only attributes a query to that AA AND the currently configured authorization policy does not have any of these attributes then a (possibly expensive) query does not need to be made. In that case, a DENY will be returned immediately.

To enable this optimization, add the respect-md-attributes configuration to your service's WSDD.

If not caching, the steps of the authorization module:

If caching, the steps of the authorization module:

Missing from the steps above is the optimization that is possible outlined here: Metadata attribute optimization (that is OFF by default).

An attribute is considered "valid" if the SAML assertion the attribute was obtained from is considered "accepted." If the query results in a response containing assertions, the assertion must be from the expected issuer and for the expected audience.

Also, the time conditions of the SAML assertion are respected. If caching, the time conditions of the assertion in which the attribute was delivered are stored with each attribute. If the cache is consulted and the time range does not include the current time anymore, the attribute is considered invalid.

See the Attribute caching section and the with-caching authorization algorithm section for details on caching.

The file pointed to by the shibAuthzAttrFile WSDD parameter contains a list of SAML attributes that direct a PERMIT decision if the caller's identity has one of the attributes associated with it.

For example, if we:

then the client is allowed to invoke the operation.

There are several things to note about how the attributes in the ACL are matched to attributes coming over the wire from the AA:

The attribute policy must conform to the simple policy schema, found here in the source tree (element: AttributePolicy): interceptors/java/source/policy/compact/gridshib_policy/gridshib_policy_port_type.wsdl

The form is a list of entries:

<AttributePolicy>
  [<entry> 0 -> unbounded ]
     <listOfAttributes> 1 -> unbounded
        <saml:Attribute> 1 -> unbounded
     [<listOfUsernames> 0 -> unbounded ]
        [<username> 0 -> unbounded ]
  [</entry>]
</AttributePolicy>

The outer element <AttributePolicy> and its entry format is in a custom namespace, the attributes contained in <listOfAttributes> are SAML <Attribute> elements. The schemas used in Shibboleth slightly alter the SAML attribute definition -- this policy does NOT use attributes with that altered namespace, it uses regular SAML attributes.

Examples:

A list of attributes can have system accounts associated with it that will allow clients bearing the attributes access to the accounts, just like a grid-mapfile can map DNs to system accounts.

If the <listOfUsernames> element is present, the SAMLMapPIP will add the usernames to the client's information for the life of the operation invocation.

Example:

<AttributePolicy
    xmlns="http://gridshib.globus.org/namespaces/2005/08/policy"
    xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion">
    <entry>
      <listOfAttributes>
        <saml:Attribute AttributeName="urn:mace:dir:attribute-def:eduPersonAffiliation"
                  AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
            <saml:AttributeValue>faculty</saml:AttributeValue>
        </saml:Attribute>
      </listOfAttributes>
      <listOfUsernames>
        <username>manager</username>
      </listOfUsernames>
    </entry>
    <entry>
      <listOfAttributes>
        <saml:Attribute AttributeName="urn:mace:dir:attribute-def:eduPersonAffiliation"
                  AttributeNamespace="urn:mace:shibboleth:1.0:attributeNamespace:uri">
            <saml:AttributeValue>member</saml:AttributeValue>
        </saml:Attribute>
      </listOfAttributes>
      <listOfUsernames>
          <username>john</username>
          <username>lily</username>
      </listOfUsernames>
    </entry>
</AttributePolicy>

NOTE: An attribute may map to multiple usernames (as seen in the second example above), multiple attributes may map to multiple usernames, or one attribute may map to one username only (as seen in the first example above). As with the grid-mapfile, if multiple usernames are present a service such as GRAM can decide for itself which is appropriate (in GRAM's case, this is accomplished by the client supplied <localUserId> RSL element present in the <job> RSL element).

The username mappings are retrieved by a service using the same exact code that the gridmap aware service should:

String[] usernames = SecurityManager.getManager().getLocalUsernames();

Thus, this can be used to replace the grid-mapfile's username mapping aspect.

The SAMLMapPIP uses the ACL file set by the shibAuthzAttrFile configuration. But if the optional shibAuthzMapFile configuration is present, it will use that instead. Thus username mapping information can be separated from authorization policy if you so desire. It also allows the SAMLMapPIP to be used on its in conjunction with other PDP implementations.

If the optional authzMap configuration is present, the ShibbolethPDP will require that the caller has at least one username mapping in order for authorization to succeed.

NOTE: If using username mappings with GRAM, you must make sure the sudoers policy is correct. The typical GRAM entry in the sudoers policy looks like so:

globus ALL=(billy) NOPASSWD: /globuslocation/libexec/globus-gridmap-and-execute -g /etc/grid-security/grid-mapfile /globuslocation/libexec/globus-job-manager-script.pl *

The call to "globus-gridmap-and-execute -g /path/to/grid-mapfile" should be removed from the line (or a separate copy of the line added that excludes this). When GRAM detects that gridmap authorization is not being used it omits these arguments. Thus, the original sudo policy would fail unless the arguments were removed. This is a working entry:

globus ALL=(billy) NOPASSWD: /globuslocation/libexec/globus-job-manager-script.pl *

For more information about GRAM and sudo, see the Configuring Sudo section of the GRAM documentation.

You may have received this a "defective credential" error. For example:

Error: ; nested exception is:
GSSException: Defective credential detected [Caused by: Proxy file
(/tmp/x509up_u1000) not found.]

In this case, the defective credential error is that your proxy certificate is not found in the first place: you need to run grid-proxy-init. Documentation for grid-proxy-init can be found here or run:

cd $GLOBUS_LOCATION
source etc/globus-devel-env.sh
grid-proxy-init -help

If you do not know what a proxy certificate is, consult the GT4 security documentation key concepts section.

For other types of defective credential errors, see the general troubleshooting section.

If the client-side reports connection refused, for example:

./bin/shibecho -s https://127.0.0.1:8443/wsrf/services/ShibEchoService
Error: ; nested exception is:
        java.net.ConnectException: Connection refused

If you did not receive a credential or connection refused error, you probably received an authorization denied error.

The first thing to do is make sure you have DEBUG output for the authorization module enabled. See the instructions below.

If the container log's ERROR output notes a connection refused error:

ERROR authorization.ShibbolethPDP [ServiceThread-3,callPIP:555] error calling
PIP: Error contacting configured attribute authority
"https://idp.example.org:8443/shibboleth-idp/AA" [Caused by: ; nested
exception is:         java.net.ConnectException: Connection refused]

... then the Shibboleth AA endpoint is not valid. This could be a DNS problem or it could be that the IdP is just not up. More can be determined by typical means (for example, telnet). See above for the location of the ShibEchoService WSDD file which contains the AAUrl setting: Running the ShibEchoService client.

If the container log's ERROR output notes a 404 error:

error calling PIP: Error contacting configured attribute
authority "https://idp.example.org:8443/shibboleth-idp/AA" [Caused by:
(404)/shibboleth/AA]

... then the Shibboleth AA endpoint is not valid. This means some server is running at this endpoint, but that the Shibboleth IdP is not installed. The endpoint is configured in the AAUrl WSDD parameter of the echo service. See above for the location of the ShibEchoService WSDD file: Running the ShibEchoService client.

NOTE: if you are using GridShib with the Globus Toolkit 4.1 release or higher, this configuration will be in the security descriptor, not the server-config.wsdd

If the DN is not a valid identity at the IdP, the container will log this INFO level message:

INFO  authorization.ShibbolethPIP [ServiceThread-3,collectAttributes:409]
Received response from Attribute Authority:
The supplied Subject was unrecognized.

To remedy this situation, the IdP needs to be populated with the caller's DN, which can be found in the DEBUG output:

DEBUG authorization.ShibbolethPIP [ServiceThread-3,getX509Subject:875] x500
subjectName: cn=timothy freeman 964650,ou=people,dc=doegrids,dc=org

It can also be found by running the rfc2253dn program (see Determining a credential's IdP identity).

It's possible that the AA is returning an attribute about the caller, but the attribute is not in the ACL. The container's DEBUG log output will show an attribute returned:

DEBUG authorization.ShibbolethPIP [ServiceThread-2,collectAttributes:571] found
an attribute

attribute name  = urn:mace:dir:attribute-def:eduPersonAffiliation
attribute namespace  = urn:mace:shibboleth:1.0:attributeNamespace:uri


DEBUG authorization.ShibbolethPIP [ServiceThread-2,collectAttributes:600]
attribute value = member

... but later will reveal that it is not in the authorization policy (the attribute ACL):

DEBUG authorization.ShibbolethPDPUtil [ServiceThread-2,isAttributePermitted:176]
found one caller attribute

DEBUG authorization.ShibbolethPDPUtil [ServiceThread-2,isAttributePermitted:207]
no attributes passed

To solve the problem, look at the attribute returned from the AA and change the policy file to match.

Note: the attribute ACL file to edit will be whatever the value of the ShibEchoService's WSDD parameter "shibAuthzAttrFile" is. By default this value resolves to $GLOBUS_LOCATION/etc/gridshib-gt-echo-0_5_1/echo-service-security-descriptor.xml

NOTE: if you are using GridShib with the Globus Toolkit 4.1 release or higher, this configuration will be in the security descriptor, not the server-config.wsdd

Details on the ACL's contents can be found here.