In Finnish

This instruction describes the exchange of the certificate protecting the transmission of SAML messages only with respect to Shibboleth and Haka metadata. Also remember to renew the changed certificate from the Tomcat / www server

The process described in the guide secures uninterrupted certificate exchange with services operating in accordance with SAML specifications. There are SAML products on the market that do not support the key exchange process as such, but changing the certificate requires either manual measures, certificate exchange scheduled with the services, or logging into the service does not work at all during the time when two certificates have been published in the metadata. Haka does not support scheduled certificate exchange without compelling reasons, as it is impossible to agree on a common metadata update time suitable for all services.

Changing the SAML service (SP) certificate

This guide describes operating instructions for renewing the certificate of services registered in Haka, for example when the certificate expires or the key or certificate changes for another reason. By following the instructions exactly, the certificate can be replaced without significant service interruptions. If the certificate needs to be changed for data security reasons, this instruction should not be followed, but the certificate must be changed immediately, in that case contact CSC's Haka maintenance.

  1. Configure your SP to use both the new and the old certificate in parallel, so that the old certificate is used first, i.e. by default. Example of shibboleth2.xml:


    <CredentialResolver type="Chaining">
  <CredentialResolver type="File">
    <Key>
      <Name>OldKey</Name>
      <Path>/etc/shibboleth/old.key</Path>
    </Key>
    <Certificate>
      <Path>/etc/shibboleth/old.crt</Path>
    </Certificate>
  </CredentialResolver>
  <CredentialResolver type="File">
    <Key>
      <Name>NewKey</Name>
      <Path>/etc/shibboleth/new.key</Path>
    </Key>
    <Certificate>
      <Path>/etc/shibboleth/new.crt</Path>
    </Certificate>
  </CredentialResolver>
</CredentialResolver>


  2. In the Resource Register, add a new certificate to your SP's registration information in addition to the old one. In this case, both certificates end up in the metadata. If you don't have Haka credentials, send a new certificate by email haka@csc.fi
  3. Wait 24 hours from the moment the metadata has been published for it to update to the IdPs. After that, in the configuration of your SP, change the order of the certificates so that the new certificate is first and therefore becomes the default (see point 1 - i.e. here you change the order of these CredentialResolvers in reverse. Note: The first certificate in the list must be valid! So this point is reason to do it before the old certificate expires.
  4. Now you can delete the old certificate from the metadata with the Resource Register. 
  5. When the metadata has been updated again, wait 24 hours after the metadata update, after which you can remove the old certificate from the configuration of your SP.
Changing the SAML Identity Source (IdP) certificate
  1. In the Resource Register, add a new certificate to your IDP's registration information in addition to the old one. In this case, both certificates end up in the metadata. If you don't have Haka credentials, send a new certificate by email haka@csc.fi
  2. Wait for the metadata to be published and for it to update to the SPs. After that, change the certificate to a new certificate in the configuration of your IdP.
  3. Now you can delete the old certificate from the metadata with the Resource Register. 
  • No labels