Introduction

From time to time, certificates on services are changed as they expire, or security improvements are made.

As we support suomi.fi-tunnistus, the nation-level authority in strong identification in Finland, we are enforced to do this certification change from time to time.

Information about the metadata change is sent to suomi.fi-tiedotteet@dvv.fi recipient list. Instructions on joining the list can be found here https://postit.csc.fi/sympa/help/user .

Process

Typically this change process is straightforward, but when it also affects production, one has to be vary careful, and be prepared for a roll-back. How roll-back is done, is described below.

Sign-in to TIS as platform manager

You need to have Platfrom Manager or Platform Administrator role to be able to execute this change. At the minimum, you need permissions to modify user directories in all namespaces.

After sign-in, locate suomi.fi-tunnistus user direcotory in all namespaces. Typically there are only few. Picture below shows an example. Term “suomi.fi” is most often found in the display name.

Open

Prepare files

Read carefully instructions from DVV on the change, and note the relevant dates. Download the new metadata XML file and store it locally. Name it so you know it is it for test or for production, and it is the new metadata you want to use from now on.

Backup the current metadata for possible roll-back

Just in case you need to roll-back to the current version of metadata, please save it locally. Again, when saving it, make note in the filename if it is test or production, and it is the metadata currently in use.

To backup the metadata, you need to edit the user directory configuration. Just select the user directory, and select “Edit Directory” button as seen on picture above. Picture below shows the location on the user directory editor (first tab at the bottom), where the metadata is located.

Open

Just select the text in field “IdP metadata XML”, copy it to clipboard, and save is to a text editor. (Hint: Select the metadata so you have a flashing cursor there, then select Ctrl+A to select it all, and finally Ctrl-C to copy it to clipboard, finally paste it to text editor with Ctrl-V.)

Replace current metadata with new one

1. Clear off the current metadata so the field “IdP metadata XML” is empty.

2. Copy to clipboard the new metadata on text editor.

3. Paste new metadata to the field “IdP metadata XML”. If there is a problem with the metadata, the field will turn to red and there will be and error message. You should Revert to previous configuration, and not to save changes, and that will break the user directory.

4. Select “Save” at the top-right on the user directory editor. Then select “Close”.

New metadata is activated immediately when it is saved.

Verify it is working

How the verification is done varies tremendously. This is why we will only show one way to do it.

Sign-in to TIS “System Config UI” with user account in namespace where suomi.fi-tunnistus is enabled, and where metadata was changed. In normal production, this UI is often disabled for majority of user accounts and namespaces, so some arrangements may be necessary. After sign-in locate on the Dashboard the following link: “Verify your identity”.

Select that link, and verify suomi.fi-tunnistus works as it should.

Additional external information

Previous metadata changes:

2022:
production https://tunnistus.suomi.fi/static/metadata/idp-metadata.xml
test https://static.apro.tunnistus.fi/static/metadata/idp-metadata.xml

2021:

<https://palveluhallinta.suomi.fi/en/ajankohtaista/uutiset/60055af5909cad03b0c819f5 ,<https://palveluhallinta.suomi.fi/en/ajankohtaista/uutiset/5f844ad576a9630847c1e9b1 >

This is all in Finnish (external links, verified working when last edited this page)..

https://palveluhallinta.suomi.fi/fi/tuki/artikkelit/5fc615b161baa3075ddba1ee

https://palveluhallinta.suomi.fi/storage/cms.files/8MThHqSLwD0nFMfo.pdf