Changing a client service’s SAML certificates

Suomi.fi e-Identification supports two or more certificates in a client service's metadata. Certificates are used as key pairs to establish a trust relationship, and the validity period of the certificates is not checked. If the client service has registered several encryption certificates, Suomi.fi e-Identification will randomly select one of these certificates to encrypt the return message.

The client service must be prepared to decrypt the return messages with all ‘encryption’ certificates without a qualifier, regardless of their period of validity. A good practice is to implement the verification of certificates as a chain, so that if an authentication response cannot be obtained with the first certificate, the next step is to try the next one and so on.

Seamless exchange of certificates

There are two ways of exchanging certificates seamlessly or near-seamlessly.

The first method is the use of transit metadata, which consists of three steps.

1. First, you register a new certificate in Suomi.fi e-Identification alongside the old one (in the metadata). Once the new metadata has been implemented, it is possible to transition to the new certificate for signing authentication requests. Make sure that the authentication responses can also be decrypted with the old certificate.
2. Next, register a set of metadata in Suomi.fi e-Identification with only the new certificate.
3. Once the that metadata has been introduced, remove the support for the old certificate from the client service for authentication responses.

The third step can be skipped if, in the first step, the identifier 'signing' is used for the old certificate. The new certificate will be installed without an identifier. In this case, Suomi.fi e-Identification accepts identification requests with both certificates, but only uses the new certificate to encrypt the return message. 

The second method is to register a new entityID and transfer traffic to it at a suitable time after release. You then remove the old entityID when the traffic has been transferred to the new one and it has been found to be functional.

Non-seamless exchange of certificates

If the client service does not support the removal of an authentication response with several certificates and it is not possible to register a parallel entityID, the change of certificates in the service must be handled with an interruption:

1. Replace the old certificate with the new one in the client service’s metadata.
2. Upload the updated metadata to Service Management and prepare to change the certificate in the client service as soon as the production update in Suomi.fi e-Identification is complete. 

We aim to carry out production updates on Wednesdays at about 9 a.m. You will be notified by email when the update is complete.