HelseID and SFM: principles for use

HelseID is a common login solution for the Norwegian health sector, that helps to ensure that health information can be shared securely and easily. You can use HelseID to provide single sign-on login functionality, and to access an API secured with HelseID. HelseID is a separate product from NHN and general information is available in HelseIDs pages here in Utviklerportalen.

SFM uses HelseID to provide "single sign-on" user login for clients, and securing the SFMs-APIs. 

You as a vendor need to implement support for HelseID before you are able to use SFM. Note that HelseID has its own approval-process that is required.

Multi or single tenancy

There are two different client patterns that can be used in HelseID: Multi or singe tenancy.

As single tenancy was the only option in early adoption, the choice is now on the vendor.

In single tenancy each organization is represented with one HelseID client, while in multi tenancy there is only one multitenant client for the system/supplier, supporting several tenants. Each HelseID client has a secret with limited lifetime, and when running a web-based multi tenant system, the management of these will obviously be more efficient with a multi tenant client that only requires maintaining one secret. This is the major driver for making the transition from single to multi tenancy. For systems installed "on site", the opposite choice might be more natural.

What is new for multi tenant systems in SFM?

  • Vendors using multi tenant systems need to be approved specifically for the use of multi tenancy by HelseID in HelseIDs own approval process before they can start using this functionality in production.

  • Only one multi tenant HelseID-client is set up pr system/supplier, supporting all the suppliers tenants. This multi tenant client must be pre-registered to SFM with the organization number appearing in orgnr_supplier before it can be used towards SFM. This may be done by an email to kundersenter@nhn.no.

  • Vendors must provide functionality for creating and maintaning the journal-id for their customers, including inheriting a journal-id/SFM-id from other vendors for new customers.

  • The EPJ should include the journal-id in the token request to HelseID. See HelseID documentation for details. The multi tenant client will request a token with a specific journal-id (in contrast to single tenant clients that will present a pre-configured SFM-id).

Specific integration requirements need to be adopted before using multi tenant in SFM.

Switching from single tenancy to multi tenancy

The SFM-id from the single tenancy client points to the owners correct journal/installation. This SFM-id may be reused as the journal-id for the same tenant using multi tenancy (if they operate in the same cluster). Read more about the details here.

Why the journal-id?

The simple answer is that the world is complex, and SFM is flexible. The journal-id and SFM-id indicates a stable id for one journal system over time. Technically there is a many to one association, as one SFM instance may have multiple journal-id's pointing to it. The mechanism covers amont others:

  • organizational changes

  • HelseID transitions

  • support for multiple EPJ systems in the same organization

    • Journal-id will select the correct journal/SFM-instance from otherwise equal tokens

The token

The token must have a claim that is specific to SFM (SFM-id/Journal-id), with SFM as audience. 

There are two scopes that are relevant in SFM full, and they need to be set up in HelseID self service portal:

  • SFM portaler og integrasjoner: Scope: e-helse:sfm.api/sfm.api

    • Used for SFM Portals: SFM Data Sharing API and SFM Basis API.

  • SFM migrering: Scope: e-helse:sfm.api/sfm-migrering.api

    • Used for the first time uploading patient and organization data from the EPJ system to SFM.

By requesting an access token, a system can use an API - and the API provider can trust the content. Because the system gives up the token to the API provider, it is the token that defines which API/resource it is intended to provide access to. The access token has a relatively short lifetime.

The client can also request a refresh token that has a longer lifetime, and can use this to renew the access token as long as the refresh token is valid. The refresh token is not intended to leave the client application and can therefore have a longer lifetime.

SFM is built in such a way that incoming API calls, or functions performed in the SFM client, often involve communication with central systems on behalf of the client/user using SFM. SFM is therefore configured in HelseID to be able to perform a "token exchange", i.e. to exchange a token with an audience for SFM, for a token that provides access to, for example, Reseptformidleren (RF ) or Kjernejournal (KJ). The exchanged token will then have information about the original client, about the SFM that has exchanged the token and audience to provide access to the the new APIs i.e RF/KJ.

There are some important things to be aware of:

  • Due to possible clock drift, HelseID recommends that the client application uses the value ExpiresIn (seconds) that is returned together with the token from HelseId to support the refresh algorithm internally.

  • The EPJ must create a session against SFM with the endpoint: /api/Session/create

  • The EPJ needs to keept the token alive using refresh tokens. This is done in the Data Sharing API with the endpoint: /api/Session/refresh

  • Similarly, the session must be closed if the user logs out of the EHR system: /api/Session/end.

SFM has a session for each user in an organization. This is to avoid sessions piling up when the user jumps between machines. In this context, the Session is a link between accesstoken and the cookie. A user can create a session from many machines and it works for the user in all browsers until the user chooses to log out on one of the machines. Then there is a requirement to end the session and the EPJ needs to send an "end session". When the user comes to one of the other machines that is using the session, the cookie does not exist and the call to SFM fails. The EPJ must then create a new session and start the browser again so that the user may continue working on the patient.

An access token from HelseID is placed as a bearer token in http Authorization header. This token contains the following information necessary for SFM to determine the instance, and subsequenty perform an access control.

  • journal-id or SFM-id. Journal-id takes preference, and is generally mandataory for multi-tenancy tokens.

    • e-helse:sfm.api/client/claims/sfm-id

    •  nhn:sfm:journal-id

  • aud : must be e-helse:sfm.api

  • scope : must contain one of the SFM scopes

  • helseid://claims/client/claims/orgnr_parent must always contain the top level of an organization in Brreg.

    • orgnr_child is optional. SFM will first try to match the lowest level.

  • helseid://claims/identity/pid represents national id of person that is logged in. This needs to be a Fnr or Dnr.

  • helseid://claims/identity/security_level must be 4

  • helseid://claims/identity/assurance_level must be high

  • helseid://claims/client/client_tenancy is multi or single If missing, it will be interpreted as single.

  • helseid://claims/client/claims/orgnr_supplier indicates the owner of the helseID client, usually vendor or supplier org. This number MUST correspond to a preregistered supplier in SFM. 

Furthermore, the standard fields, i.e issuer an expiration, are all a part of the token validation.

Søk i Utviklerportalen

Søket er fullført!