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.

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 one 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 its 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. In test this may be done by an email to kundersenter@nhn.no or by other effective channels.

• 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. See more in the examples below.

Why the journal-id?

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

• organizational changes, including transfer of activity from one organization to a Norwegian
• HelseID transitions
• multiple EHR systems in the same organization. journal-id will select the correct journal/SFM-instance, from otherwise equal tokens.
• and more

The token

The token must have a claim that is specific to SFM (SFM-id), and only have SFM as an audience.

There are two scopes that are relevant in SFM full:

 SFM portals and integrations: Scope: e-helse:sfm.api/sfm.api, Description: Used for SFM Portals, SFM Data Sharing API and SFM Basis API.

• SFM migration: Scope: e-helse:sfm.api/sfm-migrering.api, Description: Used for the first time uploading patient and business data from the EPR 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 or Kjernejournal. The token will then contain information about the original client, about the SFM that has exchanged the token and audience to provide access to the Prescription Broker's API.

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.
• SFM full version with GUI client must create a session against SFM with the endpoint: /api/Session/create
• SFM full version with GUI client must be refreshed with a new token when the EHR has done a refresh.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. Session here is a link between accesstoken and cookie. A user can create a session from many machines and it works for the user in all browsers until he chooses to log out on one of the machines. Then there is a requirement to end the session and the EPJ sends 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 from SFM fails. The EPJ must then create a new session and start the browser again so that the user can 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 - allways containing the top level of an organization, or "etat" in a norwegian kommune. Similar field for orgnr_child is optional. SFM will first try to match the lower level
• helseid://claims/identity/pid - national id of person logged in. Appears together with at least one of the two level indicatiors for strong identity
• helseid://claims/identity/security_level must be 4
• helseid://claims/identity/assurance_level must be high
• helseid://claims/client/client_tenancy is multi, single or missing, in case 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 as issuer an expiration are all a part of token validation.