Learn about HelseID
Basics
This section gives you a brief overview of a few basic terms and expressions in HelseID.
You will find links to relevant specification in each section.
What is HelseID?
HelseID offers single sign-on user authentication for clients, machine-to-machine authentication – and protection of services in the healthcare sector.
Using well established security standards as OAuth 2.0 and OpenID Connect 1.0 , HelseID is contributing to establish trust between between different organizations in the sector.
With NHN and HelseID as a trusted third party, the organizations do not have to trust each other directly.
HelseID issues access tokens which give access to services as Summary care record (Kjernejournal), The Person API (Persontjenesten), and many more.
graph TD;
SFM & Kjernejournal & Persontjenesten & ... -- Trust --- HelseID
You will find more information about HelseID in the following sections, and at nhn.no . You can also discover links to relevant security specifications and standards.
Let us begin with the basics with clients and APIs, also known as services.
What is an IdP?
IdP is short for Identity Provider, which is a service who has knowledge of a digital identity you have. In the context of HelseID, the identity is your personal identity number (pid). An identity provider lets you prove that you are allowed to use your pid in a digital context.
Identity providers like BankID, Buypass and Commfides offer authentication at the highest level of security, while for example MinID "only" offers a so-called substantial level.
Read more about security levels at the Norwegian Digitalisation Agency
What is a client?
A client is used to connect a piece of software to HelseID, and is necessary for user login or calling APIs.
The client can have access to one or more API scopes, which indicates the services it can interact with.
A HelseID client is, in short, a unique identifier which is registered in HelseID. It needs to be paired with a corresponding authentication key, because only the owner of the client should be able to use it.
This is called a confidential client, which is the only client type allowed by HelseID.
Multitenancy
A "normal" HelseID client can only represent one organization, called a main entity (hovedenhet) in the Central Coordinating Register for Legal Entities (Enhetsregisteret). A main entity is an enterprise at the highest level in the aforementioned register. A client created for a specific clinic is limited to representing the clinic's organization number in HelseID.
This is called a single-tenant pattern.
If Helseplattformen were to have one client for Ålesund, and one for St. Olavs, the number of clients might eventually be challenging to maintain independently.
This is where multitenancy comes into the picture. A multi-tenant client can represent multiple main entities in HelseID.
In order to allow Helseplattformen to represent them, St. Olavs hospital and Ålesund hospital have to delegate the right to do so through Altinn.
Read more about client patterns in HelseID's documentation in the developer portal
Read about delegating in Altinn on nhn.no
What is an API?
API is short for Application Programming Interface. It is an application specifically designed for the purpose of being used by other applications – not human users. It can also be a part of an application which provides a graphical user interface as well.
Examples of services: The Person API (Persontjenesten) only provides an API, while Summary care record (Kjernejournal) and SFM also provide graphical user interfaces.
An API is also called a service, as it suits a natural language, and addresses a bigger organizational perspective.
APIs connect separate computer systems in so-called integrations.
What is a scope?
Scopes can be used for several things, but let us limit the scope (no pun intended) to API scopes in this context. Any service (API) needs to define at least one scope, which is a unique name, for instance nhn:kjernejournal/api.
An API scope occurs as the value of the claimet scope in access tokens.
A client can have access to one or more API scopes. This implies which services the client can use. A scope can also be limited to a part of a service.
It is important to remember that every service has its own access control, meaning that it is not always enough to have access to a scope to get access to the desired data. But it is a prerequisite.
Some scopes are automatically granted just by requesting them in Self-service for HelseID. Others require approval from the service provider, while some are automatically approved if the corresponding terms of use are signed. Self-service for HelseID guides you through this.
What is a claim?
A claim is a piece of information that is located in ID-Tokens and access token.
A claim might:
- state the personal identifier or the name of the logged in user
- describe security details about the authentication
- state the organization number for the unit the client is representing
- contain data for the trust framework
- describe other details about the client, organization or end user, and more
Read more about claims in HelseID's documentation in the developer portal
Details about claims are found in the specifications for OpenID Connect Core 1.0 and JSON Web Token (JWT)
Check your knowledge about the basics in HelseID
Tokens
Tokens can be viewed as essential data documents for the interaction between HelseID, clients and services.
With the exception of refresh tokens, all tokens from HelseID are on the format of JWT (Json Web Token)
A JWT is divided in three parts consisting of a header, a payload and a signature. The signature ensures two things:
- The contents of the token cannot be modified without it being noticed
- It is possible to verify who signed the token, which is HelseID
You can read more about the various tokens in the following sections, and get links to relevant specifications.
The diagram below shows how access tokens and ID-tokens, access tokens and refresh tokens work together.
sequenceDiagram
actor X as End user
participant A as EHR
participant B as HelseID
participant C as Kjernejournal (example)
X ->> A: Wants to access information
A -->> X: Redirecting to HelseID for login
X ->> B: Logs in through an identity provider as for example BankID
A ->> B: Requests ID token, access token and refresh token
B -->> A: Requested tokens
A -->> A: Storing the ID token for own use
A ->> C: Requesting data with access token attached
C -->> C: Validating access token
C -->> A: Requested data
A -->> A: After a certain time the access token will eventually expire
A ->> B: Uses refresh token to request a new access token
B -->> A: A new access token
X ->> A: Logs out
A ->> B: Submits the ID token if HelseID is to redirect the user after logout
B -->> X: Sends the user back to the EHR
X ->> A: Gets confirmation of logoutWhat is an access token?
An access token is an admission pass to get access to something, for example a service like SFM or Kjernejournal. It contains claims of interest to the recipient.
By validating that the access token is cryptographically signed by HelseID, the recipient can trust that the token has been issued by HelseID.
An access token must only be shared with the intended recipient, that means the relevant service. It must not be sent to other services. If so, it should be rejected by the other services.
An access token from HelseID will always, among other things, contain information about:
- Which recipient the token is intended for – also called audience
- Scopes, which in this context usually mean what parts of the service can be accessed
- Which HelseID client the token was issued to
- Who issued the token and cryptographically signed it
- How long the token is valid
The token might contain information about:
- The end user's identity
- Whether the user authentication is of the highest level, which only BankID, Buypass or Commfides can offer
- Additional claims about the end user or the HelseID client
What is an ID token?
An ID token is proof that the end user has been identified and authenticated.
The ID token is only intended for the application that the user is using directly, for example an electronic health record (EHR) system.
It is not to be sent to other applications or services.
When the user is logging out, HelseID will not redirect the end user anywhere unless the ID token is attached to the logout request.
The ID token contains, among other things, information about:
- Who the end user is
- Who issued the token and cryptographically signed it
- How long the token is valid
What is a refresh token?
A refresh token is bound to a user login. It is used to fetch new access tokens without having to redirect the end user to HelseID for reauthentication.
The token is normally valid for several hours, typically a long working day – ensuring that the end user should not have to reauthenticate multiple times a day.
When the refresh token is no longer valid, the end user has to reauthenticate.
A refresh token is a generated value that is not readable for a human being.
What is DPoP?
A "normal" access token is a so called bearer token, meaning that anyone who is in possession of the token can use it – even if it does not belong to them.
DPoP is an abbreviaton for Demonstrating Proof of Possession, an approach that requires whoever trying to use an access token must prove they are the righteous possessor of it.
The party that requests an access token from HelseID attaches a public key to the request which HelseID binds to the token. By doing that, it will not be possible to use the token without attaching proof of being in possession of the corresponding private key.
When the access token is used, a DPoP proof must be attached to the request to service which is the recipient. The proof can be used only once, and is limited to a specific resource path. The recipient verifies that the proof is valid and in compliance with the key the access token is bound to.
sequenceDiagram
participant A as Client
participant B as HelseID
participant C as Kjernejournal (example)
A ->> B: Requests an access token and sends a public key
B -->> B: Binds public key to access token
B -->> A: Access token bound to public key
A -->> A: Makes DPoP proof
A ->> C: Access token with DPoP proof
C -->> C: Verifying DPoP proof
A -->> A: Makes new DPoP proof for a new request
A ->> C: Access token with new DPoP proof
C -->> C: Verifying DPoP proofRead more about DPoP in HelseID's documentation in the developer portal
Authentication
This section gives you a brief overview of a few terms and expressions regarding authentication.
You will find links to relevant specification in each section.
Client Credentials
Client Credentials is used to authenticate a client with HelseID, machine-to-machine, without involving a human user.
Access tokens are retrieved from HelseID in this context. ID-tokens are connected to a human user, and do not apply. Refresh tokens are bound to a user login and are not necessary in a machine-to-machine scenario.
Read about the Token endpoint in HelseID's documentation in the developer portal
Details about Client Credentials are found in specification RFC 6749
Authorization Code Flow
Authorization Code Flow is a mechanism for user login.
When the user has logged in, depending on settings and requirements, the client can retrieve an ID-token, an access token and a refresh token from HelseID.
Must be considered in relation to PKCE, PAR and DPoP.
Read about the Authorize endpoint in HelseID's documentation in the developer portal
Details about Authorization Code Flow are found in the specification for OpenID Connect Core 1.0
What is PKCE?
PKCE is short for Proof Key for Code Exchange, pronounced "pixie", and is supplementing Authorization Code Flow to improve the security.
When the user authentication has completed, the client receives an authorization code from HelseID. This is to be used to retrieve tokens, for instance an access token.
Without using PKCE anyone who gets a hold of the authorization code can use it. This is why HelseID requires the use of PKCE to prove righteous possession of the authorization code.
What is PAR?
PAR (Pushed Authorization Requests) is used to send less data through the browser when a user is logging in.
The client has to send data to HelseID through a service call before the end user is redirected to log in. The purpose is to improve the security by not letting an attacker see parameters in the browser, and potentially modify them.
Moving parameters from the front to the back channel also reduces the length of the url for the browser. Without PAR the url can in some cases get long enough to create problems with limitations in some browsers or recipients.
Read about the PAR endpoint in HelseID's documentation in the developer portal
Resource Indicators
A client has to use separate access tokens for the APIs A and B. When a user is logged in, the client can request an access token for API A. However, when the client needs an access token for API B, the end user has to be redirected back to HelseID. This is not seamless, and can be experienced as impractical.
Resource Indicators is a mechanism that enables a client to use multiple APIs seamlessly for the end user.
Resource Indicators allow the client to request resources, connected to scopes, where each API is one resource. This enables the client to use a refresh token to request separate access tokens for each API, without having to redirect the end user after the initial login.
Read more about Resource Indicators in HelseID's documentation in the developer portal
Details about Resource Indicators are found in specification RFC 8707
Token Exchange
If service A wants to use service B, then client credentials can be used with HelseID to achieve that.
This will lead to a machine-to-machine relationship between service A and B, without any end user involved.
Let us picture a scenario where an end user is logged into an EHR system through HelseID. The EHR calls service A, which subsequently calls service B. The latter service wants information about who originally is requesting data, none other than the human end user. The reason might be necessary audit logging or access control.
In this case, something more advanced than client credentials is needed; Token Exchange. When service A receives an access token from the EHR, this token will contain information about the end user if service A requires it. This token cannot be used directly against service B, because it is meant for service A.
Token Exchange allows service A to exchange the token via HelseID, and get an access token for service B in return. This new token will contain information about the end user who service A is acting on behalf of.
Read more about Token Exchange in HelseID's documentation in the developer portal
Details about Token Exchange are found in specification RFC 8693
Guidelines for choosing client type
As a system provider, you shall ensure that the integration with HelseID does not introduce unnecessary complexity for the users of the software.
During the code review of a new system in HelseID, we will not accept that you have chosen a solution that is convenient for you but technically challenging for the users.
You must not transfer the complexity to your users. This will lead to delays in the use of the system, and consequently in the use of the services secured by HelseID. In addition, it poses a security risk if, for example, users are required to handle cryptographic keys themselves.
Therefore, we have established clear guidelines for how the integration with HelseID should be implemented.
Will the system be used by multiple different organizations?
If your system will represent multiple distinct legal entities in Enhetsregisteret when interacting with HelseID, you are generally expected to implement a multi-tenant solution. This is typically a centralized web application where you keep track of which organization an end user represents. Helseplattformen is an example of such a system.
If you have a thick client that needs to be installed at the user sites, you must use a client template and automatically create separate single-tenant clients for your consumers via our API
Will the system be used by only one organization?
Choose single-tenant. Helsenorge is an example of such a system. It is only intended to represent Norsk helsenett towards HelseID and associated services.
Onboardingguide for suppliers
When you have created a client system in production it is time to onboard your customers. To do this in a smooth and painless way we recommend that you read this chapter to understand what HelseID offers in terms for onboarding.
For suppliers of multitenant-solutions
For suppliers with multitenant-solution the requirement is that your customer delegates a right to you via Altinn. Read more about this on NHN.no (norwegian link): Delegering av rettigheter i HelseID til databehandler
For suppliers of thick clients
A thick client is an application that runs locally on the end users machine, or locally installed at the customer/healthbusiness. An application like this needs a HelseID-client for each healthbusiness.
It can be difficult for non-technical users to set up HelseID-clients, and because of this HelseID Selvbetjening makes it possible for you as suppliers to take more control, and makes you able to shield your customers and users from technical details.
To create clients on behalf of your customers you can use our Selvbetjening API for a completely automatic setup.
For simplicities sake we will refer to the customer as general practicioner (GP) and a system/application as Electronic Patient Journal (EPJ). These are examples.
Complete automation using API
All the complexity is handled "behind the scenes" in the EPJ, so the GP only needs to confirm the configuration in Selvbetjening for HelseID.
The person at the healthbusiness who confirms the configuration must be manager, or get the delegation "Ta i bruk HelseID for et fagsystem" via Altinn. There is functionality in HelseID Selvbetjening that can assist users to ask for the correct delegation.
The EPJ will automatically update the keypairs before they expire.
Implementation guide for clients
When implementing an integration with HelseID for a client, it is necessary to comply with HelseID's security profile .
Before your application can be deployed to production in HelseID, you have to go through quality assurance and code review in collaboration with the HelseID team.
As a supplement to the security profile, we outline the most common issues that are discovered during code review here.
Note that issues uncovered during the code review will lead to delays in the production deployment process on your part.
Authentication
Will human end users log in through the client and be represented in HelseID?
If yes, the client must use Authorization Code Flow with PKCE, and PAR.
If no, the client will use a machine-to-machine pattern with Client Credentials.
Tenancy
If you have a multi-tenant client, you can read about how to specify organization numbers to HelseID in the developer portal
API integrations
If a client is going to call an API, it has to ask for the necessary scopes for the API.
Note: If the API requires DPoP, the client has to comply.
If the client will call multiple APIs, this is easy to achieve with Client Credentials: Separate access tokens are requested per API, specifying only the relevant scopes for one API at a time.
For Authorization Code Flow things get a bit more complicated.
- The end user is redirected to HelseID requesting scopes for API B, and is redirected back to the client's application
- The client uses a mechanism called Resource Indicators
Common issues
Here are a few tips on how to successfully implement a client correctly.
The points are based on the most common issues that are discovered during code review.
-
Do not implement protocol support yourself. Use industry standard security libraries for your plattform.
Make sure to upgrade your security libraries to the latest stable version.
-
Do not look at the content of access tokens – they are not meant for the client, and are to be sent to APIs. There is no guarantee that access tokens will be unencrypted jwts in the future, or that claims will not be renamed. If your code is depending on being able to read the content of an access token, potential changes might break your application.
You are not meant to look at the exp claim in an access token to know how long it is valid. Look at the expires_in parameter in the response from HelseID.
- Remember to cache access tokens according to the expires_in parameter in the response from HelseID. Many security libraries have built-in support for caching. When you are in possession of a valid token, requesting a new access token for each API request is not acceptable practice. The reason for this is to avoid unnecessary load on HelseID's infrastructure.
- Are you confident that your end users should be encouraged to log out? HelseID is an SSO solution, and a logout can lead to end users having to log in again to be able to use other applications. Conduct a thorough analysis of the ripple effects of logging out of HelseID.
- The validity of ID tokens do not affect the validity of the user session, where the latter usually expires after 10 hours. Do not use refresh tokens to renew the ID tokens. Refresh tokens are used to request new access tokens, not ID tokens.
Sample code
You will find sample code in HelseID.Samples on GitHub
Implementation guide for API
When implementing validation of access tokens issued by HelseID it is necessary to comply with HelseID's security profile
Types of access tokens
HelseID requires that all new APIs support DPoP. You can choose to support both Bearer and DPoP tokens at the same time, but because of potential downgrade attacks you need to set up separate endpoints for the different token types. More information about this can be found in the developer portal
Validation of audience
The audience ("aud" in the access token) says who the access token is meant for. In HelseID the 'aud' field is set to the API's short name. It is important to validate the field, and it is important to validate that only your audience is set in the audience field. This is to limit the damage of a potentially leaked token. (Note: Double check that your OAuth library checks this. Default behaviour for most libraries is to allow multiple audiences, but this is not allowed in HelseID's security profile.
Claims
Claims are information included in an access token. The claims can contain information about the user, the organization and/or the system that is behind the session in HelseID. The claims are inserted into the access token by HelseID when a client asks for an access token. A complete list of claims supported by HelseID can be found in the developer portal . Here you will also find information about where the values in the various claims are from. The claims that should be included in access tokens to your API can be configured in Self-service for HelseID.
User login
Some claims are only available if the login session is for an end user, and not a system. If your API requires a logged in user, only clients using authorization code can use your API. When a machine logs on using client credentials, no information about the end user is available.
Scopes
To manage which clients can access which endpoints in your API you can utilize scopes. When a client asks HelseID for an access token, HelseID will check whether the client has access to the requested scopes. The access token will reflect which scopes the client asked for. You can configure your scopes in Self-service for HelseID, and set up which claims are included for different scopes.
Token Exchange
If your API needs to call another API, and this API needs a user login or some other context from further up the call chain, then token exchange is something to consider.
Documentation for HelseID
You can find more detailed documentation for HelseID in the developer portal