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 in the developer portal
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 claim 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 manual 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 tokens.
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, klienter og tjenester.
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, 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
Details for DPoP are found in specification RFC 9449
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
Details about PAR are found in specification RFC 9126
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
Implementation guide for clients
When implementing an integration with HelseID for a client, it is necessary to comply with HelseID's security profile.
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
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.