The technical configuration of a Shibboleth SP to connect to eduGAIN has been broken down into the following steps.

• Running the latest version of software
• Loading the AAF eduGAIN metadata
• SP is releasing the required R&S attributes to the federation
• An eduGAIN enabled Discovery Service
  

Laster version of software for eduGAIN services

What software are you running?

There are a number of software implementations of the SAML service provider. Each will have its own website, development activities and update notification processes. You should be following the notifications for the software you are using to implement your SAML service providers to help ensure you are running the latest secure stable version at all times. The following table provides a short list of common software that has been used within the AAF

What version are you running?

To determine the software or System Information/version you are currently running, type one of the following commands:

Note: Depending on your software version, these commands/keys may vary.

Shibboleth SP

You can determine the overall version of the SP software you have installed by running shibd from the command line with the -v option (Linux/Unix only).

On Windows, use shibd -version at the command prompt (you might have to browse to the folder, usually c:\opt\shibboleth-sp\sbin, if the shibboleth SP isn't in your path and you get the 'unrecognised command' error)

For any platform, you can determine the version of the SP and various libraries by examining log files during the startup sequence or, if you have sufficient access, by using the status handler.

https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPHandler

SimpleSAMLphp

To determine the version you are currently running:

SimpleSAML_Configuration-class:

    require_once('.../lib/_autoload.php');

    $cfg = SimpleSAML_Configuration::loadFromArray(array());

    echo $cfg->getVersion();

Output can be something like:

    1.14.14

Upgrading your software

Consult the software web site for detailed information on upgrading. Upgrading the Shibboleth SP software is generally straight forward as it packaged software on a number of Linux variants.

When upgrading please ensure you upgrade your test version in the AAF test federation before moving to your production services.Also consider your organisation change processes when upgrading software.

Keeping your OS and supporting software up to date

You SAML Service provider software doesn’t run in isolation, there is the Operating System, Web Server, crypto software and many other dependent software components. Each of these is specific to your environments and each will have its own maintenance processes. You need to ensure that these supporting components are regularly patched and upgraded.

Consuming eduGAIN metadata for Service Providers

The AAF is providing a new Metadata feeds for eduGAIN that must be consumed by AAF Services and Identity Providers that wish to join eduGAIN.

EduGAIN metadata contains all of the authorised entities that can participate with service providers and identity providers within the AAF. This includes;

• All eduGAIN Identity Providers
• All eduGAIN service providers that identify as Research and Scholarly
• All other eduGAIN service providers that have been requested by an AAF organisation and approved by the AAF.

Production Federation

Services in the Production federation will use the AAF eduGAIN metadata available at https://md.aaf.edu.au/aaf-edugain-metadata.xml. This metadata is signed by the AAF using a SHA256 signing key. You MUST use the public key available at https://md.aaf.edu.au/aaf-metadata-certificate.pem to verify metadata documents whenever they are retrieved.

To confirm that you have obtained the correct key ensure the file you have downloaded conforms to the following:

$> openssl x509 -subject -dates -fingerprint -in aaf-metadata-certificate.pem
         subject= /O=Australian Access Federation/CN=AAF Metadata
         notBefore=Nov 24 04:27:20 2015 GMT
         notAfter=Dec  9 04:27:20 2035 GMT
         SHA1 Fingerprint=E2:FC:CC:CB:0E:0F:3B:32:FA:55:87:29:08:DE:E0:34:DA:A2:15:5A

Configuring a Shibboleth SP

If your service provider is using the Shibboleth SP software you will need to make the following changes to the shibboleth2.xml file generally found in the /etc/shibboleth.

Check which Version of the AAF metadata you are currently using. If you obtain metadata from https://ds.aaf.edu.au you must first update your SP to use the new AAF federation metadata source available from https://md.aaf.edu.au before continuing.

Add the following configuration beneath the AAF federation metadata configuration.

<MetadataProvider type="XML" uri="https://md.aaf.edu.au/aaf-edugain-metadata.xml"
             backingFilePath="eduGAIN-metadata.aaf.xml" reloadInterval="7200">
           <MetadataFilter type="RequireValidUntil" maxValidityInterval="2419200"/>
           <MetadataFilter type="Signature" certificate="aaf-metadata-cert.pem"/>
        </MetadataProvider>

Verify that the certificate used for your AAF metadata feed is the same as for the eduGAIN metadata feed. The certitifcate=”aaf-metadata-cert.pem" config should be the same for both.

Restart your service provider.

Testing

To verify that your SP is consuming the eduGAIN metadata check your SP logs for any errors and check that the metadata file is downloading correctly and appears on your server. Your SP should have created the file /var/cache/eduGAIN-metadata.aaf.xml.

If your SP does not load the eduGAIN metadata, your log files should provide a good indication as to the fault. You may need to increase the log level to DEBUG which will give you all of the relevant details.

If your SP does not successfully load the metadata and your logs do not highlight the cause of the failure please contact support@aaf.edu.au for assistance.

Non-Shibboleth Service Providers

For non-shibboleth service providers please consult the documentation provided by your software on how to consume federation metadata.  AAF Support can provide limited support for non-shibboleth software at this time.

Test Federation

 eduGAIN does not provide a test federation, however the AAF does provide an eduGAIN feed for the test federation (see https://md.test.aaf.edu.au for details). This metadata can be used on your test SP to verify your configuration changes before applying them to your production service.

Requesting attributes from eduGAIN IdPs

The Australian Access Federation simplifies access to user attributes from AAF Identity providers. The AAF has defined Core attributes that a service provider can reliably expect to receive from the IdP when requested.

The AAF also provides the Federation Registry tool where service providers can register their attribute requirements. Once approved, these attributes are converted into technical attribute requirements within the metadata which inform IdPs to release a correct set of attributes.

This process of using the federation registry will continue for services that are part of eduGAIN. As a Service Provider you will use the Federation Registry to assert the attributes your service requires.

The Research and Scholarly categories will form a fundamental attribute set which guarantees a higher success rates when requesting attribute from the R & S attribute bundle. The R&S attribute bundle consists (abstractly) of the following required data elements:

• shared user identifier
• person name
• email address

and one optional element:

• affiliation

Where shared user identifier is a persistent, non-reassigned, non-targeted identifier defined to be either of the following:

• eduPersonPrincipalName (if non-reassigned)
• eduPersonPrincipalName + eduPersonTargetedID

and where person name is defined to be either (or both) of the following:

• displayName
• givenName + sn

Email address is defined to be the mail attribute, and Affiliation is defined to be the eduPersonScopedAffiliation attribute. All attributes in the R&S attribute bundle are also part of the AAF Core attribute set.

Requesting attributes using the Federation Registry

Steps for requesting attributes from Federation Registry:

• Login to the Federation Registry as the Administrator of the Service (contact AAF Support if you need to assign an administrator to your service).
• Select your service from the “My Service Providers” list on your dashboard
• Select the SAML tab
• Select the Attributes tab

You are now on the Service Provider’s Attributes page. From here you can add, modify and remove attributes that your service requires.

Adding a new attribute the request will require approval at both the organisation and federation level. Please ensure that a reason is clearly provided which defines a purpose with respect to your service.

Once the approval has occurred the change will flow out into the metadata which is then consumed by eduGAIN Identity Providers. This process may take up to 48 hours to propagate across internet, multi-federations and their respective metadata files.

Discovery Service Mechanism for Service Providers

When a service can be accessed by users from multiple organisations from multiple federations, it must ensure that the user during the login process can find and select their organisation he/she to authenticate. This process is called Identity Provider Discovery. There are multiple open-source implementations (Shibboleth Discovery Service) that allow to operate an own Discovery Service. Alternatively, the AAF provides a central discovery service.

There are 2 Discovery Service options, use a local discovery mechanism or use the central AAF discovery service.  

Use a local Discovery Service

When using a local discovery service your SAML service provider software will generally provide you with the required data. It will extract the data from the Metadata which will include the MDUI extensions for enhanced discovery.

A local discovery service mechanism is the responsibility of the service provider.

Use the AAF Discovery Service

The AAF provides a central discovery service that can be utilized by any AAF service provider. It provides a discovery mechanism for both AAF IdPs and all of eduGAIN IdPs.

The URL for the all of eduGAIN IdPs is: https://ds.aaf.edu.au/discovery/edugain

To update your Shibboleth Service Provider to use the all of eduGAIN discovery you need to modify the discoveryURL defined in the /etc/shibboleth/shibboleth2.xml file.

  <SSO discoveryProtocol="SAMLDS"
                  discoveryURL="https://ds.aaf.edu.au/discovery/edugain">
                  SAML2 SAML1
   </SSO>

After a restart of the Service provider users will be taken to the all of eduGAIN discovery section of the AAF central discovery service.