Reference Federation FAQ

Shibboleth SP Configuration

How do you configure the Shibboleth 2.0 SP to receive GFIPM SAML 2 Federation Entity Metadata automatically (including digital signature verification)?

1. Download a copy of the Reference Federation's CA Certificate, and save it on your Shibboleth SP server in an appropriate place (typically the Shibboleth configuration directory).

2. Add the following Metadata Provider to your Shibboleth2.xml file (you will need to update the paths for backingFilePath and the path to the saved certificate):

     <MetadataProvider type="XML" uri="http://ref.gfipm.net/gfipm-signed-ref-metadata.xml"
         backingFilePath="/var/run/shibboleth/gfipm-metadata.xml" reloadInterval="7200">
         <SignatureMetadataFilter certificate="/etc/shibboleth/trust/ref-gfipm-ca.crt"/>
     </MetadataProvider>

How do you configure the Shibboleth 2.0 SP to use GFIPM Issued SAML Credentials?

1. Edit the Shibboleth2.xml file, specifically the Credential Resolver section:

     <CredentialResolver type="File">
         <Key>
             <Path>/full/path/to/yoursp.key</Path>
         </Key>
         <Certificate>
             <Path>/full/path/to/yoursp.crt</Path>
         </Certificate>
     </CredentialResolver>

2. Restart Shibboleth

How do you configure the Shibboleth 2.0 SP to use GFIPM 2.0 Attributes export them to your application?

1. Edit the attribute-map.xml file (found in your Shibboleth configuration directory).

2. You can add individual attribute mapping rules like the following (or download a full Attribute Map and trim it down to the attributes you care about).

   <Attribute name="gfipm:2.0:user:LocalId" id="GfipmLocalId">
       <AttributeDecoder xsi:type="StringAttributeDecoder" caseSensitive="true"/>
   </Attribute>

3. The id specified above is the name of the environment variable that Apache populates with the assertion contents. In some cases, your application environment may further alter this name by prepending HTTP_, CGI_, or something else. Use an appropriate test script/program for your application to view the full environment if the id is not directly available.

How do you configure the Shibboleth 2.0 SP to export via HTTP Headers Instead of Apache Environment Variables?

This is commonly needed when Apache is proxying a backend application resource (Tomcat, etc...).

1. Edit the shibd.conf file (found in your Apache module configuration directory).

2. Add the following line to each protected location:

  ShibUseHeaders On

A full snippet from the file might look like:

     <Location /prot>
       AuthType shibboleth
       ShibRequireSession On
       ShibUseHeaders On
       require valid-user
     </Location>

You should also read this article from the Shibboleth wiki regarding passing environment variables into Tomcat instead of using headers to strengthen the security of your application.

How do you configure the Shibboleth 2.0 SP to export the full SAML assertion for your application?

1. Configure your protected resource to include exporting of the assertion (either in the Apache file or the native request map):

     <Host name="your.sphost.name">
         <Path name="prot" 
               authType="shibboleth" 
               requireSession="true" 
               exportAssertion="true">
         </Path>
     </Host>

Or within the Apache configuration file:

     <Location /prot>
       AuthType shibboleth
       ShibRequireSession On
       ShibExportAssertion On
       require valid-user
     </Location>

2. Optional: Depending on how you secure your system you may need to edit the exportLocation URL within the Shibboleth2.xml file (to specify https or to specify http):

     <Sessions lifetime="28800" timeout="3600" checkAddress="false"
        handlerURL="/Shibboleth.sso" handlerSSL="true" cookieProps="; path=/; secure"
        exportLocation="https://localhost/Shibboleth.sso/GetAssertion"
        idpHistory="false" idpHistoryDays="7">

3. Restart Shibboleth

4. Now you will need to update your application to use the exported URL to query for the SAML Assertion. Shibboleth documents this process here. Within GFIPM, there should be only a single assertion, so you can configure your application to query the URL found at the Header/Environment Variable Shib-Assertion-01.

How do you configure the Shibboleth 2.0 SP to use the centralized GFIPM Discovery Service?

1. Comment out or remove all of the current Session Initiator's within the <Sessions> section of the Shibboleth2.xml.

2. Add the following <SessionInitator>:

     <SessionInitiator isDefault="true" type="Chaining" Location="/DS" id="DS">
         <SessionInitiator type="SAML2" defaultACSIndex="1" 
                           template="bindingTemplate.html"/>
         <SessionInitiator type="SAMLDS" URL="http://ref.gfipm.net/ds/"/>
     </SessionInitiator>

3. Restart Shibboleth. Shibboleth should now redirect you to the Discovery Service when Shibboleth protected resources are accessed.

---

Shibboleth IDP Configuration

How do you configure the Shibboleth 2.0 IDP to receive GFIPM SAML 2 Federation Entity Metadata automatically (including digital signature verification)?

1. Download a copy of the Reference Federation's CA Certificate, and save it on your Shibboleth IDP server in an appropriate place (typically the Shibboleth configuration directory).

2. You will need to add two configuration snippets to the Relying-Party.xml configuration file, updating appropriately for the paths on your system. First add a new Metadata Provider:

     <MetadataProvider id="URLMD" xsi:type="FileBackedHTTPMetadataProvider" 
                       xmlns="urn:mace:shibboleth:2.0:metadata"
     		  metadataURL="http://ref.gfipm.net/gfipm-signed-ref-metadata.xml" 
                       backingFile="C:\Shib-idp/metadata/gfipm-metadata.xml" 
                       maintainExpiredMetadata="true" />

You will also need to add a Trust entry for validating the Metdata file:

     <security:TrustEngine id="shibboleth.MetadataTrustEngine" 
                           xsi:type="security:StaticExplicitKeySignature">
       <security:Credential id="GFIPMCredentials" xsi:type="security:X509Filesystem">
         <security:Certificate>/path/to/ref-gfipm-ca.crt</security:Certificate>
       </security:Credential>
     </security:TrustEngine>

How do you configure the Shibboleth 2.0 IDP to use GFIPM Issued SAML Credentials?

1. Edit the relying-party.xml file, specifically the Credential section:

     <security:Credential id="IdPCredential" xsi:type="security:X509Filesystem">
         <security:PrivateKey>/your/shib/path/creds/youridp.key</security:PrivateKey>
         <security:Certificate>/your/shib/path/creds/youridp.crt</security:Certificate>
     </security:Credential> 

2. Restart Tomcat/Shibboleth

---

PKI Issues

How do you generate SAML Signing/Encryption Certificates with openssl?

1. Download a copy of openssl (if not available on your system) from http://www.openssl.org/.

2. The following snippet is how you generate a private key and self signed certificate that lasts for 5 years:

     #openssl req -nodes -new -days 1826 -sha256 -x509 -keyout key.pem -out cert.pem -newkey 4096

3. This operation will prompt the user for data to populate the CSR, specifically it will look like the following:

     Country Name (2 letter code) [GB]:US
     State or Province Name (full name) [Berkshire]:GA
     Locality Name (eg, city) [Newbury]:Atlanta
     Organization Name (eg, company) [My Company Ltd]:GFIPM
     Organizational Unit Name (eg, section) []:GTRI
     Common Name (eg, your name or your server's hostname) []:my.hostname.ext
     Email Address []:admin@hostname.ext

4. The resulting certificate should be included in the metadata for your organization.