OIDC interface
Suomi.fi e-Identification to deploy OpenID Connect interface – the change requires measures from e-services
Suomi.fi e-Identification will introduce an interface that supports the OpenID Connect protocol instead of the SAML 2.0 standard. In the change, the current SAML interface will be replaced with a new OIDC interface. The deployment of the new interface requires measures from e-services. The current SAML interface of Suomi.fi e-Identification will be discontinued after a transition period.
The new OpenID Connect interface responds to the needs of client organisations better
OpenID Connect is an authentication protocol based on the OAuth 2.0 protocol. As a result of the interface change, a trust relationship is established between the e-service and the e-Identification service by using metadata compliant with the OIDC protocol.
The new OpenID Connect interface responds to the needs of client organisations and introduces a more modern and developer-friendly protocol. The changeover to the OIDC interface will also improve security, as the exchange of keys will in future take place more often and personal data will be transferred between servers.
Changes in the interface
SAML 2.0 and OpenID Connect have similar functionalities, but their implementation methods are different. The SAML protocol uses XML-based messages, whereas the OIDC protocol uses JSOn and JWT.
Changing over to the OIDC interface facilitates the workload involved in maintaining e-services. As a result of the changeover, the changing of SAML certificates will be discontinued. In the OIDC interface, the change of keys can be automated and metadata updates are not required. The change of SAML certificates carried out every two years will be discontinued, and in the OIDC interface, the keys will be retrieved in the url specified by the e-service in its metadata. The e-service will no longer need to download new metadata when certificates are changed.
Below is a summary of the interfaces.
Feature | SAML | OIDC |
|---|---|---|
Text format / data transfer format | XML | JSON |
Single sign-on and single logout | Supported functionality | Supported functionality Remains the same. The single sign-on session is shared between the interfaces. |
Personal data | Attributes | Scope and claims. Same data, but in a different format. |
Submission of metadata/Registration of environment | Through Suomi.fi Service Management | Through Suomi.fi Service Management The e-service no longer needs to provide certificates in connection with metadata, which reduces the need for metadata updates. |
User permit | Remains the same. The permit for SAML is also valid for OIDC | |
Certificate for the e-service’s environment | Managed through metadata | Managed using jwks_uris, which means that the e-service can change certificates without separately having to submit them to Suomi.fi e-Identification. |
Changing SAML Certificates | Changing SAML certificates every two years | Changes regularly |
Identification tokens | Remains the same | |
User's perspective | Remains the same |
Read more about the OIDC specifications here: https://openid.net/specs/openid-connect-core-1_0.htmlOpens in a new window.
The transition from the SAML 2.0 standard to the OpenID Connect protocol does not bring any visible changes to the citizen’s identification path. It is possible to carry out the deployment without any breaks visible to users by registering the new OIDC environment alongside the old one. More detailed instructions for the deployment will be communicated to e-services later.
Single sign-on and single logout remain supported functionalities in the OIDC interface.
The change requires measures from e-services – do as follows
A prerequisite for the change is that the e-services using Suomi.fi e-Identification deploy the new OIDC interface in the production and testing environment of Suomi.fi e-Identification. E-services must carry out the technical deployment of the interface themselves, and the workload of the deployment depends on the implementation of the e-service. The transition to the OIDC interface starts from the client test environment and then proceeds to the production environment. Inform your potential system supplier about the upcoming change and take into account the deployment of the new interface in the product development roadmap of the e-service.
A prerequisite for the deployment of the OIDC interface is that the new details of the metadata are submitted through Service Management. We will notify you separately when the client test environment and the production environment can be deployed. Suomi.fi e-Identification will publish instructions for the deployment of the OIDC interface on the Suomi.fi for Service Developers website and provide support for the deployment of the interface. The deployment of the OIDC interface does not require a new user permit for Suomi.fi e-Identification.
Schedule for the deployment of the OIDC interface
The OIDC interface will be published in late 2026 in the client test environment and production environment of Suomi.fi e-Identification. We will publish more detailed publication schedules separately. The deployment of the client test environment and production environment does not need to be carried out at the same time as the publication of the OIDC interfaces by Suomi.fi e-Identification. E-services can make the transition within their own schedules, taking into account the transition period of the interface change. The e-service is responsible for testing the change before proceeding to production.
E-services must change over to using the OIDC interface by 1 June 2028. The current SAML interface of Suomi.fi e-Identification will remain a supported interface for the duration of the transition period, and e-services can schedule their own transition to the OIDC interface within the transition period. It is advisable to start scheduling and planning the transition in your organisation immediately so that the transition of your e-service can be completed within the transition period.
The current SAML interface will be discontinued in Suomi.fi e-Identification on 1 June 2028. After this, identification through the SAML interface will no longer work.