CANARIE - Canadian Access Federation

The Shibboleth IdP software can be implemented at an institution in two main ways:

1. As an add-on to an existing web single sign-on (WebSSO) service
2. To provide both WebSSO and federated access.

Due to the relatively recent application of federated access technologies, it is common for institutions to have an existing WebSSO service. In this case, Shibboleth is installed as an add-on. The Shibboleth IdP was designed to integrate with common WebSSO products today such as OpenSSO, Pubcookie and CAS for authentication. It also integrates with popular directory store technologies such as LDAP, RDBMS, and ActiveDirectory for authorization processing.

There are a number of choices among commercial Identity Management products to construct a SAML-compliant IdP (e.g., Sun's OpenSSO product), however, most commercial products are compliant with only the latest version of the SAML standard - version 2.0.

Internet2 has an excellent reference for Shibboleth basics.  

Overview of an installation process (not upgrade) for an IdP using Shibboleth version 2 software

The primary reference for this function is from Internet2. Information provided here is intended to augment the already comprehensive I2 documentation.

Note that Shibboleth version 1.3 should no longer be used in a new installation. The version 2 software supports both the new SAML 2.0 and older SAML 1.1 functionality.

The steps are:

• Install and configure Shibboleth Identity Provider software.
  This step involves the selection and setup of platform and OS, installation of a Java Servlet container - typically Tomcat, and the installation and configuration of the Shibboleth distribution. There is also description on hot failover design.
• Test installation using the Internet2 Shibboleth testbed.
  The testbed is available at: https://www.testshib.org/testshib-two/index.jsp and consists of a test service provider, log monitoring and documentation which will aid in checking and troubleshooting IdP operation.
• Work with CAF Shibboleth Federation operator (SFO) to ensure the setup of proper operating configuration (metadata).
  This step involves the generation of metadata - SAML site configuration - which will be used by CAF participants to uniquely and securely communicate with the IdP.
  The following information must be provided to the SFO:

Field	Value	Example
EntityID	URL	https://idp.myschool.ca/entity
Service Location	URL	https://idp.myschool.ca/shibboleth
Client Certificate
Organization Name	public identifier	University of Myschool
Organization URL	public website	http://www.myschool.ca
Technical Contact	Firstname Lastname
Technical Contact Email

Notes:

1. The EntityID must meet the following criteria:

• it must be chosen to be persistent, so do not use DNS hostnames
• it must be unique
• it should be chosen to be resolvable at some future time - e.g., https://idp.myschool.ca/entity can be an active URL.

2. The client certificate must be a self-signed X.509 certificate with a minimum 2048 bit keysize.
3. The email address for the SFO is: tickets@canarie.ca  

To configure a functional Shibboleth 2.3.x identity provider to download and verify the federation metadata file, there are two sections in the file relying-party.xml that need to be edited:

1. Add MetadataProvider configuration using the following as a template:

<metadata:MetadataProvider id="CanadianAccessFederation" xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
     metadataURL="https://caf-shib2ops.ca/CoreServices/caf_metadata_signed.xml"
     backingFile="/local/shibboleth-idp/metadata/cafshib_metadata_signed.xml"
     cacheDuration="3600">
<metadata:MetadataFilter xsi:type="ChainingFilter" xmlns="urn:mace:shibboleth:2.0:metadata">
     <metadata:MetadataFilter xsi:type="RequiredValidUntil" xmlns="urn:mace:shibboleth:2.0:metadata" maxValidityInterval="4838400" />
          <metadata:MetadataFilter xsi:type="SignatureValidation" xmlns="urn:mace:shibboleth:2.0:metadata" trustEngineRef="shibboleth.MetadataTrustEngine" requireSignedMetadata="true" />
     </metadata:MetadataFilter>
</metadata:MetadataProvider>

2. Download the metadata verification X.509 certificate from: https://caf-shibops.ca/CoreServices/index.shtml

3. Add TrustEngine configuration using the following template:

<security:TrustEngine id="shibboleth.MetadataTrustEngine" xsi:type="security:StaticExplicitKeySignature">
     <security:Credential id="CAFFederationCredentials" xsi:type="security:X509Filesystem">
          <security:Certificate>/local/shibboleth-idp/credentials/cafshib_metadata_verify.pem</security:Certificate>
     </security:Credential>
</security:TrustEngine>

A Shibboleth SP is typically installed and configured on a web server to implement access control for a site. That control includes successful authentication and authorization based on attributes requested from an IdP.

For an institution, there could potentially be numerous SPs given the proliferation of web resources. Therefore, it is useful to plan and provide resources for Shibboleth SP deployment in order to reduce complexity as much as possible. Also, it is necessary to have a technical 'point of contact' to handle troubleshooting issues that may involve other CAF participants.

 

Overview of an installation process for an SP using Shibboleth version 2 software

The primary reference for this function is the Internet2 site. Information provided here is intended to augment the already comprehensive I2 documentation.

Note that Shibboleth version 1.3 should no longer be used in a new installation. The version 2 software supports both the new SAML 2.0 and older SAML 1.1 functionality.

The steps are analogous to the IdP installation overview:

• Install and configure Shibboleth Identity Provider software.
• Test installation using the Internet2 Shibboleth testbed.
  The testbed is available at: https://www.testshib.org/testshib-two/index.jsp and consists of a test service provider, log monitoring and documentation which will aid in checking and troubleshooting IdP operation.
• Work with CAF Shibboleth Federation Operator (SFO) to ensure the setup of proper operating configuration (metadata).
  This step involves the generation of metadata - SAML site configuration - which will be used by CAF participants to uniquely and securely communicate with the IdP.
  The following information must be provided to the SFO:

Field	Value	Example
EntityID	URL	https://mySP.mydept.myschool.ca/entity
Service Location	URL	https://mySP.mydept.myschool.ca/SP_label
Client Certificate
Organization Name	public identifier	University of Myschool
Organization URL	public website	http://www.myschool.ca
Technical Contact	Firstname Lastname
Technical Contact	Email

Notes:

1. The EntityID must meet the following criteria:

• it must be chosen to be persistent, so do not use DNS hostnames
• it must be unique
• it should be chosen to be resolvable at some future time - e.g., https://idp.myschool.ca/entity can be an active URL.

2. The client certificate must be a self-signed X.509 certificate with a minimum 2048 bit keysize.
3. The email address for the SFO is: tickets@canarie.ca  

This section describes the steps to implement IdP Discovery and metadata verification/retrieval with the new CAF SAML2 service for your SP installation.

Configuring IdP Discovery for SAML 2 Shibboleth 2.4.x or Greater

Add the following configuration to your Shibboleth SP metadata that you must then submit to CAF at tickets@canarie.ca.

<md:Extensions>
         <DiscoveryResponse xmlns="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="https://<Service_Provider_FQDN>/Shibboleth.sso/Login" index="1"/>
</md:Extensions>

The SessionInitiator element

The SessionInitiator element should be configured similarly to:

<!-- caf-shib2ops SAML2 Discovery Service -->
         <SSO discoveryProtocol="SAMLDS" discoveryURL="https://caf-shib2ops.ca/DS/CAF.ds">
         SAML2 SAML1
</SSO>

Configuring IdP Discovery Service for SAML 2 that predates 2.4.x

<md:Extensions>
          <DiscoveryResponse xmlns="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Binding="urn:oasis:names:tc:SAML:profiles:SSO:idp-discovery-protocol" Location="https://<Service_Provider_FQDN>/Shibboleth.sso/DS" index="1"/>
</md:Extensions>

Note that as an SP, these changes must be submitted to the CAF operator for installation to the CAF metadata for them to be available to the rest of the federation participants.

The SessionInitiator element

The following entry is used by the SAML 2.0 Discovery Service to return to the requesting Service Provider where to send the user for authentication. The SessionInitiator element in shibboleth2.xml should be configured similarly to:

<SessionInitiator type="Chaining" Location="/DS" id="DS" relayState="cookie">
           <SessionInitiator type="SAML2" acsIndex="1" template="bindingTemplate.html"/>
           <SessionInitiator type="Shib1" acsIndex="5"/>
           <SessionInitiator type="SAMLDS" URL="https://caf-shib2ops.ca/DS/CAF.ds"/>
</SessionInitiator>

---

---

Configuring IdP Discovery for versions of SAML1 (Shibboleth previous to 2.4.x)

NOTE: The older Where Are You From (WAYF) service and supporting metadata endpoints will no longer be relevant as the new Discovery Service has integrated support for back compatibility to SAML1 WAYF. The old core services located at: https://caf-shibops.ca/CoreServices/index.shtml will be disabled as of June 30th, 2013. The new services are available now and this date was chosen to permit sufficient time to migrate to the new service recognizing activities may need to take place after this academic school year.

Following are instructions for configuration of versions of SAML1 (Shibboleth previous to 2.4.x)

To configure a functional Shibboleth 2.3.x identity provider to download and verify the federation metadata file, there are two sections in the file relying-party.xml that need to be edited:

1. Use the following configuration as a template in the shibboleth2.xml file to configure your SP to input and verify the Canadian Access Federation metadata:

<MetadataProvider type="XML" uri="https://caf-shibops.ca/CoreServices/cafshib_metadata_signed.xml" backingFilePath="/etc/shibboleth/metadata.caf.xml" reloadInterval="3600">
<MetadataFilter type="RequireValidUntil" maxValidityInterval="7776000"/>
<MetadataFilter type="Signature" verifyName="false" certificate="/etc/pki/tls/certs/cafshib_metadata_verify.pem"/>
</MetadataProvider>

2. The configured verification certificate must be downloaded and stored locally. Download location: https://caf-shibops.ca/CoreServices/index.shtml

3. Use the following configuration as a template in the shibboleth2.xml file to configure your SP to select the CAF IdP Discovery service:

<SessionInitiator type="Chaining" Location="/WAYF" id="WAYF" relayState="cookie">
<SessionInitiator type="SAML2" acsIndex="1" template="bindingTemplate.html"/>
<SessionInitiator type="Shib1" acsIndex="5"/>
<SessionInitiator type="WAYF" acsIndex="5" URL="https://caf-shibops.ca/WAYF/a.wayf" />
</SessionInitiator>