Important information about your OpenAthens SP implementation

24 October 2012

We have been informed by the UK Access Management Federation for Education and Research that the certificate they issue to validate the federation metadata expires on Friday 16 November 2012 at 13:26:51 GMT.  The certificate is configured with your copy of OpenAthens SP; each time OpenAthens SP retrieves a copy of the federation metadata (usually once every 24 hours), the UK Access Management Federation’s certificate is used to verify that the metadata is valid and genuine, so it is essential that it is updated before then. 

What will the impact be?

If your copy of the certificate is allowed to expire, OpenAthens SP will cease to trust organisations registered with the UK Access Management Federation that have implemented identity provider (IdP) software, and your products and services will not be available to their users.  Users accessing your products and services via Athens will not be affected.

Where is the certificate?

OpenAthens SP 2.0 and above
Federation signing certificates are pushed to OpenAthens SP 2.x via the configuration generated from the SP Dashboard tool.  So there will be no need to update them directly on the file system, however the configuration(s) will need updating to include the new certificate.

OpenAthens SP pre 2.0
1. Locate the Atacama configuration file used by your service, usually named atacamaConfig.xml.
2. Under the Shibboleth compatibility module section, locate the following parameter for the relevant implementation of OpenAthens SP:

Non Java implementations, and Java versions pre 1.3.0
<!-- Set the location of a file containing on or more trusted CA certificates. -->
      <param name="trustFile">
        <value>/path/to/ukfederation.pem</value>
        <value>/path/to/ukfederation-2010.pem</value>
      </param>

Java versions 1.3.0 and after
<param name="trustFile">
<!-- Use to verify metadata.  Signatures and TLS if the metadata is served on a secure channel (https) -->
      <map groupMatch=".*" valueMatch="^.*.pem$"
valueTarget="${platform}/trust/$0">
<dataSource provider="Core:listFiles" match="${platform}/trust/"/>
</map>
</param>

This defines the location of your existing UK Access Management Federation certificate.

How do I fix this?

OpenAthens SP 2.0 and above
Please see our wiki article for detailed instructions.

OpenAthens SP pre 2.0
1. Download the new certificate from http://metadata.ukfederation.org.uk/ukfederation-2012.pem and verify according to the UK Federation Technical Recommendations for Participants, section 4.3.
2. The instructions for adding the new certificate are dependent on the OpenAthens SP implementation that you are using:

Non Java implementations, and Java versions pre 1.3.0
a) Add the new certificate to the configuration in addition to the existing certificate:
      <!-- Set the location of a file containing on or more trusted CA certificates. -->
      <param name="trustFile">
        <value>/path/to/ukfederation.pem</value>
        <value>/path/to/ukfederation-2010.pem</value>
        <value>/path/to/ukfederation-2012.pem</value>
      </param>
NB: You MUST not remove the parameter reference to the 2010 certificate, and if you have parameters pointing to certificates for other federations you should also leave these in place.

b) Add the new certificate to the directory referenced in the above configuration parameters

Java versions 1.3.0 and after
a) Just add the new certificate to the "${platform}/trust” directory

3. Ensure that your webserver has permission to read the certificate file.
4. Restart your server (or ensure that the Atacama configuration is re-read).
5. After 16 November 2012 the original certificate can safely be removed from the configuration and server.  

How can I check that the new certificate is working?

The UK Federation will be informing their registered technical contacts directly on when they will be embedding the new certificate in the metadata; the next automatic refresh of the metadata will use the new certificate.  If you want to refresh the metadata manually, you should do the following:

OpenAthens SP 2.0 and above
Please refer to step 5 in our wiki article for details.

OpenAthens SP pre 2.0
C library (Windows/Linux)
1. Locate the Atacama configuration file used by your service, usually named atacamaConfig.xml.
2. Find the location of the OpenAthensSP metadata cache directory. This is configured under the SAML module section, via the following parameter:

      <!-- Defines the directory to use to cache metadata files. -->
      <param name="cacheDir">
        <value>/path/to/cache_directory</value>
      </param>

3. Delete all metadata files in the cache directory. These all have a prefix of  ‘ata-md-’.
4. Restart your server (or ensure that the Atacama configuration is re-read).

Java
For Java implementations simply restart your server to ensure that the Atacama configuration is re-read.

Where can I get further information about this?

If you have any questions about this issue, please contact the Eduserv OpenAthens Service Desk via one of the methods below, using ‘OpenAthens SP certificate update’ as a reference:

Last reviewed date: 24 October 2012